@thomasfosterau/effect-forms 0.2.0 → 0.3.1

package/dist/index.js

@@ -1,8 +1,14 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
+import * as Arr from "effect/Array";
+import * as Exit from "effect/Exit";
+import * as Match from "effect/Match";
+import * as Predicate from "effect/Predicate";
+import * as Rec from "effect/Record";
 import * as Schema from "effect/Schema";
 import * as SchemaAST from "effect/SchemaAST";
-import * as Effect from "effect/Effect";
 import * as SchemaParser from "effect/SchemaParser";
+import * as Option from "effect/Option";
+import * as Effect from "effect/Effect";
 import * as SchemaIssue from "effect/SchemaIssue";
 import * as Duration from "effect/Duration";
 //#region src/Coerce.ts
@@ -55,7 +61,7 @@ function trimToNull(value) {
 }
 function numberFromField(raw, { nullable }) {
 	const coerced = nullable ? emptyToNull(raw) : emptyToUndefined(raw);
-	return typeof coerced === "string" ? Number(coerced) : coerced;
+	return coerced === void 0 || coerced === null ? coerced : Number(coerced);
 }
 /**
 * Interpret a checkbox field. An HTML checkbox submits its `value` (default
@@ -110,23 +116,21 @@ var Command_exports = /* @__PURE__ */ __exportAll({
 	plan: () => plan,
 	updateAdapter: () => updateAdapter
 });
+/** A command field {@link plan} cannot classify into any {@link FieldKind}. */
+var UnclassifiableFieldError = class extends Schema.TaggedError()("UnclassifiableFieldError", { message: Schema.String }) {};
+/** A malformed `jsonArray` field payload, as {@link jsonRowsFromField} rejects it. */
+var InvalidJsonRowsError = class extends Schema.TaggedError()("InvalidJsonRowsError", { message: Schema.String }) {};
 /**
 * Run one decode probe: whether the schema accepts the input, plus the decoded
 * value for instance checks (the date probe needs to see a `Date` come out,
 * not just a successful decode).
 */
 const probe = (schema, input) => {
-	try {
-		return {
-			ok: true,
-			value: Schema.decodeUnknownSync(schema)(input)
-		};
-	} catch {
-		return { ok: false };
-	}
+	const decoder = schema;
+	return SchemaParser.decodeUnknownExit(decoder)(input);
 };
