Reference · 03

Schemas and failures.

Validators whose types flow into methods, records and clients, and the structured failures callers receive.

Schemas

v builds runtime validators. Their types flow into method arguments, records, keys, queue payloads and clients. Import it from @flower-js/sdk.

API	Contract
`v`	A frozen object of the validators below.
`v.string({ min?, max?, pattern? })`	A string, with optional length bounds and a `RegExp` (its `g` and `y` flags are ignored).
`v.number({ min?, max?, integer? })`	A finite number. `integer: true` requires a safe integer.
`v.int({ min?, max? })`	A safe integer.
`v.boolean()`, `v.null()`	Exactly a boolean, or `null`.
`v.literal(value)`	One string, number, boolean or `null`.
`v.enum([...values])`	One of several strings or numbers.
`v.array(item, { min?, max? })`	An array of `item`, with optional length bounds.
`v.tuple([...items])`	An array of exactly these items. The usual key schema.
`v.object(shape, { rest? })`	A plain object with these properties. Unknown properties are rejected unless `rest` validates them.
`v.optional(schema)`	Marks an object property as optional. Only valid inside `v.object` shapes.
`v.nullable(schema)`	The schema, or `null`.
`v.union(...schemas)`	Any of the schemas. A failure reports the alternative that got furthest.
`v.record(item, { key? })`	An object with any keys, every value matching `item`; `key` can check the keys.
`v.json()`	Any JSON value: finite numbers, no cycles, at most 128 levels deep.
`v.refine(schema, predicate, reason)`	The schema, plus a check that fails with `reason`.
`v.lazy(() => schema)`	A schema resolved on first use, for recursive shapes.
`Schema<T>`	Readonly `kind: "schema"` and `description`; `parse(value)` returns the value unchanged or throws `ValidationError`; `is(value)` returns a boolean. Also a Standard Schema.
`StandardSchema<T>`	The Standard Schema v1 contract. Any synchronous implementation, such as zod, works wherever Flower takes a schema; asynchronous ones throw `TypeError`.
`SchemaLike<T>`	`Schema<T> \| StandardSchema<T>`: what every `args`, `payload`, `result` and collection option accepts.
`Optional<T>`	What `v.optional` returns: readonly `kind: "optional"` and `schema`.
`Infer<S>`	The TypeScript type a schema validates.
`ObjectOf<Shape>`	The type of `v.object(shape)`: optional properties become `?:`.
`ValidationError`	Thrown by `parse`: an `Error` with `reason` (such as `must be at most 4`), `path`, and a message that joins them: `lines[0].quantity: must be at most 4`.
`SchemaPath`	`readonly (string \| number)[]`: property names and array indexes from the root.

Schemas outside methods

import { v, ValidationError, type Infer } from "@flower-js/sdk";

const topping = v.enum(["mushroom", "olive", "basil"]);
const pizza = v.object({ size: v.int({ min: 20, max: 40 }), toppings: v.array(topping, { max: 5 }) });
type Pizza = Infer<typeof pizza>; // { size: number; toppings: ("mushroom" | "olive" | "basil")[] }

try {
  pizza.parse({ size: 30, toppings: ["pineapple"] });
} catch (error) {
  if (error instanceof ValidationError) console.log(error.message); // toppings[0]: must be one of "mushroom", "olive", "basil"
}

Schemas check values; they never transform them. parse returns its input.
Only the first problem is reported.
Where a schema checks method arguments, a failure becomes INVALID_ARGUMENT before your code runs.

Failures

API	Contract
`fail(code, message, details?): never`	Aborts the callback with a failure. `code` must be `UPPER_SNAKE_CASE` and `details` must be JSON, or it throws `TypeError` instead. A failing mutation commits nothing.
`Failure`	Readonly `code`, `message` and optional `details`: what callers receive as `FlowerError.failure`, what `task` error handlers get, and what failed timers store.

Over HTTP, a failing method answers 422 with {"error":{"code":"EVALUATION_FAILED","message":"CODE: message","failure":{"code","message","details"}}}. A failure from an access check arrives as 403 FORBIDDEN, and one from a transaction participant as 422 TRANSACTION_ABORTED, each with its failure. Watch error events carry it too. A plain throw becomes COMPUTE_ERROR with the error's message. Details thrown inside a derived value aren't kept.

Built-in failure codes

Code	Meaning
`INVALID_ARGUMENT`	Arguments failed the method's `args` schema, or a queue payload, queue result or external result failed its schema. `details: { path }`.
`INVALID_RECORD`	A write failed the collection's record schema. `details: { collection, key, path }`.
`INVALID_KEY`	A key failed the collection's key schema, or a string-keyed collection got a non-string key.
`INVALID_SCAN`	Key bounds on a typed-key collection, or a malformed prefix.
`INVALID_VALUE`	A callback returned or stored something that isn't JSON.
`COMPUTE_ERROR`	Your code threw an ordinary error.
`EVALUATION_BUDGET`	The call ran out of time or memory.
`DEFINITION_MISSING`	A derived value or method isn't registered. List derived values in `definitions`.
`TRIGGER_LOOP`	Triggers kept changing records for 32 rounds.
`UNAUTHENTICATED`, `FORBIDDEN`	An access check refused the call (HTTP 403).
`LEASE_LOST`, `LEASE_TOO_LONG`, `JOB_EXISTS`, `JOB_NOT_FAILED`	Queue rules.
`TIMER_NOT_FAILED`, `SCHEDULER_HANDLER_MISSING`	Scheduler rules.
`UNDECLARED_INDEX`	Test databases only: an index read on an undeclared index. See Testing.