-/** True when a schema decodes the given input without throwing. */
-const decodes = (schema, input) => probe(schema, input).ok;
+/** True when a schema decodes the given input without failing. */
+const decodes = (schema, input) => Exit.isSuccess(probe(schema, input));
 /** A syntactically valid UUID no other field kind accepts as non-text. */
 const PROBE_UUID = "9f8c1c2e-4b3a-4c5d-8e6f-0a1b2c3d4e5f";
 /**
@@ -141,13 +145,10 @@ const PROBE_UUID = "9f8c1c2e-4b3a-4c5d-8e6f-0a1b2c3d4e5f";
 * `enumOptions` below needs the full literal set, not just one branch of it.
 */
 function unwrapWrapperUnion(ast) {
-	let current = ast;
-	while (SchemaAST.isUnion(current)) {
-		const real = current.types.filter((t) => !SchemaAST.isUndefined(t) && !SchemaAST.isNull(t));
-		if (real.length !== 1 || real.length === current.types.length) break;
-		current = real[0];
-	}
-	return current;
+	if (!SchemaAST.isUnion(ast)) return ast;
+	const real = Arr.filter(ast.types, (t) => !SchemaAST.isUndefined(t) && !SchemaAST.isNull(t));
+	if (real.length !== 1 || real.length === ast.types.length) return ast;
+	return unwrapWrapperUnion(real[0]);
 }
 /**
 * The literal option values of a field shaped like `Schema.Literal(...)` or
@@ -160,8 +161,8 @@ function enumOptions(ast) {
 	const inner = unwrapWrapperUnion(ast);
 	if (SchemaAST.isLiteral(inner)) return [String(inner.literal)];
 	if (SchemaAST.isUnion(inner)) {
-		const literals = inner.types.filter(SchemaAST.isLiteral);
-		if (literals.length === inner.types.length && literals.length > 0) return literals.map((literal) => String(literal.literal));
+		const literals = Arr.filter(inner.types, SchemaAST.isLiteral);
+		if (Arr.isReadonlyArrayNonEmpty(literals) && literals.length === inner.types.length) return Arr.map(literals, (literal) => String(literal.literal));
 	}
 }
 /**
@@ -187,7 +188,7 @@ const probeKind = (schema) => {
 	if (decodes(schema, true)) return "boolean";
 	if (decodes(schema, 42)) return "number";
 	const date = probe(schema, "2024-01-02T03:04:05.000Z");
-	if (date.ok && date.value instanceof Date) return "date";
+	if (Exit.isSuccess(date) && date.value instanceof Date) return "date";
 	if (decodes(schema, PROBE_UUID) && !decodes(schema, "not-a-uuid")) return "id";
 	if (decodes(schema, "plain text")) return "text";
 };
@@ -214,7 +215,7 @@ const classify = (key, schema) => {
 	const probed = probeKind(schema);
 	if (probed !== void 0) return { kind: probed };
 	if (isStructured(schema.ast)) return { kind: "structured" };
-	throw new Error(`Command.plan: field "${key}" matches no known kind (text/id/number/date/jsonArray/boolean/enum/structured) — a Schema.declare'd type needs an explicit form-level treatment before it can derive`);
+	throw new UnclassifiableFieldError({ message: `Command.plan: field "${key}" matches no known kind (text/id/number/date/jsonArray/boolean/enum/structured) — a Schema.declare'd type needs an explicit form-level treatment before it can derive` });
 };
 /**
 * Read a create/update command struct pair into a {@link CommandPlan}.
@@ -224,22 +225,23 @@ const classify = (key, schema) => {
 const plan = (create, update) => {
 	const createFields = create.fields;
 	const updateFields = update.fields;
-	const keys = [];
-	for (const key in updateFields) if (key !== "id") keys.push(key);
-	for (const key in createFields) if (key !== "id" && !(key in updateFields)) keys.push(key);
+	const keys = [...Arr.filter(Rec.keys(updateFields), (key) => key !== "id"), ...Arr.filter(Rec.keys(createFields), (key) => key !== "id" && !(key in updateFields))];
 	return {
-		fields: keys.map((key) => {
+		fields: Arr.map(keys, (key) => {
 			const createField = createFields[key];
 			const updateField = updateFields[key];
 			const { kind, options } = classify(key, createField ?? updateField);
-			return {
+			const fieldPlan = {
 				key,
 				kind,
 				inCreate: createField !== void 0,
 				createRequired: createField !== void 0 && !decodes(createField, void 0),
 				inUpdate: updateField !== void 0,
-				updateClearable: updateField !== void 0 && decodes(updateField, null),
-				...options !== void 0 ? { options } : {}
+				updateClearable: updateField !== void 0 && decodes(updateField, null)
+			};
+			return options === void 0 ? fieldPlan : {
+				...fieldPlan,
+				options
 			};
 		}),
 		clientId: "id" in createFields
@@ -253,17 +255,16 @@ const plan = (create, update) => {
 * "create") })`, with `overrides` spread last for irregular fields.
 */
 const formInputFields = (commandPlan, mode, overrides = {}) => {
-	const fields = {};
-	if (mode === "create" && commandPlan.clientId) fields.id = Schema.optional(Schema.String);
-	if (mode === "update") fields.id = Schema.String.check(Schema.isUUID());
-	for (const field of commandPlan.fields) {
-		if (mode === "create" ? !field.inCreate : !field.inUpdate) continue;
-		fields[field.key] = mode === "create" && field.createRequired ? Schema.String.check(Schema.isMinLength(1)) : Schema.optional(Schema.String);
-	}
-	return {
-		...fields,
-		...overrides
-	};
+	const idField = mode === "update" ? [["id", Schema.String.check(Schema.isUUID())]] : commandPlan.clientId ? [["id", Schema.optional(Schema.String)]] : [];
+	const planFields = Arr.flatMap(commandPlan.fields, (field) => {
+		if (mode === "create" ? !field.inCreate : !field.inUpdate) return [];
+		return [[field.key, mode === "create" && field.createRequired ? Schema.String.check(Schema.isMinLength(1)) : Schema.optional(Schema.String)]];
+	});
+	return Rec.fromEntries([
+		...idField,
+		...planFields,
+		...Rec.toEntries(overrides)
+	]);
 };
 /**
 * Blank string defaults for one mode's Form-Input shape. Client-id entities
@@ -271,13 +272,8 @@ const formInputFields = (commandPlan, mode, overrides = {}) => {
 * crypto.randomUUID() }`) so retries stay idempotent.
 */
 const blankDefaults = (commandPlan, mode) => {
-	const defaults = {};
-	if (mode === "update" || commandPlan.clientId) defaults.id = "";
-	for (const field of commandPlan.fields) {
-		if (mode === "create" ? !field.inCreate : !field.inUpdate) continue;
-		defaults[field.key] = "";
-	}
-	return defaults;
+	const keys = [...mode === "update" || commandPlan.clientId ? ["id"] : [], ...Arr.flatMap(commandPlan.fields, (field) => (mode === "create" ? field.inCreate : field.inUpdate) ? [field.key] : [])];
+	return Rec.fromEntries(Arr.map(keys, (key) => [key, ""]));
 };
 /**
 * Parse a JSON-encoded row list (a contributor list) from a multipart form
@@ -289,25 +285,28 @@ const blankDefaults = (commandPlan, mode) => {
 */
 const jsonRowsFromField = (raw, label) => {
 	if (raw === void 0 || raw.trim() === "") return void 0;
-	let parsed;
-	try {
-		parsed = JSON.parse(raw);
-	} catch {
-		throw new Error(`Invalid ${label} payload — expected JSON array`);
-	}
-	if (!Array.isArray(parsed)) throw new Error(`Invalid ${label} payload — expected array`);
-	return parsed.map((row, index) => {
-		if (typeof row !== "object" || row === null) throw new Error(`Invalid ${label} entry at index ${index}`);
-		const r = row;
-		if (typeof r.agentId !== "string") throw new Error(`${label} entry at index ${index} missing agentId`);
+	const decoded = decodeJson(raw);
+	if (Exit.isFailure(decoded)) throw new InvalidJsonRowsError({ message: `Invalid ${label} payload — expected JSON array` });
+	const parsed = decoded.value;
+	if (!Arr.isArray(parsed)) throw new InvalidJsonRowsError({ message: `Invalid ${label} payload — expected array` });
+	return Arr.map(parsed, (row, index) => {
+		if (!Predicate.isObjectOrArray(row)) throw new InvalidJsonRowsError({ message: `Invalid ${label} entry at index ${index}` });
+		const propertyOf = (key) => Predicate.hasProperty(row, key) ? row[key] : void 0;
+		const agentId = propertyOf("agentId");
+		if (!Predicate.isString(agentId)) throw new InvalidJsonRowsError({ message: `${label} entry at index ${index} missing agentId` });
+		const id = propertyOf("id");
+		const creditedName = propertyOf("creditedName");
+		const orderingPosition = propertyOf("orderingPosition");
 		return {
-			id: typeof r.id === "string" ? r.id : void 0,
-			agentId: r.agentId,
-			creditedName: typeof r.creditedName === "string" ? r.creditedName : void 0,
-			orderingPosition: typeof r.orderingPosition === "number" ? r.orderingPosition : index
+			id: Predicate.isString(id) ? id : void 0,
+			agentId,
+			creditedName: Predicate.isString(creditedName) ? creditedName : void 0,
+			orderingPosition: Predicate.isNumber(orderingPosition) ? orderingPosition : index
 		};
 	});
 };
+/** Parse a JSON text (`JSON.parse` semantics) to a success or a failed `Exit`. */
+const decodeJson = SchemaParser.decodeUnknownExit(Schema.fromJsonString(Schema.Unknown));
 /** Text fields: trim always; required create fields never skip. */
 const coerceText = (ctx, raw) => ctx.required ? (raw ?? "").trim() : ctx.clearable ? trimToNull(raw) : trimToUndefined(raw);
 /** Id fields: no trimming (pickers emit `""` or a UUID); required create FKs pass through raw. */
@@ -356,49 +355,66 @@ const coerceContextFor = (field, mode) => ({
 /** The default coercion for one field in one mode. */
 const coerce = (field, mode, raw) => {
 	const ctx = coerceContextFor(field, mode);
-	switch (field.kind) {
-		case "text":
-		case "enum": return coerceText(ctx, raw);
-		case "id": return coerceId(ctx, raw);
-		case "number": return coerceNumber(ctx, raw);
-		case "date": return coerceDate(ctx, raw);
-		case "jsonArray": return jsonRowsFromField(raw, field.key);
-		case "boolean": return coerceBoolean(ctx, raw);
-		case "structured": return structuredFromField(raw, ctx.clearable);
-	}
+	return Match.value(field.kind).pipe(Match.when(Match.is("text", "enum"), () => coerceText(ctx, raw)), Match.when("id", () => coerceId(ctx, raw)), Match.when("number", () => coerceNumber(ctx, raw)), Match.when("date", () => coerceDate(ctx, raw)), Match.when("jsonArray", () => jsonRowsFromField(raw, field.key)), Match.when("boolean", () => coerceBoolean(ctx, raw)), Match.when("structured", () => structuredFromField(raw, ctx.clearable)), Match.exhaustive);
 };
 /**
+* Adapt every field of `commandPlan` present in `mode`, in plan order, to a
+* `[key, value]` entry: through the field's override when it has one, else
+* the default {@link coerce}.
+*/
+const adaptFields = (commandPlan, overrides, mode, input) => Arr.flatMap(commandPlan.fields, (field) => {
+	if (mode === "create" ? !field.inCreate : !field.inUpdate) return [];
+	const override = overrides[field.key];
+	const raw = input[field.key];
+	return [[field.key, override ? override(raw) : coerce(field, mode, raw)]];
+});
+/**
 * Derive the create adapter: validated all-string input → encoded create
 * command payload. `overrides` replace the default per-field coercion for
 * genuinely irregular fields (e.g. a create-time fallback default).
 */
-const createAdapter = (commandPlan, overrides = {}) => (input) => {
-	const out = {};
-	if (commandPlan.clientId) out.id = trimToUndefined(input.id);
-	for (const field of commandPlan.fields) {
-		if (!field.inCreate) continue;
-		const override = overrides[field.key];
-		out[field.key] = override ? override(input[field.key]) : coerce(field, "create", input[field.key]);
-	}
-	return out;
-};
+const createAdapter = (commandPlan, overrides = {}) => (input) => Rec.fromEntries([...commandPlan.clientId ? [["id", trimToUndefined(input.id)]] : [], ...adaptFields(commandPlan, overrides, "create", input)]);
 /**
 * Derive the update adapter: validated all-string input → encoded update
 * command payload (value sets, `null` clears a clearable field, `undefined`
 * skips). The required `id` passes through as-is — the command's canonical
 * decode brands it.
 */
-const updateAdapter = (commandPlan, overrides = {}) => (input) => {
-	const out = { id: input.id };
-	for (const field of commandPlan.fields) {
-		if (!field.inUpdate) continue;
-		const override = overrides[field.key];
-		out[field.key] = override ? override(input[field.key]) : coerce(field, "update", input[field.key]);
-	}
-	return out;
-};
+const updateAdapter = (commandPlan, overrides = {}) => (input) => Rec.fromEntries([["id", input.id], ...adaptFields(commandPlan, overrides, "update", input)]);
 //#endregion
 //#region src/Constraints.ts
+/**
+* HTML input constraints derived from an Effect Schema.
+*
+* Native validation attributes can be read (`required`, `minlength`, …)
+* off the schema so a form can apply them to its inputs for free, layering
+* browser-native validation under the schema-driven validation. This module
+* does the framework-neutral half: walk the schema AST and emit an
+* {@link InputConstraints} tree a UI can spread onto its `<input>`s.
+*
+* `required` comes from a struct field's optionality; `minlength` /
+* `maxlength` / `min` / `max` / `pattern` / `step` are derived from the
+* `representation` annotation Effect Schema's built-in checks carry
+* (`isMinLength`, `isBetween`, `isPattern`, …), keyed by its stable
+* `effect/schema/<check>` id. A check with no recognised representation id
+* (a bare `Schema.filter` predicate, a custom `.check()`) contributes
+* nothing; there is no attribute to guess at,
+* so the derivation stays silent rather than wrong. The walk descends into
+* nested structs and into a homogeneous array's item type (folding the
+* array's own optionality into the item's `required`); a fixed-shape tuple
+* with differently-typed elements has no single item schema to represent as
+* one constraint, so it derives only `required`. Like
+* {@link module:effect-forms/Field}'s `fromAst`, an `optional` / `NullOr`
+* union is unwrapped by taking its first non-`null`/`undefined` member —
+* scoped to that wrapping pattern, not general discriminated unions, whose
+* branches can't be flattened into one constraint either. The `overrides`
+* argument to {@link constraintsFromSchema} remains the seam for anything the
+* walk cannot infer (or should not — a check that's semantically stronger
+* than any HTML attribute).
+*
+* @copyright Thomas Foster
+* @module effect-forms/Constraints
+*/
 var Constraints_exports = /* @__PURE__ */ __exportAll({
 	constraintAt: () => constraintAt,
 	constraintsFromSchema: () => constraintsFromSchema,
@@ -416,17 +432,15 @@ const isOptional = (type) => type.context?.isOptional === true;
 */
 function unwrapOptional(type) {
 	if (!SchemaAST.isUnion(type)) return type;
-	for (const member of type.types) {
-		if (SchemaAST.isUndefined(member) || SchemaAST.isNull(member)) continue;
-		return unwrapOptional(member);
-	}
-	return type;
+	return Arr.findFirst(type.types, (member) => !SchemaAST.isUndefined(member) && !SchemaAST.isNull(member)).pipe(Option.match({
+		onNone: () => type,
+		onSome: unwrapOptional
+	}));
 }
 /** Flatten a `Checks` array (recursing into `FilterGroup`s) into individual filters. */
-function flattenChecks(checks, out) {
-	if (!checks) return;
-	for (const check of checks) if (check._tag === "FilterGroup") flattenChecks(check.checks, out);
-	else out.push(check);
+function flattenChecks(checks) {
+	if (checks === void 0) return [];
+	return Arr.flatMap(checks, (check) => Predicate.isTagged(check, "FilterGroup") ? flattenChecks(check.checks) : [check]);
 }
 /**
 * One constraint patch per recognised representation id — the built-in
@@ -454,14 +468,18 @@ const payloadPatches = {
 	}),
 	"effect/schema/isMultipleOf": (p) => ({ step: p.divisor })
 };
+/** Whether `id` names a check {@link payloadPatches} has a patch for (an own key, never an inherited one). */
+const isPatchedCheckId = (id) => Rec.has(payloadPatches, id);
 /**
 * Look up and apply `payloadPatches[representation.id]`. The cast is sound:
 * each payload is authored by the same built-in check constructor its id
 * names, so an entry is never called with a mismatched payload shape.
 */
 function applyPayloadPatch(representation) {
-	const patch = payloadPatches[representation.id];
-	return patch?.(representation.payload);
+	const id = representation.id;
+	if (!isPatchedCheckId(id)) return void 0;
+	const patch = payloadPatches[id];
+	return patch(representation.payload);
 }
 /**
 * Derive an {@link InputConstraint}'s refinement attributes from the checks
@@ -472,25 +490,20 @@ function applyPayloadPatch(representation) {
 * filter) is skipped: there is no attribute to derive from it.
 */
 function constraintFromChecks(outer, inner) {
-	const filters = [];
-	flattenChecks(outer.checks, filters);
-	if (inner !== outer) flattenChecks(inner.checks, filters);
-	let out = {};
-	let hasIntCheck = false;
-	for (const filter of filters) {
+	const filters = inner === outer ? flattenChecks(outer.checks) : [...flattenChecks(outer.checks), ...flattenChecks(inner.checks)];
+	const representations = Arr.flatMap(filters, (filter) => {
 		const representation = filter.annotations?.representation;
-		if (!representation) continue;
-		if (representation.id === "effect/schema/isInt") {
-			hasIntCheck = true;
-			continue;
-		}
-		out = {
-			...out,
-			...applyPayloadPatch(representation)
-		};
-	}
-	if (hasIntCheck && out.step === void 0) out.step = 1;
-	return out;
+		return representation === void 0 ? [] : [representation];
+	});
+	const isIntCheck = (representation) => representation.id === "effect/schema/isInt";
+	const patched = Arr.reduce(representations, {}, (out, representation) => isIntCheck(representation) ? out : {
+		...out,
+		...applyPayloadPatch(representation)
+	});
+	return Arr.some(representations, isIntCheck) && patched.step === void 0 ? {
+		...patched,
+		step: 1
+	} : patched;
 }
 /**
 * Whether `ast` is a homogeneous array/list — `Schema.Array(item)` or
@@ -503,8 +516,10 @@ function constraintFromChecks(outer, inner) {
 function homogeneousItem(ast) {
 	if (ast.rest.length !== 1) return void 0;
 	const [item] = ast.rest;
-	if (ast.elements.length === 0) return item;
-	if (ast.elements.length === 1 && ast.elements[0] === item) return item;
+	return Arr.match(ast.elements, {
+		onEmpty: () => item,
+		onNonEmpty: (elements) => elements.length === 1 && elements[0] === item ? item : void 0
+	});
 }
 /**
 * Derive the constraint (or nested tree) for one property/item type: a
@@ -535,30 +550,43 @@ function constraintsForType(type) {
 }
 /** Build the constraint tree for one object AST node. */
 function constraintsForObjects(ast) {
-	const out = {};
-	for (const ps of ast.propertySignatures) out[String(ps.name)] = constraintsForType(ps.type);
-	return out;
+	return Rec.fromEntries(Arr.map(ast.propertySignatures, (ps) => [String(ps.name), constraintsForType(ps.type)]));
 }
 /** Deep-merge constraint overrides over a derived tree. */
 function mergeConstraints(base, overrides) {
-	const out = { ...base };
-	for (const key of Object.keys(overrides)) {
+	const merged = Arr.flatMap(Rec.keys(overrides), (key) => {
 		const override = overrides[key];
-		if (override === void 0) continue;
-		const existing = out[key];
-		if (existing !== void 0 && !isLeafConstraint(existing) && !isLeafConstraint(override)) out[key] = mergeConstraints(existing, override);
-		else if (existing !== void 0 && isLeafConstraint(existing) && isLeafConstraint(override)) out[key] = {
+		if (override === void 0) return [];
+		const existing = base[key];
+		if (existing !== void 0 && !isLeafConstraint(existing) && !isLeafConstraint(override)) return [[key, mergeConstraints(existing, override)]];
+		if (existing !== void 0 && isLeafConstraint(existing) && isLeafConstraint(override)) return [[key, {
 			...existing,
 			...override
-		};
-		else out[key] = override;
-	}
-	return out;
+		}]];
+		return [[key, override]];
+	});
+	return {
+		...base,
+		...Rec.fromEntries(merged)
+	};
 }
 /**
 * Derive the {@link InputConstraints} for a struct schema. Non-struct schemas
 * yield an empty tree. `overrides` (deep-merged over the derived tree, and
 * winning on conflict) is the seam for anything the AST walk does not infer.
+*
+* @example
+* ```ts
+* import * as Schema from "effect/Schema"
+* import { Constraints } from "@thomasfosterau/effect-forms"
+*
+* const Signup = Schema.Struct({
+*   name: Schema.String.check(Schema.isMinLength(2)),
+*   nickname: Schema.optional(Schema.String),
+* })
+* console.log(Constraints.constraintsFromSchema(Signup))
+* // { name: { required: true, minlength: 2 }, nickname: { required: false } }
+* ```
 */
 function constraintsFromSchema(schema, overrides = {}) {
 	const ast = schema.ast;
@@ -575,16 +603,34 @@ function constraintsFromSchema(schema, overrides = {}) {
 * skips the index and resolves straight to `label`'s derived constraint.
 */
 function constraintAt(constraints, path) {
-	let node = constraints;
-	for (const segment of path) {
-		if (typeof segment === "number") continue;
-		if (node === void 0 || isLeafConstraint(node)) return {};
-		node = node[segment];
-	}
+	const node = Arr.reduce(path, constraints, (current, segment) => {
+		if (Predicate.isNumber(segment)) return current;
+		if (current === void 0 || isLeafConstraint(current)) return void 0;
+		return current[segment];
+	});
 	return node !== void 0 && isLeafConstraint(node) ? node : {};
 }
 //#endregion
 //#region src/FormData.ts
+/**
+* Structured parsing of an HTML form body into a plain object the schema can
+* decode.
+*
+* Browsers flatten structured data into `name=value` pairs using bracket /
+* dot path notation (`author.name`, `author[name]`, `tags[0]`, `tags[]`).
+* {@link formDataToObject} reverses that into a nested object / array tree —
+* the framework-neutral step that turns a form body into structured data, before handing it
+* to a validator. Coercion (strings → numbers / booleans / dates) is then the
+* schema's job: decode the result with a schema built from coercing leaves
+* (`Schema.FiniteFromString`, `Schema.BooleanFromString`, the {@link
+* module:effect-forms/Coerce} helpers, …).
+*
+* `File` values pass through untouched; repeated bare keys collapse into an
+* array. The parser is total and never throws.
+*
+* @copyright Thomas Foster
+* @module effect-forms/FormData
+*/
 var FormData_exports = /* @__PURE__ */ __exportAll({
 	formDataToObject: () => formDataToObject,
 	parseFieldPath: () => parseFieldPath,
@@ -597,48 +643,56 @@ var FormData_exports = /* @__PURE__ */ __exportAll({
 * `"a.b[]"` → `["a","b",""]`.
 */
 function parseFieldPath(name) {
-	const tokens = [];
-	let buffer = "";
-	let inBracket = false;
-	for (const char of name) if (char === "[") {
-		if (buffer !== "") tokens.push(buffer);
-		buffer = "";
-		inBracket = true;
-	} else if (char === "]") {
-		tokens.push(buffer);
-		buffer = "";
-		inBracket = false;
-	} else if (char === "." && !inBracket) {
-		if (buffer !== "") tokens.push(buffer);
-		buffer = "";
-	} else buffer += char;
-	if (buffer !== "") tokens.push(buffer);
+	const nonEmpty = (buffer) => buffer === "" ? [] : [buffer];
+	const scanned = Arr.reduce(Arr.fromIterable(name), {
+		tokens: Arr.empty(),
+		buffer: "",
+		inBracket: false
+	}, ({ tokens, buffer, inBracket }, char) => {
+		if (char === "[") return {
+			tokens: [...tokens, ...nonEmpty(buffer)],
+			buffer: "",
+			inBracket: true
+		};
+		if (char === "]") return {
+			tokens: [...tokens, buffer],
+			buffer: "",
+			inBracket: false
+		};
+		if (char === "." && !inBracket) return {
+			tokens: [...tokens, ...nonEmpty(buffer)],
+			buffer: "",
+			inBracket
+		};
+		return {
+			tokens,
+			buffer: buffer + char,
+			inBracket
+		};
+	});
+	const tokens = [...scanned.tokens, ...nonEmpty(scanned.buffer)];
 	return tokens.length > 1 && tokens[0] === "" ? tokens.slice(1) : tokens;
 }
 const isIndexToken = (token) => token === "" || /^\d+$/.test(token);
 /** Create the container a token should live in: array for index/append tokens. */
 const makeContainer = (nextToken) => isIndexToken(nextToken) ? [] : {};
 const setOnContainer = (container, token, value) => {
-	if (Array.isArray(container)) {
+	if (Arr.isArray(container)) {
 		if (token === "") container.push(value);
 		else container[Number(token)] = value;
 	} else container[token] = value;
 };
-const getFromContainer = (container, token) => Array.isArray(container) ? container[Number(token)] : container[token];
+const getFromContainer = (container, token) => Arr.isArray(container) ? container[Number(token)] : container[token];
 /** Assign `value` deep into `root` along `tokens`, creating containers as needed. */
 function assign(root, tokens, value) {
-	let node = root;
-	for (let i = 0; i < tokens.length - 1; i++) {
-		const token = tokens[i];
-		const nextToken = tokens[i + 1];
-		let child = token === "" ? void 0 : getFromContainer(node, token);
-		if (child === void 0 || typeof child !== "object" || child === null) {
-			child = makeContainer(nextToken);
-			setOnContainer(node, token, child);
-		}
-		node = child;
-	}
-	const last = tokens[tokens.length - 1];
+	const last = Arr.lastNonEmpty(tokens);
+	const node = Arr.reduce(Arr.initNonEmpty(tokens), root, (parent, token, i) => {
+		const child = token === "" ? void 0 : getFromContainer(parent, token);
+		if (Predicate.isObjectOrArray(child)) return child;
+		const created = makeContainer(tokens[i + 1]);
+		setOnContainer(parent, token, created);
+		return created;
+	});
 	if (last !== "" && !Array.isArray(node)) {
 		const existing = getFromContainer(node, last);
 		if (existing !== void 0) {
@@ -651,27 +705,35 @@ function assign(root, tokens, value) {
 	setOnContainer(node, last, value);
 }
 /** Normalise a source into `[name, value]` entries. */
-function* entriesOf(source) {
-	if (typeof source[Symbol.iterator] === "function" && !(source instanceof FormData) && !(source instanceof URLSearchParams)) {
-		yield* source;
-		return;
-	}
-	for (const entry of source.entries()) yield entry;
+function entriesOf(source) {
+	if (source instanceof FormData || source instanceof URLSearchParams) return source.entries();
+	return source;
 }
 /**
 * Parse a form body into a nested object / array tree. Field names use dot or
 * bracket path notation (see {@link parseFieldPath}); repeated bare keys
 * become arrays; `File` values pass through. The result is ready to hand to
 * `Schema.decodeUnknown` with a schema whose leaves coerce the string inputs.
+*
+* @example
+* ```ts
+* import { FormData } from "@thomasfosterau/effect-forms"
+*
+* const body = new URLSearchParams([
+*   ["author.name", "Ada"],
+*   ["tags[]", "math"],
+*   ["tags[]", "engines"],
+* ])
+* console.log(FormData.formDataToObject(body))
+* // { author: { name: "Ada" }, tags: ["math", "engines"] }
+* ```
 */
 function formDataToObject(source) {
-	const root = {};
-	for (const [name, value] of entriesOf(source)) {
+	return Arr.reduce(entriesOf(source), Rec.empty(), (root, [name, value]) => {
 		const tokens = parseFieldPath(name);
-		if (tokens.length === 0) continue;
-		assign(root, tokens, value);
-	}
-	return root;
+		if (Arr.isReadonlyArrayNonEmpty(tokens)) assign(root, tokens, value);
+		return root;
+	});
 }
 /** Read and parse a `Request`'s form body. Errors (e.g. wrong content-type) reject. */
 async function requestToObject(request) {
@@ -720,32 +782,41 @@ var Path_exports = /* @__PURE__ */ __exportAll({
 * traverses a non-object. The empty path returns the object itself.
 */
 function getAt(obj, path) {
-	let current = obj;
-	for (const segment of path) {
-		if (current === null || typeof current !== "object") return void 0;
-		current = current[segment];
-	}
-	return current;
+	return Arr.reduce(path, obj, (current, segment) => Predicate.isObjectOrArray(current) && Predicate.hasProperty(current, segment) ? current[segment] : void 0);
 }
 /**
 * Return a new tree with the value at `path` replaced by `value`. Objects and
 * arrays along the path are cloned (structural sharing elsewhere); missing
 * containers are created as arrays for numeric segments and objects otherwise.
 * The empty path returns `value`. Pure — `obj` is never mutated.
+*
+* @example
+* ```ts
+* import { Path } from "@thomasfosterau/effect-forms"
+*
+* const before = { authors: [{ name: "Ada" }] }
+* const after = Path.setAt(before, ["authors", 0, "name"], "Grace")
+* console.log(Path.getAt(after, ["authors", 0, "name"])) // "Grace"
+* console.log(before.authors[0]?.name) // "Ada" — the input is untouched
+* ```
 */
 function setAt(obj, path, value) {
-	if (path.length === 0) return value;
-	const [head, ...rest] = path;
-	const clone = Array.isArray(obj) ? [...obj] : { ...obj };
-	const child = clone[head];
-	clone[head] = rest.length === 0 ? value : setAt(child === null || typeof child !== "object" ? typeof rest[0] === "number" ? [] : {} : child, rest, value);
-	return clone;
+	return Arr.match(path, {
+		onEmpty: () => value,
+		onNonEmpty: ([head, ...rest]) => {
+			const clone = Arr.isArray(obj) ? [...obj] : { ...Object(obj) };
+			const child = clone[head];
+			clone[head] = Arr.match(rest, {
+				onEmpty: () => value,
+				onNonEmpty: (tail) => setAt(Predicate.isObjectOrArray(child) ? child : Predicate.isNumber(tail[0]) ? [] : {}, tail, value)
+			});
+			return clone;
+		}
+	});
 }
 /** Whether `path` is `root` or nested beneath it. */
 function isUnder(path, root) {
-	if (path.length < root.length) return false;
-	for (let i = 0; i < root.length; i++) if (path[i] !== root[i]) return false;
-	return true;
+	return path.length >= root.length && Arr.every(root, (segment, i) => path[i] === segment);
 }
 /**
 * Render a {@link FormPath} as flat field-name notation: string segments join
@@ -753,10 +824,7 @@ function isUnder(path, root) {
 * The inverse of {@link fromString}.
 */
 function toString(path) {
-	let out = "";
-	for (const segment of path) if (typeof segment === "number") out += `[${segment}]`;
-	else out += out === "" ? segment : `.${segment}`;
-	return out;
+	return Arr.reduce(path, "", (out, segment) => Predicate.isNumber(segment) ? `${out}[${segment}]` : out === "" ? segment : `${out}.${segment}`);
 }
 /**
 * Parse flat field-name notation into a {@link FormPath}: integer tokens become
@@ -801,7 +869,7 @@ const clearAll = () => null;
 function remapIndex(path, arrayPath, map) {
 	if (!isUnder(path, arrayPath) || path.length === arrayPath.length) return path;
 	const segment = path[arrayPath.length];
-	if (typeof segment !== "number") return path;
+	if (!Predicate.isNumber(segment)) return path;
 	const mapped = map(segment);
 	if (mapped === null) return null;
 	if (mapped === segment) return path;
@@ -817,15 +885,34 @@ function remapIndex(path, arrayPath, map) {
 * maps to `null` are dropped. Pure.
 */
 function remapKeyedRecord(record, arrayPath, map) {
-	const out = {};
-	for (const key of Object.keys(record)) {
+	return Rec.fromEntries(Arr.flatMap(Rec.toEntries(record), ([key, value]) => {
 		const remapped = remapIndex(fromString(key), arrayPath, map);
-		if (remapped !== null) out[toString(remapped)] = record[key];
-	}
-	return out;
+		return remapped === null ? [] : [[toString(remapped), value]];
+	}));
 }
 //#endregion
 //#region src/Errors.ts
+/**
+* The nested form-error tree and its operations.
+*
+* {@link FormErrors} is a nested error tree so a UI can read
+* `errors.author.name` or `errors.tags[0]` directly. The representation is:
+*
+* - a **leaf** field's messages are a `string[]` keyed by the field name
+*   (`{ title: ["Required"] }`);
+* - a **branch** (nested object / array) is a nested `FormErrors`
+*   (`{ author: { name: ["Required"] } }`); array elements are keyed by their
+*   stringified index (`{ tags: { "0": ["Too short"] } }`);
+* - a message attached to a **branch itself** (a cross-field or
+*   whole-array message) lives under that branch's `_errors` key.
+*
+* The tree is plain JSON — it serialises across the SSR boundary unchanged —
+* and the operations here ({@link issuesToErrors}, {@link flattenErrors},
+* {@link setError}, {@link mergeErrors}, …) are pure and return new trees.
+*
+* @copyright Thomas Foster
+* @module effect-forms/Errors
+*/
 var Errors_exports = /* @__PURE__ */ __exportAll({
 	ROOT_ERROR_KEY: () => ROOT_ERROR_KEY,
 	clearSourceAt: () => clearSourceAt,
@@ -844,7 +931,7 @@ var Errors_exports = /* @__PURE__ */ __exportAll({
 });
 /** The root key under which a branch's own (non-field) messages are stored. */
 const ROOT_ERROR_KEY = "_errors";
-const isMessageList = (value) => Array.isArray(value) && value.every((v) => typeof v === "string");
+const isMessageList = (value) => Arr.isArray(value) && Arr.every(value, Predicate.isString);
 const ownErrors = (node) => {
 	const existing = node[ROOT_ERROR_KEY];
 	if (isMessageList(existing)) return existing;
@@ -853,15 +940,26 @@ const ownErrors = (node) => {
 	return created;
 };
 /**
-* If `node[key]` is a leaf's message list, convert it in place into a branch
-* carrying those same messages as its own {@link ROOT_ERROR_KEY} (a path used
-* as a leaf is now needed as a branch too) — a no-op when `node[key]` is
-* already a branch or absent. Shared by {@link insert} and {@link setLeaf}'s
-* path-descent, the one piece of their branch-walking that's identical.
+* Return the branch at `node[key]`, making one in place if needed: an absent
+* key gets a new empty branch, and a leaf's message list is converted into a
+* branch carrying those same messages as its own {@link ROOT_ERROR_KEY} (a
+* path used as a leaf is now needed as a branch too). Shared by {@link insert}
+* and {@link setLeaf}'s path-descent, the one piece of their branch-walking
+* that's identical.
 */
-const promoteLeafToBranch = (node, key) => {
+const branchAt = (node, key) => {
 	const existing = node[key];
-	if (isMessageList(existing)) node[key] = { [ROOT_ERROR_KEY]: existing };
+	if (existing === void 0) {
+		const created = {};
+		node[key] = created;
+		return created;
+	}
+	if (isMessageList(existing)) {
+		const promoted = { [ROOT_ERROR_KEY]: existing };
+		node[key] = promoted;
+		return promoted;
+	}
+	return existing;
 };
 /**
 * Insert one message at `path` into a mutable error tree. A leaf becomes a
@@ -871,18 +969,12 @@ const promoteLeafToBranch = (node, key) => {
 * tree root's {@link ROOT_ERROR_KEY}.
 */
 const insert = (root, path, message) => {
-	if (path.length === 0) {
+	if (!Arr.isReadonlyArrayNonEmpty(path)) {
 		ownErrors(root).push(message);
 		return;
 	}
-	let node = root;
-	for (let i = 0; i < path.length - 1; i++) {
-		const key = String(path[i]);
-		if (node[key] === void 0) node[key] = {};
-		else promoteLeafToBranch(node, key);
-		node = node[key];
-	}
-	const last = String(path[path.length - 1]);
+	const node = Arr.reduce(Arr.initNonEmpty(path), root, (parent, segment) => branchAt(parent, String(segment)));
+	const last = String(Arr.lastNonEmpty(path));
 	const existing = node[last];
 	if (existing === void 0) node[last] = [message];
 	else if (isMessageList(existing)) existing.push(message);
@@ -891,7 +983,7 @@ const insert = (root, path, message) => {
 /** Build a nested {@link FormErrors} tree from a flat list of {@link FormIssue}s. */
 function issuesToErrors(issues) {
 	const root = {};
-	for (const issue of issues) insert(root, issue.path, issue.message);
+	Arr.forEach(issues, (issue) => insert(root, issue.path, issue.message));
 	return root;
 }
 /**
@@ -900,32 +992,25 @@ function issuesToErrors(issues) {
 * ordering within a single field).
 */
 function flattenErrors(errors) {
-	const out = [];
-	const walk = (node, path) => {
-		for (const key of Object.keys(node)) {
-			const value = node[key];
-			if (value === void 0) continue;
-			if (key === "_errors") {
-				for (const message of value) out.push({
-					path,
-					message
-				});
-				continue;
-			}
-			const segment = /^\d+$/.test(key) ? Number(key) : key;
-			if (isMessageList(value)) for (const message of value) out.push({
-				path: [...path, segment],
-				message
-			});
-			else walk(value, [...path, segment]);
-		}
-	};
-	walk(errors, []);
-	return out;
+	const walk = (node, path) => Arr.flatMap(Rec.keys(node), (key) => {
+		if (key === "_errors") return Arr.map(node["_errors"] ?? [], (message) => ({
+			path,
+			message
+		}));
+		const value = node[key];
+		if (value === void 0) return [];
+		const segment = /^\d+$/.test(key) ? Number(key) : key;
+		if (isMessageList(value)) return Arr.map(value, (message) => ({
+			path: [...path, segment],
+			message
+		}));
+		return walk(value, [...path, segment]);
+	});
+	return walk(errors, []);
 }
 /** Whether the tree carries any message anywhere. */
 function hasErrors(errors) {
-	return flattenErrors(errors).length > 0;
+	return Arr.isReadonlyArrayNonEmpty(flattenErrors(errors));
 }
 /**
 * Read the messages attached directly to `path` (a leaf's list, or a branch's
@@ -933,11 +1018,7 @@ function hasErrors(errors) {
 * messages.
 */
 function getError(errors, path) {
-	let node = errors;
-	for (const segment of path) {
-		if (node === void 0 || isMessageList(node)) return void 0;
-		node = node[String(segment)];
-	}
+	const node = Arr.reduce(path, errors, (current, segment) => current === void 0 || isMessageList(current) ? void 0 : current[String(segment)]);
 	if (node === void 0) return void 0;
 	if (isMessageList(node)) return node;
 	return node[ROOT_ERROR_KEY];
@@ -961,15 +1042,13 @@ const noErrors = {};
 * Messages whose index maps to `null` are dropped. Pure.
 */
 function remapIndices(errors, arrayPath, map) {
-	const remapped = [];
-	for (const issue of flattenErrors(errors)) {
+	return issuesToErrors(Arr.flatMap(flattenErrors(errors), (issue) => {
 		const path = remapIndex(issue.path, arrayPath, map);
-		if (path !== null) remapped.push({
+		return path === null ? [] : [{
 			path,
 			message: issue.message
-		});
-	}
-	return issuesToErrors(remapped);
+		}];
+	}));
 }
 /**
 * Return a new tree with the messages *directly at* `path` replaced by
@@ -986,51 +1065,45 @@ function replaceAt(errors, path, messages) {
 	return next;
 }
 const setLeaf = (root, path, messages) => {
-	if (path.length === 0) {
+	if (!Arr.isReadonlyArrayNonEmpty(path)) {
 		setOwnMessages(root, messages);
 		return;
 	}
-	const parent = descendClearing(root, path, messages);
+	const parent = descendClearing(root, Arr.initNonEmpty(path), messages);
 	if (parent === void 0) return;
-	setLeafMessages(parent, String(path[path.length - 1]), messages);
+	setLeafMessages(parent, String(Arr.lastNonEmpty(path)), messages);
 };
 /** Set or clear a node's own {@link ROOT_ERROR_KEY} messages. */
 const setOwnMessages = (node, messages) => {
-	if (messages.length === 0) delete node[ROOT_ERROR_KEY];
+	if (Arr.isReadonlyArrayEmpty(messages)) delete node[ROOT_ERROR_KEY];
 	else node[ROOT_ERROR_KEY] = [...messages];
 };
 /**
-* Walk to `path`'s parent branch, creating branches as needed. When
+* Walk down the `parents` segments (a path minus its last segment) to the
+* leaf's parent branch, creating branches as needed. When
 * `messages` is empty (a clear, not a set) a missing branch means there is
 * nothing to clear — descent stops early and returns `undefined` rather than
 * creating empty branches just to immediately no-op inside them.
 */
-const descendClearing = (root, path, messages) => {
-	let node = root;
-	for (let i = 0; i < path.length - 1; i++) {
-		const key = String(path[i]);
-		if (node[key] === void 0) {
-			if (messages.length === 0) return void 0;
-			node[key] = {};
-		} else promoteLeafToBranch(node, key);
-		node = node[key];
-	}
-	return node;
-};
+const descendClearing = (root, parents, messages) => Arr.reduce(parents, root, (node, segment) => {
+	if (node === void 0) return void 0;
+	const key = String(segment);
+	if (node[key] === void 0 && Arr.isReadonlyArrayEmpty(messages)) return void 0;
+	return branchAt(node, key);
+});
 /** Set or clear `node[key]`'s messages — a leaf's list, or (if it's already a branch) its own {@link ROOT_ERROR_KEY}. */
 const setLeafMessages = (node, key, messages) => {
 	const existing = node[key];
 	if (existing === void 0) {
-		if (messages.length > 0) node[key] = [...messages];
+		if (Arr.isReadonlyArrayNonEmpty(messages)) node[key] = [...messages];
 		return;
 	}
 	if (isMessageList(existing)) {
-		if (messages.length === 0) delete node[key];
+		if (Arr.isReadonlyArrayEmpty(messages)) delete node[key];
 		else node[key] = [...messages];
 		return;
 	}
-	if (messages.length === 0) delete existing[ROOT_ERROR_KEY];
-	else existing[ROOT_ERROR_KEY] = [...messages];
+	setOwnMessages(existing, messages);
 };
 /** Both source trees empty. */
 const emptySourced = {
@@ -1057,6 +1130,26 @@ function clearSourceAt(sourced, source, path) {
 }
 //#endregion
 //#region src/Field.ts
+/**
+* Field definitions for the {@link module:effect-forms/FormBuilder}.
+*
+* A {@link FormBuilder} composes a form one field at a time. Each field is
+* either a **scalar** {@link FieldDef} (bound to a leaf schema) or an
+* **array** {@link ArrayFieldDef} (bound to an item schema — the field is a
+* list of that item). This module is the small vocabulary the builder is made
+* of: the two field shapes, their guards, the type-level projections that turn
+* a record of fields into the form's encoded / decoded data types, and the
+* default-value derivation used to seed a blank form (or a freshly-appended
+* array item).
+*
+* Defaults are *encoded* — an HTML form holds strings, so a scalar seeds to
+* `""`, an array to `[]`, and a nested struct recurses. Coercion back to the
+* decoded type is the schema's job at validate time (see
+* {@link module:effect-forms/Coerce}).
+*
+* @copyright Thomas Foster
+* @module effect-forms/Field
+*/
 var Field_exports = /* @__PURE__ */ __exportAll({
 	defaultEncodedValues: () => defaultEncodedValues,
 	defaultItemAt: () => defaultItemAt,
@@ -1068,9 +1161,9 @@ var Field_exports = /* @__PURE__ */ __exportAll({
 	schemaAt: () => schemaAt
 });
 /** Whether `def` is an {@link ArrayFieldDef}. */
-const isArrayFieldDef = (def) => def._tag === "array";
+const isArrayFieldDef = (def) => Predicate.isTagged(def, "array");
 /** Whether `def` is a scalar {@link FieldDef}. */
-const isFieldDef = (def) => def._tag === "field";
+const isFieldDef = (def) => Predicate.isTagged(def, "field");
 /** Construct a scalar {@link FieldDef}. */
 const makeField = (key, schema) => ({
 	_tag: "field",
@@ -1100,19 +1193,14 @@ function defaultValue(schema) {
 */
 function unwrapToStructured(ast) {
 	if (!SchemaAST.isUnion(ast)) return ast;
-	for (const member of ast.types) {
+	return Arr.findFirst(ast.types, (member) => {
 		const inner = unwrapToStructured(member);
-		if (SchemaAST.isObjects(inner) || SchemaAST.isArrays(inner)) return inner;
-	}
-	return ast;
+		return SchemaAST.isObjects(inner) || SchemaAST.isArrays(inner) ? Option.some(inner) : Option.none();
+	}).pipe(Option.getOrElse(() => ast));
 }
 function fromAst(ast) {
 	const unwrapped = unwrapToStructured(ast);
-	if (SchemaAST.isObjects(unwrapped)) {
-		const out = {};
-		for (const ps of unwrapped.propertySignatures) out[String(ps.name)] = fromAst(ps.type);
-		return out;
-	}
+	if (SchemaAST.isObjects(unwrapped)) return Rec.fromEntries(Arr.map(unwrapped.propertySignatures, (ps) => [String(ps.name), fromAst(ps.type)]));
 	if (SchemaAST.isArrays(unwrapped)) return [];
 	return "";
 }
@@ -1140,12 +1228,7 @@ function stepIntoStruct(ast, key) {
 * schemas built directly with `Form.make` (no builder involved).
 */
 function schemaAt(schema, path) {
-	let ast = unwrapToStructured(schema.ast);
-	for (const segment of path) {
-		if (ast === void 0) return void 0;
-		ast = typeof segment === "number" ? stepIntoArray(ast) : stepIntoStruct(ast, segment);
-	}
-	return ast;
+	return Arr.reduce(path, unwrapToStructured(schema.ast), (ast, segment) => ast === void 0 ? void 0 : Predicate.isNumber(segment) ? stepIntoArray(ast) : stepIntoStruct(ast, segment));
 }
 /**
 * Derive a blank encoded item for the array field at `path` (any nesting
@@ -1154,18 +1237,34 @@ function schemaAt(schema, path) {
 */
 function defaultItemAt(schema, path) {
 	const ast = schemaAt(schema, path);
-	if (ast === void 0 || !SchemaAST.isArrays(ast)) return "";
-	const item = arrayElementAst(ast);
+	const item = ast !== void 0 && SchemaAST.isArrays(ast) ? arrayElementAst(ast) : void 0;
 	return item === void 0 ? "" : fromAst(item);
 }
 /** Seed a blank encoded value for every field: `[]` for arrays, `""` otherwise. */
 function defaultEncodedValues(fields) {
-	const out = {};
-	for (const [key, def] of Object.entries(fields)) out[key] = isArrayFieldDef(def) ? [] : defaultValue(def.schema);
-	return out;
+	return Rec.map(fields, (def) => isArrayFieldDef(def) ? [] : defaultValue(def.schema));
 }
 //#endregion
 //#region src/Issues.ts
+/**
+* Form issues — the flat, path-addressed representation of a single
+* validation failure, plus the walker that turns an Effect Schema issue
+* tree into a list of them.
+*
+* An Effect Schema decode failure is a recursive {@link SchemaIssue.Issue}
+* tree: `Pointer` nodes carry path segments, `Composite` / `AnyOf` group
+* sibling failures, `Filter` / `Encoding` wrap a single inner failure, and
+* the leaves (`InvalidType`, `InvalidValue`, `MissingKey`, …) describe the
+* actual problem. {@link schemaIssuesToFormIssues} flattens that tree into
+* one {@link FormIssue} per leaf, accumulating the `Pointer.path` segments
+* into a `FormPath`. This is the framework-neutral
+* flattened error list and the same walk the repo's JSON:API materialiser
+* performs — here it stays UI-shaped (`path` + `message`) rather than
+* JSON:API-pointer-shaped.
+*
+* @copyright Thomas Foster
+* @module effect-forms/Issues
+*/
 var Issues_exports = /* @__PURE__ */ __exportAll({
 	defaultLeafFormatter: () => defaultLeafFormatter,
 	filterOutputToFormIssues: () => filterOutputToFormIssues$1,
@@ -1178,21 +1277,12 @@ const defaultLeafFormatter = SchemaIssue.makeFormatterDefault();
 * keys become numbers (array indices), everything else becomes a string.
 */
 const normaliseSegment = (segment) => {
-	if (typeof segment === "number") return segment;
-	if (typeof segment === "symbol") return segment.toString();
+	if (Predicate.isNumber(segment)) return segment;
+	if (Predicate.isSymbol(segment)) return segment.toString();
 	return /^\d+$/.test(segment) ? Number(segment) : segment;
 };
 /** Whether `issue` is a terminal leaf: it wraps no further issues. */
-const isTerminal = (issue) => {
-	switch (issue._tag) {
-		case "Pointer":
-		case "Composite":
-		case "Filter":
-		case "Encoding": return false;
-		case "AnyOf": return issue.issues.length === 0;
-		default: return true;
-	}
-};
+const isTerminal = Match.type().pipe(Match.tag("Pointer", "Composite", "Filter", "Encoding", () => false), Match.tag("AnyOf", (issue) => Arr.isReadonlyArrayEmpty(issue.issues)), Match.orElse(() => true));
 /**
 * Walk an Effect Schema issue tree, emitting one {@link FormIssue} per leaf
 * failure. Path segments accumulate through `Pointer` nodes; `Composite` and
@@ -1201,48 +1291,18 @@ const isTerminal = (issue) => {
 * mismatch) is itself a leaf.
 */
 function schemaIssuesToFormIssues(issue, format = defaultLeafFormatter) {
-	const out = [];
 	const walk = (current, path) => {
-		switch (current._tag) {
-			case "Pointer":
-				walk(current.issue, [...path, ...current.path.map(normaliseSegment)]);
-				return;
-			case "Composite":
-				for (const child of current.issues) walk(child, path);
-				return;
-			case "AnyOf":
-				if (current.issues.length === 0) {
-					out.push({
-						path,
-						message: format(current)
-					});
-					return;
-				}
-				for (const child of current.issues) walk(child, path);
-				return;
-			case "Filter":
-				if (isTerminal(current.issue)) {
-					out.push({
-						path,
-						message: format(current)
-					});
-					return;
-				}
-				walk(current.issue, path);
-				return;
-			case "Encoding":
-				walk(current.issue, path);
-				return;
-			default:
-				out.push({
-					path,
-					message: format(current)
-				});
-				return;
-		}
+		const leaf = (node) => [{
+			path,
+			message: format(node)
+		}];
+		const walkAll = (children) => Arr.flatMap(children, (child) => walk(child, path));
+		return Match.value(current).pipe(Match.tag("Pointer", (pointer) => walk(pointer.issue, [...path, ...Arr.map(pointer.path, normaliseSegment)])), Match.tag("Composite", (composite) => walkAll(composite.issues)), Match.tag("AnyOf", (anyOf) => Arr.match(anyOf.issues, {
+			onEmpty: () => leaf(anyOf),
+			onNonEmpty: walkAll
+		})), Match.tag("Filter", (filter) => isTerminal(filter.issue) ? leaf(filter) : walk(filter.issue, path)), Match.tag("Encoding", (encoding) => walk(encoding.issue, path)), Match.orElse(leaf));
 	};
-	walk(issue, []);
-	return out;
+	return walk(issue, []);
 }
 /**
 * Normalise a filter predicate's {@link Schema.FilterOutput} into a flat list of
@@ -1257,17 +1317,19 @@ function filterOutputToFormIssues$1(output) {
 		path: [],
 		message: "Invalid value"
 	}];
-	if (Array.isArray(output)) return output.flatMap(filterIssueToFormIssues);
+	if (isFilterIssueList(output)) return Arr.flatMap(output, filterIssueToFormIssues);
 	return filterIssueToFormIssues(output);
 }
+/** `Array.isArray` as a guard that also narrows away a `ReadonlyArray` member. */
+const isFilterIssueList = (output) => Arr.isArray(output);
 function filterIssueToFormIssues(issue) {
-	if (typeof issue === "string") return [{
+	if (Predicate.isString(issue)) return [{
 		path: [],
 		message: issue
 	}];
 	if ("path" in issue && "issue" in issue) {
-		const prefix = issue.path.map((s) => typeof s === "symbol" ? s.toString() : s);
-		return (typeof issue.issue === "string" ? [{
+		const prefix = Arr.map(issue.path, (s) => Predicate.isSymbol(s) ? s.toString() : s);
+		return (Predicate.isString(issue.issue) ? [{
 			path: [],
 			message: issue.issue
 		}] : schemaIssuesToFormIssues(issue.issue)).map((i) => ({
@@ -1315,10 +1377,12 @@ var FormBuilder_exports = /* @__PURE__ */ __exportAll({
 });
 /** Brand for a {@link FormBuilder}. */
 const TypeId = Symbol.for("@thomasfosterau/effect-forms/FormBuilder");
+/** Whether `addField` was called with the `(key, schema)` overload — the only one whose first argument is a string. */
+const isKeyedArgs = (args) => Predicate.isString(args[0]);
 const proto = {
 	[TypeId]: TypeId,
-	addField(keyOrField, schema) {
-		const field = typeof keyOrField === "string" ? makeField(keyOrField, schema) : keyOrField;
+	addField(...args) {
+		const field = isKeyedArgs(args) ? makeField(...args) : args[0];
 		return build({
 			...this.fields,
 			[field.key]: field
@@ -1350,7 +1414,7 @@ function build(fields, refinements) {
 	return self;
 }
 /** Whether `u` is a {@link FormBuilder}. */
-const isFormBuilder = (u) => typeof u === "object" && u !== null && TypeId in u;
+const isFormBuilder = (u) => Predicate.isObjectOrArray(u) && Predicate.hasProperty(u, TypeId);
 /** The empty builder — the starting point for {@link FormBuilder.addField}. */
 const make$2 = build({}, []);
 /** Alias of {@link make} — the empty builder. */
@@ -1361,16 +1425,20 @@ const empty = make$2;
 * applied as a struct-level check. Ready for {@link module:effect-forms/Form}.
 */
 function buildSchema(self) {
-	const structFields = {};
-	for (const [key, def] of Object.entries(self.fields)) if (isArrayFieldDef(def)) structFields[key] = Schema.Array(def.itemSchema);
-	else if (isFieldDef(def)) structFields[key] = def.schema;
-	let schema = Schema.Struct(structFields);
-	for (const refinement of self.refinements) if (refinement._tag === "sync") schema = schema.check(Schema.makeFilter(refinement.fn));
-	return schema;
+	const structFields = Rec.fromEntries(Arr.flatMap(Rec.toEntries(self.fields), ([key, def]) => {
+		if (isArrayFieldDef(def)) return [[key, Schema.Array(def.itemSchema)]];
+		if (isFieldDef(def)) return [[key, def.schema]];
+		return [];
+	}));
+	const struct = Schema.Struct(structFields);
+	return Arr.reduce(self.refinements, struct, (refined, refinement) => Predicate.isTagged(refinement, "sync") ? refined.check(Schema.makeFilter(refinement.fn)) : refined);
 }
 /** The asynchronous refinements carried on a builder, as bare predicates. */
 function asyncRefinements(self) {
-	return self.refinements.filter((r) => r._tag === "async").map((r) => r.fn);
+	return Arr.flatMap(self.refinements, (refinement) => {
+		if (!Predicate.isTagged(refinement, "async")) return [];
+		return [refinement.fn];
+	});
 }
 /**
 * Normalise a filter predicate's `Schema.FilterOutput` into a flat list of
@@ -1386,9 +1454,10 @@ const filterOutputToFormIssues = filterOutputToFormIssues$1;
 * concurrently; requirements propagate on the `R` channel.
 */
 function runAsyncRefinements(self, values) {
-	const refinements = asyncRefinements(self);
-	if (refinements.length === 0) return Effect.succeed([]);
-	return Effect.forEach(refinements, (fn) => fn(values), { concurrency: "unbounded" }).pipe(Effect.map((outputs) => outputs.flatMap(filterOutputToFormIssues$1)));
+	return Arr.match(asyncRefinements(self), {
+		onEmpty: () => Effect.succeed([]),
+		onNonEmpty: (refinements) => Effect.forEach(refinements, (fn) => fn(values), { concurrency: "unbounded" }).pipe(Effect.map((outputs) => Arr.flatMap(outputs, filterOutputToFormIssues$1)))
+	});
 }
 //#endregion
 //#region src/State.ts
@@ -1414,15 +1483,16 @@ var State_exports = /* @__PURE__ */ __exportAll({
 /** Build a {@link FormState} from data plus overrides. `valid` defaults to "no errors". */
 function make$1(data, options = {}) {
 	const errors = options.errors ?? noErrors;
-	return {
+	const state = {
 		id: options.id ?? "default",
 		valid: options.valid ?? !hasErrors(errors),
 		posted: options.posted ?? false,
 		data,
-		errors,
-		...options.message !== void 0 ? { message: options.message } : {},
-		...options.constraints !== void 0 ? { constraints: options.constraints } : {}
+		errors
 	};
+	if (options.message !== void 0) state.message = options.message;
+	if (options.constraints !== void 0) state.constraints = options.constraints;
+	return state;
 }
 /** Return a new state carrying `message` (and not otherwise changed). */
 function withMessage(state, message) {
@@ -1489,7 +1559,10 @@ var Form_exports = /* @__PURE__ */ __exportAll({
 });
 const toStructured = (input) => {
 	if (input === null || input === void 0) return Effect.succeed(null);
-	if (input instanceof Request) return Effect.promise(() => requestToObject(input));
+	if (input instanceof Request) return Effect.tryPromise({
+		try: () => requestToObject(input),
+		catch: (cause) => cause
+	}).pipe(Effect.orDie);
 	if (input instanceof FormData || input instanceof URLSearchParams) return Effect.succeed(formDataToObject(input));
 	return Effect.succeed(input);
 };
@@ -1499,6 +1572,22 @@ const toStructured = (input) => {
 * its requirements are the schema's decoding services) and `empty()` seeds a
 * blank form from `defaults`. The returned {@link Form} is stateless and
 * reusable across requests.
+*
+* @example
+* ```ts
+* import * as Effect from "effect/Effect"
+* import * as Schema from "effect/Schema"
+* import { Form } from "@thomasfosterau/effect-forms"
+*
+* const signup = Form.make(
+*   Schema.Struct({ name: Schema.String.check(Schema.isMinLength(2)) }),
+*   { id: "signup", defaults: { name: "" } },
+* )
+*
+* const state = Effect.runSync(signup.validate(new URLSearchParams({ name: "A" })))
+* console.log(state.valid) // false
+* console.log(state.data) // { name: "A" } — the posted value, kept for re-render
+* ```
 */
 function make(schema, options) {
 	const id = options.id ?? "default";
@@ -1522,16 +1611,19 @@ function make(schema, options) {
 				posted: true,
 				constraints
 			})),
-			onFailure: (issue) => Effect.succeed(make$1({
-				...defaults,
-				...object
-			}, {
-				id,
-				valid: false,
-				posted: true,
-				constraints,
-				errors: issuesToErrors(schemaIssuesToFormIssues(issue, leafFormatter))
-			}))
+			onFailure: (issue) => {
+				const posted = {
+					...defaults,
+					...object
+				};
+				return Effect.succeed(make$1(posted, {
+					id,
+					valid: false,
+					posted: true,
+					constraints,
+					errors: issuesToErrors(schemaIssuesToFormIssues(issue, leafFormatter))
+				}));
+			}
 		}));
 	}));
 	return {
@@ -1565,17 +1657,20 @@ function fromBuilder(builder, options = {}) {
 			...object
 		};
 		return decode(object).pipe(Effect.matchEffect({
-			onSuccess: (data) => runAsyncRefinements(builder, data).pipe(Effect.map((issues) => issues.length === 0 ? make$1(data, {
-				id: base.id,
-				valid: true,
-				posted: true,
-				constraints: base.constraints
-			}) : make$1(posted, {
-				id: base.id,
-				valid: false,
-				posted: true,
-				constraints: base.constraints,
-				errors: issuesToErrors(issues)
+			onSuccess: (data) => runAsyncRefinements(builder, data).pipe(Effect.map((issues) => Arr.match(issues, {
+				onEmpty: () => make$1(data, {
+					id: base.id,
+					valid: true,
+					posted: true,
+					constraints: base.constraints
+				}),
+				onNonEmpty: (failures) => make$1(posted, {
+					id: base.id,
+					valid: false,
+					posted: true,
+					constraints: base.constraints,
+					errors: issuesToErrors(failures)
+				})
 			}))),
 			onFailure: (issue) => Effect.succeed(make$1(posted, {
 				id: base.id,