@orkestrel/form 0.0.4 → 0.0.6

package/dist/src/core/index.js

@@ -1,7 +1,7 @@
-import { arrayOf, attempt, cloneJSONRecord, isArray, isBoolean, isBoundedJSONRecord, isContractError, isFiniteNumber, isFunction, isInteger, isRecord, isString, literalOf, parseNumber, readArrayEntries, recordOf, unionOf } from "@orkestrel/contract";
+import { arrayOf, attempt, cloneJSONRecord, isArray, isBoolean, isBoundedJSONRecord, isContractError, isFiniteNumber, isFunction, isInteger, isRecord, isString, keyOf, parseNumber, readArrayEntries, recordOf, unionOf } from "@orkestrel/contract";
 import { Emitter } from "@orkestrel/emitter";
 //#region src/core/constants.ts
-/** Every field control, in the order declared by the public contract. */
+/** Lists every field control, in the order declared by the public contract. */
 var FIELD_CONTROLS = Object.freeze([
 	"text",
 	"editor",
@@ -16,13 +16,69 @@ var FIELD_CONTROLS = Object.freeze([
 	"checkbox",
 	"file"
 ]);
-/** Every form lifecycle status. */
+/** Lists the members every field declares, whatever its control. */
+var FIELD_BASE_KEYS = Object.freeze([
+	"control",
+	"name",
+	"label",
+	"help",
+	"group",
+	"hidden",
+	"disabled",
+	"locked",
+	"rule",
+	"meta"
+]);
+/**
+* Lists every member one field control permits, composed from {@link FIELD_BASE_KEYS} and the
+* members the control's own interface adds.
+*/
+var FIELD_KEYS = Object.freeze({
+	text: Object.freeze([
+		...FIELD_BASE_KEYS,
+		"default",
+		"placeholder"
+	]),
+	editor: Object.freeze([
+		...FIELD_BASE_KEYS,
+		"default",
+		"placeholder"
+	]),
+	password: Object.freeze([...FIELD_BASE_KEYS, "mask"]),
+	number: Object.freeze([
+		...FIELD_BASE_KEYS,
+		"default",
+		"placeholder"
+	]),
+	date: Object.freeze([...FIELD_BASE_KEYS, "default"]),
+	time: Object.freeze([...FIELD_BASE_KEYS, "default"]),
+	datetime: Object.freeze([...FIELD_BASE_KEYS, "default"]),
+	color: Object.freeze([...FIELD_BASE_KEYS, "default"]),
+	confirm: Object.freeze([...FIELD_BASE_KEYS, "default"]),
+	select: Object.freeze([
+		...FIELD_BASE_KEYS,
+		"choices",
+		"default",
+		"open"
+	]),
+	checkbox: Object.freeze([
+		...FIELD_BASE_KEYS,
+		"choices",
+		"default"
+	]),
+	file: Object.freeze([
+		...FIELD_BASE_KEYS,
+		"accept",
+		"multiple"
+	])
+});
+/** Lists every form lifecycle status. */
 var FORM_STATUSES = Object.freeze([
 	"editing",
 	"settled",
 	"abandoned"
 ]);
-/** Default failure copy for every named field rule. */
+/** Holds the default failure copy for every named field rule. */
 var RULE_MESSAGES = Object.freeze({
 	required: "This field is required",
 	minimum: "Must be at least {limit}",
@@ -34,50 +90,62 @@ var RULE_MESSAGES = Object.freeze({
 	integer: "Must be an integer",
 	alphanumeric: "Must contain only letters and numbers"
 });
-/** A practical whole-address email shape. */
+/** Matches a practical whole-address email shape. */
 var EMAIL_PATTERN = Object.freeze(/^[^\s@]+@[^\s@]+\.[^\s@]+$/);
-/** An absolute HTTP or HTTPS URL shape. */
+/** Matches an absolute HTTP or HTTPS URL shape. */
 var URL_PATTERN = Object.freeze(/^https?:\/\/[^\s]+$/);
-/** One or more ASCII letters or digits. */
+/** Matches one or more ASCII letters or digits. */
 var ALPHANUMERIC_PATTERN = Object.freeze(/^[A-Za-z0-9]+$/);
-/** A signed or unsigned base-ten integer string. */
+/** Matches a signed or unsigned base-ten integer string. */
 var INTEGER_PATTERN = Object.freeze(/^[+-]?\d+$/);
-/** A six-digit hexadecimal color string. */
+/** Matches a six-digit hexadecimal color string. */
 var COLOR_PATTERN = Object.freeze(/^#[0-9A-Fa-f]{6}$/);
-/** An ISO calendar date string in `YYYY-MM-DD` form. */
+/** Matches an ISO calendar date string in `YYYY-MM-DD` form. */
 var DATE_PATTERN = Object.freeze(/^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$/);
-/** A 24-hour time string with optional seconds. */
+/** Matches a 24-hour time string with optional seconds. */
 var TIME_PATTERN = Object.freeze(/^(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d)?$/);
-/** An ISO local date and time string with optional seconds. */
+/** Matches an ISO local date and time string with optional seconds. */
 var DATETIME_PATTERN = Object.freeze(/^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])T(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d)?$/);
-/** The maximum accepted source length for an authored regular expression. */
+/** Caps the accepted source length for an authored regular expression, at 256. */
 var PATTERN_LIMIT = 256;
-/** The maximum number of fields one schema may declare. */
+/** Caps the number of fields one schema may declare, at 512. */
 var FIELD_LIMIT = 512;
-/** The maximum number of groups one schema may declare. */
+/** Caps the number of groups one schema may declare, at 64. */
 var GROUP_LIMIT = 64;
-/** The maximum number of choices one `select` or `checkbox` field may offer. */
+/** Caps the number of choices one `select` or `checkbox` field may offer, at 1024. */
 var CHOICE_LIMIT = 1024;
-/** The maximum number of entries one list-valued answer may hold. */
+/** Caps the number of entries one list-valued answer may hold, at 1024. */
 var LIST_LIMIT = 1024;
-/** The maximum length, in UTF-16 code units, of a schema, group, or field name. */
+/** Caps the length, in UTF-16 code units, of a schema, group, or field name, at 128. */
 var NAME_LIMIT = 128;
-/** The maximum length, in UTF-16 code units, of any single retained string. */
+/** Caps the length, in UTF-16 code units, of any single retained string, at 65536. */
 var STRING_LIMIT = 65536;
-/** The maximum total length, in UTF-16 code units, of every string one schema retains. */
+/** Caps the total length, in UTF-16 code units, of every string one schema retains, at 1048576. */
 var TEXT_LIMIT = 1048576;
-/** The maximum total number of records, arrays, and leaves one schema retains. */
+/** Caps the total number of records, arrays, and leaves one schema retains, at 16384. */
 var NODE_LIMIT = 16384;
 //#endregion
 //#region src/core/errors.ts
-/** An error raised by the form domain. */
+/**
+* Represents an error raised by the form domain.
+*
+* @example
+* ```ts
+* const error = new FormError('FIELD', 'The schema declares no field named "nickname"', {
+* 	field: 'nickname',
+* })
+*
+* error.code // 'FIELD'
+* error.context // { field: 'nickname' }
+* ```
+*/
 var FormError = class extends Error {
-	/** The machine-readable reason for this failure. */
+	/** Holds the machine-readable reason for this failure. */
 	code;
-	/** Structured values that locate or explain this failure. */
+	/** Holds structured values that locate or explain this failure. */
 	context;
 	/**
-	* Create a form error.
+	* Creates a form error.
 	*
 	* @param code - The machine-readable reason.
 	* @param message - The human-readable failure text.
@@ -91,10 +159,10 @@ var FormError = class extends Error {
 	}
 };
 /**
-* Determine whether an unknown value is a form error.
+* Determines whether an unknown value is a form error.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a {@link FormError} instance.
+* @returns True if the value is a {@link FormError} instance; false otherwise.
 */
 function isFormError(input) {
 	return input instanceof FormError;
@@ -102,37 +170,41 @@ function isFormError(input) {
 //#endregion
 //#region src/core/validators.ts
 /**
-* Determine whether an unknown value is a declared field control.
+* Determines whether an unknown value is a declared field control.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a field control.
+* @returns True if the value is a field control; false otherwise.
 */
 function isFieldControl(input) {
 	return FIELD_CONTROLS.some((control) => control === input);
 }
 /**
-* Determine whether an unknown value is a form lifecycle status.
+* Determines whether an unknown value is a form lifecycle status.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a form status.
+* @returns True if the value is a form status; false otherwise.
 */
 function isFormStatus(input) {
 	return FORM_STATUSES.some((status) => status === input);
 }
 /**
-* Determine whether an unknown value has a form field value shape.
+* Determines whether an unknown value has a form field value shape.
+*
+* @remarks
+* A string, a finite number, a boolean, and a list of strings each qualify. A number that is not
+* finite does not, so `NaN` and `Infinity` are refused.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a field value.
+* @returns True if the value is a field value; false otherwise.
 */
 function isFieldValue(input) {
 	return unionOf(isString, isFiniteNumber, isBoolean, arrayOf(isString))(input);
 }
 /**
-* Determine whether an unknown value is one exact field choice record.
+* Determines whether an unknown value is one exact field choice record.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a field choice.
+* @returns True if the value is a field choice; false otherwise.
 */
 function isFieldChoice(input) {
 	const keys = attempt(() => isRecord(input) && Reflect.ownKeys(input).every((key) => isString(key)));
@@ -145,10 +217,10 @@ function isFieldChoice(input) {
 	}, ["help", "disabled"])(input);
 }
 /**
-* Determine whether an unknown value is one exact field rule record.
+* Determines whether an unknown value is one exact field rule record.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a structurally valid field rule.
+* @returns True if the value is a structurally valid field rule; false otherwise.
 */
 function isFieldRule(input) {
 	const keys = attempt(() => isRecord(input) && Reflect.ownKeys(input).every((key) => isString(key)));
@@ -167,7 +239,7 @@ function isFieldRule(input) {
 	}, true)(input);
 }
 /**
-* Determine whether an unknown value is one exact discriminated form field.
+* Determines whether an unknown value is one exact discriminated form field.
 *
 * @remarks
 * Metadata is admitted structurally as bounded JSON. An accessor-bearing metadata record is
@@ -175,120 +247,15 @@ function isFieldRule(input) {
 * data properties only.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a structurally valid form field.
+* @returns True if the value is a structurally valid form field; false otherwise.
 */
 function isFormField(input) {
 	const outcome = attempt(() => {
 		if (!isRecord(input) || !Object.hasOwn(input, "control") || !Object.hasOwn(input, "name")) return false;
 		const control = input.control;
 		if (!isFieldControl(control)) return false;
-		if (!Reflect.ownKeys(input).every((key) => {
-			if (!isString(key)) return false;
-			switch (control) {
-				case "text":
-				case "editor": return [
-					"control",
-					"name",
-					"label",
-					"help",
-					"group",
-					"hidden",
-					"disabled",
-					"locked",
-					"rule",
-					"meta",
-					"default",
-					"placeholder"
-				].includes(key);
-				case "password": return [
-					"control",
-					"name",
-					"label",
-					"help",
-					"group",
-					"hidden",
-					"disabled",
-					"locked",
-					"rule",
-					"meta",
-					"mask"
-				].includes(key);
-				case "number": return [
-					"control",
-					"name",
-					"label",
-					"help",
-					"group",
-					"hidden",
-					"disabled",
-					"locked",
-					"rule",
-					"meta",
-					"default",
-					"placeholder"
-				].includes(key);
-				case "date":
-				case "time":
-				case "datetime":
-				case "color":
-				case "confirm": return [
-					"control",
-					"name",
-					"label",
-					"help",
-					"group",
-					"hidden",
-					"disabled",
-					"locked",
-					"rule",
-					"meta",
-					"default"
-				].includes(key);
-				case "select": return [
-					"control",
-					"name",
-					"label",
-					"help",
-					"group",
-					"hidden",
-					"disabled",
-					"locked",
-					"rule",
-					"meta",
-					"choices",
-					"default",
-					"open"
-				].includes(key);
-				case "checkbox": return [
-					"control",
-					"name",
-					"label",
-					"help",
-					"group",
-					"hidden",
-					"disabled",
-					"locked",
-					"rule",
-					"meta",
-					"choices",
-					"default"
-				].includes(key);
-				case "file": return [
-					"control",
-					"name",
-					"label",
-					"help",
-					"group",
-					"hidden",
-					"disabled",
-					"locked",
-					"rule",
-					"meta",
-					"accept",
-					"multiple"
-				].includes(key);
-			}
-		})) return false;
+		const permitted = FIELD_KEYS[control];
+		if (!Reflect.ownKeys(input).every((key) => isString(key) && permitted.includes(key))) return false;
 		const name = input.name;
 		const hasLabel = Object.hasOwn(input, "label");
 		const label = hasLabel ? input.label : void 0;
@@ -369,10 +336,10 @@ function isFormField(input) {
 	return outcome.success && outcome.value;
 }
 /**
-* Determine whether an unknown value is one exact form group record.
+* Determines whether an unknown value is one exact form group record.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a form group.
+* @returns True if the value is a form group; false otherwise.
 */
 function isFormGroup(input) {
 	const keys = attempt(() => isRecord(input) && Reflect.ownKeys(input).every((key) => isString(key)));
@@ -384,10 +351,14 @@ function isFormGroup(input) {
 	}, ["help"])(input);
 }
 /**
-* Determine whether an unknown value is one exact structural form schema.
+* Determines whether an unknown value is one exact structural form schema.
+*
+* @remarks
+* Structure alone is read. Domain soundness — a duplicate name, a bound no answer satisfies, a
+* breached budget — is {@link auditSchema}'s question.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a structurally valid form schema.
+* @returns True if the value is a structurally valid form schema; false otherwise.
 */
 function isFormSchema(input) {
 	const keys = attempt(() => isRecord(input) && Reflect.ownKeys(input).every((key) => isString(key)));
@@ -406,10 +377,10 @@ function isFormSchema(input) {
 	])(input);
 }
 /**
-* Determine whether an unknown value is a record of field values.
+* Determines whether an unknown value is a record of field values.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a form values record.
+* @returns True if the value is a form values record; false otherwise.
 */
 function isFormValues(input) {
 	const outcome = attempt(() => {
@@ -419,10 +390,10 @@ function isFormValues(input) {
 	return outcome.success && outcome.value;
 }
 /**
-* Determine whether an unknown value is one exact field error record.
+* Determines whether an unknown value is one exact field error record.
 *
 * @param input - The value to inspect.
-* @returns Whether the value is a field error.
+* @returns True if the value is a field error; false otherwise.
 */
 function isFieldError(input) {
 	const keys = attempt(() => isRecord(input) && Reflect.ownKeys(input).every((key) => isString(key)));
@@ -430,7 +401,7 @@ function isFieldError(input) {
 	return recordOf({
 		field: isString,
 		message: isString,
-		rule: literalOf("required", "minimum", "maximum", "step", "pattern", "email", "url", "integer", "alphanumeric")
+		rule: keyOf(RULE_MESSAGES)
 	}, ["rule"])(input);
 }
 //#endregion
@@ -439,7 +410,7 @@ function cloneValue(value) {
 	return isArray(value) ? Object.freeze(value.slice()) : value;
 }
 /**
-* Clone a field's choices into an owned frozen snapshot.
+* Clones a field's choices into an owned frozen snapshot.
 *
 * @param choices - The choices to own.
 * @returns A frozen list of frozen choice records.
@@ -448,7 +419,7 @@ function cloneChoices(choices) {
 	return Object.freeze(choices.map((choice) => Object.freeze({ ...choice })));
 }
 /**
-* Clone one form field into an owned frozen snapshot.
+* Clones one form field into an owned frozen snapshot.
 *
 * @param field - The field to own.
 * @returns A frozen field with every nested collection owned.
@@ -499,7 +470,7 @@ function cloneFormField(field) {
 	}
 }
 /**
-* Clone a form schema into an owned frozen snapshot.
+* Clones a form schema into an owned frozen snapshot.
 *
 * @param schema - The schema to own.
 * @returns A frozen schema with every nested record and list owned.
@@ -515,11 +486,68 @@ function cloneFormSchema(schema) {
 //#endregion
 //#region src/core/helpers.ts
 /**
-* Check whether a value has the shape required by one field control.
+* Writes one own enumerable data property onto a record.
+*
+* @param target - The record to write into.
+* @param name - The property name to write.
+* @param value - The value to store.
+*
+* @remarks
+* Plain assignment runs an inherited setter, so writing a `__proto__` key that way reaches
+* `Object.prototype` and leaves the record without the entry. Defining the property writes the
+* record itself, whatever the prototype chain declares. The entry stays writable and configurable.
+*
+* @example
+* ```ts
+* const values: Record<string, number> = {}
+* defineEntry(values, '__proto__', 1)
+* Object.hasOwn(values, '__proto__') // true
+* ```
+*/
+function defineEntry(target, name, value) {
+	Object.defineProperty(target, name, {
+		value,
+		enumerable: true,
+		configurable: true,
+		writable: true
+	});
+}
+/**
+* Writes one own enumerable data property that cannot be rewritten or removed.
+*
+* @param target - The record to write into.
+* @param name - The property name to write.
+* @param value - The value to store.
+*
+* @remarks
+* The prototype-safe write of {@link defineEntry}, frozen: the entry is neither writable nor
+* configurable, so the record a parser hands back cannot be edited through the key it filled.
+*
+* @example
+* ```ts
+* const values: Record<string, number> = {}
+* freezeEntry(values, '__proto__', 1)
+* Object.getOwnPropertyDescriptor(values, '__proto__')?.writable // false
+* ```
+*/
+function freezeEntry(target, name, value) {
+	Object.defineProperty(target, name, {
+		value,
+		enumerable: true,
+		configurable: false,
+		writable: false
+	});
+}
+/**
+* Checks whether a value has the shape required by one field control.
+*
+* @remarks
+* Every write and every seeded value passes through this gate, and it reads `STRING_LIMIT` and
+* `LIST_LIMIT` before it consults the control, so no regular expression sees an over-long value.
 *
 * @param field - The field that owns the value.
 * @param value - The unknown value to inspect.
-* @returns Whether the control can hold the value.
+* @returns True if the control can hold the value; false otherwise.
 */
 function matchesField(field, value) {
 	if (isString(value) && value.length > 65536) return false;
@@ -548,7 +576,7 @@ function matchesField(field, value) {
 	}
 }
 /**
-* Decide whether a raw binding value projects to an answered field.
+* Decides whether a raw binding value projects to an answered field.
 *
 * @remarks
 * Bind with `fill(name, matchesAnswer(raw) ? raw : undefined)`. This projection treats an absent
@@ -557,13 +585,13 @@ function matchesField(field, value) {
 * its `required` rule remains presence-only.
 *
 * @param value - The raw field value, or absence.
-* @returns Whether the binding should preserve the value as an answer.
+* @returns True if the binding preserves the value as an answer; false otherwise.
 */
 function matchesAnswer(value) {
 	return value !== void 0 && (!isString(value) || value.trim().length > 0);
 }
 /**
-* Check whether a named rule applies to one field control.
+* Checks whether a named rule applies to one field control.
 *
 * @remarks
 * The runtime control-membership check keeps this boundary total for JavaScript callers that
@@ -571,7 +599,7 @@ function matchesAnswer(value) {
 *
 * @param control - The field control to inspect.
 * @param rule - The named rule to inspect.
-* @returns Whether the control evaluates that rule.
+* @returns True if the control evaluates that rule; false otherwise.
 */
 function appliesRule(control, rule) {
 	if (!FIELD_CONTROLS.some((candidate) => candidate === control)) return false;
@@ -589,23 +617,21 @@ function appliesRule(control, rule) {
 	return false;
 }
 /**
-* Evaluate one field rule against its current value.
+* Evaluates one field rule against its current value.
 *
 * @param field - The field and rule to evaluate.
 * @param value - The current value, or absence.
 * @param values - Every value available to a custom rule.
 * @param messages - Optional rule-specific message replacements.
 * @returns Every failure in rule order.
+* @throws Thrown when a {@link FieldValidator} supplied through {@link FieldRule.custom} throws:
+*   its own value escapes unchanged, because this helper adds no boundary around it.
 */
 function evaluateField(field, value, values, messages) {
 	const errors = [];
 	const rule = field.rule;
 	if (value === void 0) {
-		if (rule?.required === true && appliesRule(field.control, "required")) errors.push(Object.freeze({
-			field: field.name,
-			message: formatMessage("required", void 0, messages),
-			rule: "required"
-		}));
+		if (rule?.required === true && appliesRule(field.control, "required")) errors.push(createFieldError(field, "required", void 0, messages));
 	}
 	if (rule === void 0) return Object.freeze(errors);
 	if (rule.minimum !== void 0 && appliesRule(field.control, "minimum")) {
@@ -627,11 +653,7 @@ function evaluateField(field, value, values, messages) {
 			case "checkbox":
 			case "file": failed = isArray(value) && isFiniteNumber(rule.minimum) && value.length < rule.minimum;
 		}
-		if (failed) errors.push(Object.freeze({
-			field: field.name,
-			message: formatMessage("minimum", rule.minimum, messages),
-			rule: "minimum"
-		}));
+		if (failed) errors.push(createFieldError(field, "minimum", rule.minimum, messages));
 	}
 	if (rule.maximum !== void 0 && appliesRule(field.control, "maximum")) {
 		let failed = false;
@@ -652,63 +674,27 @@ function evaluateField(field, value, values, messages) {
 			case "checkbox":
 			case "file": failed = isArray(value) && isFiniteNumber(rule.maximum) && value.length > rule.maximum;
 		}
-		if (failed) errors.push(Object.freeze({
-			field: field.name,
-			message: formatMessage("maximum", rule.maximum, messages),
-			rule: "maximum"
-		}));
+		if (failed) errors.push(createFieldError(field, "maximum", rule.maximum, messages));
 	}
 	if (rule.step !== void 0 && appliesRule(field.control, "step") && isFiniteNumber(value)) {
 		const multiple = (value - (isFiniteNumber(rule.minimum) ? rule.minimum : 0)) / rule.step;
-		if (!isFiniteNumber(rule.step) || rule.step === 0 || !isFiniteNumber(multiple) || Math.abs(multiple - Math.round(multiple)) > 1e-9) errors.push(Object.freeze({
-			field: field.name,
-			message: formatMessage("step", rule.step, messages),
-			rule: "step"
-		}));
+		if (!isFiniteNumber(rule.step) || rule.step === 0 || !isFiniteNumber(multiple) || Math.abs(multiple - Math.round(multiple)) > 1e-9) errors.push(createFieldError(field, "step", rule.step, messages));
 	}
 	if (isString(value)) {
 		if (rule.pattern !== void 0 && appliesRule(field.control, "pattern")) {
 			const pattern = rule.pattern;
-			if (pattern.length > 256) errors.push(Object.freeze({
-				field: field.name,
-				message: formatMessage("pattern", void 0, messages),
-				rule: "pattern"
-			}));
+			if (pattern.length > 256) errors.push(createFieldError(field, "pattern", void 0, messages));
 			else {
 				const outcome = attempt(() => new RegExp(pattern).test(value));
-				if (!outcome.success || !outcome.value) errors.push(Object.freeze({
-					field: field.name,
-					message: formatMessage("pattern", void 0, messages),
-					rule: "pattern"
-				}));
+				if (!outcome.success || !outcome.value) errors.push(createFieldError(field, "pattern", void 0, messages));
 			}
 		}
-		if (rule.email === true && appliesRule(field.control, "email") && !EMAIL_PATTERN.test(value)) errors.push(Object.freeze({
-			field: field.name,
-			message: formatMessage("email", void 0, messages),
-			rule: "email"
-		}));
-		if (rule.url === true && appliesRule(field.control, "url") && !URL_PATTERN.test(value)) errors.push(Object.freeze({
-			field: field.name,
-			message: formatMessage("url", void 0, messages),
-			rule: "url"
-		}));
-		if (rule.alphanumeric === true && appliesRule(field.control, "alphanumeric") && !ALPHANUMERIC_PATTERN.test(value)) errors.push(Object.freeze({
-			field: field.name,
-			message: formatMessage("alphanumeric", void 0, messages),
-			rule: "alphanumeric"
-		}));
-		if (rule.integer === true && appliesRule(field.control, "integer") && !INTEGER_PATTERN.test(value)) errors.push(Object.freeze({
-			field: field.name,
-			message: formatMessage("integer", void 0, messages),
-			rule: "integer"
-		}));
+		if (rule.email === true && appliesRule(field.control, "email") && !EMAIL_PATTERN.test(value)) errors.push(createFieldError(field, "email", void 0, messages));
+		if (rule.url === true && appliesRule(field.control, "url") && !URL_PATTERN.test(value)) errors.push(createFieldError(field, "url", void 0, messages));
+		if (rule.alphanumeric === true && appliesRule(field.control, "alphanumeric") && !ALPHANUMERIC_PATTERN.test(value)) errors.push(createFieldError(field, "alphanumeric", void 0, messages));
+		if (rule.integer === true && appliesRule(field.control, "integer") && !INTEGER_PATTERN.test(value)) errors.push(createFieldError(field, "integer", void 0, messages));
 	}
-	if (value !== void 0 && field.control === "number" && rule.integer === true && appliesRule(field.control, "integer") && !isInteger(value)) errors.push(Object.freeze({
-		field: field.name,
-		message: formatMessage("integer", void 0, messages),
-		rule: "integer"
-	}));
+	if (value !== void 0 && field.control === "number" && rule.integer === true && appliesRule(field.control, "integer") && !isInteger(value)) errors.push(createFieldError(field, "integer", void 0, messages));
 	if (rule.custom !== void 0) {
 		const result = rule.custom(value, values);
 		if (isString(result)) errors.push(Object.freeze({
@@ -719,12 +705,14 @@ function evaluateField(field, value, values, messages) {
 	return Object.freeze(errors);
 }
 /**
-* Evaluate every active field in schema order.
+* Evaluates every active field in schema order.
 *
 * @param schema - The form schema to evaluate.
 * @param values - The values keyed by field name.
 * @param options - Optional message replacements and the effective disabled field set.
 * @returns Every field failure in schema and rule order.
+* @throws Thrown when a {@link FieldValidator} supplied through {@link FieldRule.custom} throws:
+*   its own value escapes unchanged, because this helper adds no boundary around it.
 */
 function evaluateForm(schema, values, options) {
 	const errors = [];
@@ -735,7 +723,11 @@ function evaluateForm(schema, values, options) {
 	return Object.freeze(errors);
 }
 /**
-* Compute the values explicitly seeded by a schema.
+* Computes the values explicitly seeded by a schema.
+*
+* @remarks
+* `password` and `file` declare no default, so a field of either control never appears in the
+* result.
 *
 * @param schema - The schema whose defaults to collect.
 * @returns A value record containing only fields with defaults.
@@ -744,12 +736,7 @@ function computeDefaults(schema) {
 	const defaults = {};
 	for (const field of schema.fields) switch (field.control) {
 		case "checkbox":
-			if (field.default !== void 0) Object.defineProperty(defaults, field.name, {
-				value: cloneValue(field.default),
-				enumerable: true,
-				configurable: true,
-				writable: true
-			});
+			if (field.default !== void 0) defineEntry(defaults, field.name, cloneValue(field.default));
 			break;
 		case "password":
 		case "file": break;
@@ -761,35 +748,30 @@ function computeDefaults(schema) {
 		case "datetime":
 		case "color":
 		case "confirm":
-		case "select": if (field.default !== void 0) Object.defineProperty(defaults, field.name, {
-			value: field.default,
-			enumerable: true,
-			configurable: true,
-			writable: true
-		});
+		case "select": if (field.default !== void 0) defineEntry(defaults, field.name, field.default);
 	}
 	return Object.freeze(defaults);
 }
 /**
-* Compare two field values by scalar identity or ordered list content.
+* Compares two field values by scalar identity or ordered list content.
 *
 * @param a - The first field value.
 * @param b - The second field value.
-* @returns Whether both values contain the same answer.
+* @returns True if both values contain the same answer; false otherwise.
 */
 function matchesValue(a, b) {
 	if (isArray(a) || isArray(b)) return isArray(a) && isArray(b) && a.length === b.length && a.every((entry, index) => entry === b[index]);
 	return a === b;
 }
 /**
-* Extract the names whose answers differ between two form value records.
+* Extracts the names whose answers differ between two form value records.
 *
 * @remarks
 * Presence is compared in both directions before present values are compared through
 * {@link matchesValue}. The returned set is a new snapshot, exposed as readonly because later
 * changes to either input never alter its membership.
 *
-* @param current - The values held now.
+* @param current - The values the form holds.
 * @param opened - The values held when the form opened.
 * @returns A readonly snapshot of changed field names.
 */
@@ -808,17 +790,21 @@ function extractChanges(current, opened) {
 	return changed;
 }
 /**
-* Compare two form value records by keys and value content.
+* Compares two form value records by keys and value content.
 *
 * @param a - The first value record.
 * @param b - The second value record.
-* @returns Whether both records contain the same answers.
+* @returns True if both records contain the same answers; false otherwise.
 */
 function matchesValues(a, b) {
 	return extractChanges(a, b).size === 0;
 }
 /**
-* Resolve and interpolate one rule message.
+* Resolves and interpolates one rule message.
+*
+* @remarks
+* A replacement in `messages` is read first and {@link RULE_MESSAGES} supplies the copy otherwise,
+* and `{limit}` in whichever text wins is replaced with the rule's operand.
 *
 * @param rule - The rule whose message to resolve.
 * @param limit - The optional operand substituted for `{limit}`.
@@ -830,7 +816,34 @@ function formatMessage(rule, limit, messages) {
 	return limit === void 0 ? message : message.replaceAll("{limit}", String(limit));
 }
 /**
-* Project a schema into JSON while removing custom validators and absent values.
+* Creates one named-rule failure against a field.
+*
+* @param field - The field the rule failed on.
+* @param rule - The named rule that failed.
+* @param limit - The rule's operand, substituted for `{limit}`, or absence when it carries none.
+* @param messages - Optional rule-specific message replacements.
+* @returns A frozen {@link FieldError} carrying the field's name, the resolved text, and the rule.
+*
+* @remarks
+* A `custom` validator and the form's `invalidate` method both report a message of their own
+* under no rule name, so neither builds its failure here.
+*
+* @example
+* ```ts
+* const field: FormField = { control: 'text', name: 'nickname', rule: { minimum: 3 } }
+* const error = createFieldError(field, 'minimum', 3)
+* error.message // 'Must be at least 3'
+* ```
+*/
+function createFieldError(field, rule, limit, messages) {
+	return Object.freeze({
+		field: field.name,
+		message: formatMessage(rule, limit, messages),
+		rule
+	});
+}
+/**
+* Projects a schema into JSON while removing custom validators and absent values.
 *
 * @param schema - The schema to project.
 * @returns A deep JSON copy of the serializable schema.
@@ -932,7 +945,7 @@ function serializeForm(schema) {
 	return cloneJSONRecord(output);
 }
 /**
-* Select referenced groups in first-reference field order.
+* Selects referenced groups in first-reference field order.
 *
 * @param schema - The schema whose group references to resolve.
 * @returns The referenced schema groups without duplicates.
@@ -947,7 +960,7 @@ function extractGroups(schema) {
 	return Object.freeze(groups);
 }
 /**
-* Audit a structurally valid schema for domain invariants.
+* Audits a structurally valid schema for domain invariants.
 *
 * @param schema - The form schema to audit.
 * @returns Human-readable invariant violations, or an empty list when the schema is sound.
@@ -1122,7 +1135,7 @@ function auditSchema(schema) {
 //#endregion
 //#region src/core/parsers.ts
 /**
-* Parse unknown wire data into an owned, semantically sound form schema.
+* Parses unknown wire data into an owned, semantically sound form schema.
 *
 * @param input - The unknown schema value to parse.
 * @returns An owned schema with custom rules removed, or `undefined` on refusal.
@@ -1133,12 +1146,7 @@ function parseForm(input) {
 		const schema = {};
 		for (const key of Reflect.ownKeys(input)) {
 			if (!isString(key)) return void 0;
-			Object.defineProperty(schema, key, {
-				value: input[key],
-				enumerable: true,
-				configurable: true,
-				writable: true
-			});
+			defineEntry(schema, key, input[key]);
 		}
 		const fields = schema.fields;
 		if (!isArray(fields)) return void 0;
@@ -1154,24 +1162,14 @@ function parseForm(input) {
 			const copy = {};
 			for (const key of Reflect.ownKeys(field)) {
 				if (!isString(key)) return void 0;
-				Object.defineProperty(copy, key, {
-					value: field[key],
-					enumerable: true,
-					configurable: true,
-					writable: true
-				});
+				defineEntry(copy, key, field[key]);
 			}
 			const rule = copy.rule;
 			if (isRecord(rule)) {
 				const projected = {};
 				for (const key of Reflect.ownKeys(rule)) {
 					if (!isString(key)) return void 0;
-					if (key !== "custom") Object.defineProperty(projected, key, {
-						value: rule[key],
-						enumerable: true,
-						configurable: true,
-						writable: true
-					});
+					if (key !== "custom") defineEntry(projected, key, rule[key]);
 				}
 				copy.rule = projected;
 			}
@@ -1185,7 +1183,11 @@ function parseForm(input) {
 	return outcome.success ? outcome.value : void 0;
 }
 /**
-* Parse one answer against its field control.
+* Parses one answer against its field control.
+*
+* @remarks
+* A numeric string coerces to a number for a `number` field, and `'true'` and `'false'` coerce to
+* a boolean for a `confirm` field. Every other value must already have its control's shape.
 *
 * @param field - The field that defines the accepted value.
 * @param input - The unknown value to parse.
@@ -1207,7 +1209,7 @@ function parseValue(field, input) {
 	return outcome.success ? outcome.value : void 0;
 }
 /**
-* Parse a strict answer record against the fields declared by a schema.
+* Parses a strict answer record against the fields declared by a schema.
 *
 * @param schema - The schema that owns the accepted field names and controls.
 * @param input - The unknown answer record to parse.
@@ -1223,12 +1225,7 @@ function parseValues(schema, input) {
 			if (field === void 0) return void 0;
 			const value = parseValue(field, input[key]);
 			if (value === void 0) return void 0;
-			Object.defineProperty(values, key, {
-				value,
-				enumerable: true,
-				configurable: false,
-				writable: false
-			});
+			freezeEntry(values, key, value);
 		}
 		return Object.freeze(values);
 	});
@@ -1237,7 +1234,8 @@ function parseValues(schema, input) {
 //#endregion
 //#region src/core/Form.ts
 /**
-* A form: a schema, the answers given against it, and the errors they carry.
+* Implements `FormInterface` exactly, over an owned schema, the answers given against it, and the
+* errors they carry.
 *
 * @remarks
 * The form owns its schema, so a later edit to the schema the caller passed changes nothing here.
@@ -1277,7 +1275,7 @@ var Form = class {
 	#evaluation = 0;
 	#pending = false;
 	/**
-	* Open a form against a schema.
+	* Opens a form against a schema.
 	*
 	* @param schema - The form to ask. It is copied, and the copy is what the form asks.
 	* @param options - The form's settings.
@@ -1286,93 +1284,76 @@ var Form = class {
 	*   value is one its field's control cannot hold.
 	*/
 	constructor(schema, options) {
-		const problems = isFormSchema(schema) ? auditSchema(schema) : ["The schema is not a form schema"];
-		if (problems.length > 0) throw new FormError("SCHEMA", `The form schema is unusable: ${problems.join("; ")}`, { problems: [...problems] });
-		this.#schema = cloneFormSchema(schema);
+		const owned = attempt(() => cloneFormSchema(schema));
+		if (!owned.success && isFormError(owned.error)) throw owned.error;
+		const copy = owned.success && isFormSchema(owned.value) ? owned.value : void 0;
+		const problems = copy === void 0 ? ["The schema is not a form schema"] : auditSchema(copy);
+		if (copy === void 0 || problems.length > 0) throw new FormError("SCHEMA", `The form schema is unusable: ${problems.join("; ")}`, { problems: [...problems] });
+		this.#schema = copy;
 		this.#messages = options?.messages === void 0 ? void 0 : Object.freeze({ ...options.messages });
 		const baseline = {};
-		for (const [name, value] of Object.entries(computeDefaults(this.#schema))) Object.defineProperty(baseline, name, {
-			value,
-			enumerable: true,
-			configurable: true,
-			writable: true
-		});
+		for (const [name, value] of Object.entries(computeDefaults(this.#schema))) defineEntry(baseline, name, value);
 		for (const [name, value] of Object.entries(options?.values ?? {})) {
 			const field = this.#requireField(name);
 			if (!matchesField(field, value)) throw new FormError("CONTROL", `The ${field.control} field "${name}" cannot hold that value`, {
 				field: name,
 				control: field.control
 			});
-			Object.defineProperty(baseline, name, {
-				value: cloneValue(value),
-				enumerable: true,
-				configurable: true,
-				writable: true
-			});
+			defineEntry(baseline, name, cloneValue(value));
 		}
 		this.#baseline = Object.freeze(baseline);
 		this.#values = {};
-		for (const [name, value] of Object.entries(baseline)) Object.defineProperty(this.#values, name, {
-			value,
-			enumerable: true,
-			configurable: true,
-			writable: true
-		});
+		for (const [name, value] of Object.entries(baseline)) defineEntry(this.#values, name, value);
 		this.#resolvers.promise.catch(() => void 0);
 		this.#emitter = new Emitter(options);
 		this.#evaluate();
 	}
-	/** The form's event emitter. */
+	/** Holds the form's event emitter. */
 	get emitter() {
 		return this.#emitter;
 	}
-	/** The schema this form asks, owned and frozen. */
+	/** Holds the schema this form asks, owned and frozen. */
 	get schema() {
 		return this.#schema;
 	}
-	/** The answers held right now. */
+	/** Reports the answers the form holds. */
 	get values() {
 		const values = {};
-		for (const name of Object.keys(this.#values)) Object.defineProperty(values, name, {
-			value: this.#values[name],
-			enumerable: true,
-			configurable: true,
-			writable: true
-		});
+		for (const [name, value] of Object.entries(this.#values)) defineEntry(values, name, value);
 		return Object.freeze(values);
 	}
-	/** The answers the form opened with. */
+	/** Holds the answers the form opened with. */
 	get baseline() {
 		return this.#baseline;
 	}
-	/** Every error the last completed evaluation produced. */
+	/** Holds every error the last completed evaluation produced. */
 	get errors() {
 		return this.#errors;
 	}
-	/** The names of the fields somebody has visited. */
+	/** Lists the names of the fields somebody has visited. */
 	get touched() {
 		return new Set(this.#touched);
 	}
-	/** The names of the fields currently out of the form. */
+	/** Lists the names of the fields that are out of the form. */
 	get disabled() {
 		const disabled = /* @__PURE__ */ new Set();
 		for (const field of this.#schema.fields) if ((this.#disabled.get(field.name) ?? field.disabled === true) === true) disabled.add(field.name);
 		return disabled;
 	}
-	/** Where the form sits in its life. */
+	/** Reports where the form sits in its life. */
 	get status() {
 		return this.#status;
 	}
-	/** Whether the last completed evaluation found no error. */
+	/** Reports whether the last completed evaluation found no error. */
 	get valid() {
 		return this.#errors.length === 0;
 	}
-	/** Whether any answer has moved since the form opened. */
+	/** Reports whether any answer has moved since the form opened. */
 	get dirty() {
 		return !matchesValues(this.values, this.#baseline);
 	}
 	/**
-	* The answers, once the form settles.
+	* Holds the answers after the form settles.
 	*
 	* @remarks
 	* It resolves with the submitted values on the first valid submit, and rejects with a
@@ -1382,7 +1363,7 @@ var Form = class {
 		return this.#resolvers.promise;
 	}
 	/**
-	* Find one field by name.
+	* Finds one field by name.
 	*
 	* @param name - The field's name.
 	* @returns The field, or `undefined` when the schema declares no such name.
@@ -1391,7 +1372,7 @@ var Form = class {
 		return this.#schema.fields.find((field) => field.name === name);
 	}
 	/**
-	* Answer one field or several.
+	* Answers one field or several.
 	*
 	* @param input - One field's name, or the answers to write keyed by field name.
 	* @param value - The answer to write when `input` names one field.
@@ -1414,12 +1395,7 @@ var Form = class {
 			for (const [name, answer] of entries) {
 				if (this.#differs(name, answer)) moved.push(name);
 				if (answer === void 0) delete this.#values[name];
-				else Object.defineProperty(this.#values, name, {
-					value: cloneValue(answer),
-					enumerable: true,
-					configurable: true,
-					writable: true
-				});
+				else defineEntry(this.#values, name, cloneValue(answer));
 				this.#invalidations.delete(name);
 			}
 			for (const name of moved) {
@@ -1430,7 +1406,7 @@ var Form = class {
 		});
 	}
 	/**
-	* Record that somebody has visited a field.
+	* Records that somebody has visited a field.
 	*
 	* @param name - The field's name.
 	* @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended, and
@@ -1442,7 +1418,7 @@ var Form = class {
 		this.#touched.add(name);
 	}
 	/**
-	* Fail a field from outside, for what the rules cannot see.
+	* Fails a field from outside, for what the rules cannot see.
 	*
 	* @param name - The field's name.
 	* @param message - What to tell the person.
@@ -1461,7 +1437,7 @@ var Form = class {
 		});
 	}
 	/**
-	* Take one or more fields out of the form.
+	* Takes one or more fields out of the form.
 	*
 	* @param input - One field name, several names, or absence to select every field.
 	* @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended, and
@@ -1473,7 +1449,7 @@ var Form = class {
 		this.#change(input, true);
 	}
 	/**
-	* Put one or more fields back into the form.
+	* Puts one or more fields back into the form.
 	*
 	* @param input - One field name, several names, or absence to select every field.
 	* @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended, and
@@ -1485,7 +1461,7 @@ var Form = class {
 		this.#change(input, false);
 	}
 	/**
-	* Check every answer and settle the form when they all pass.
+	* Checks every answer and settles the form when they all pass.
 	*
 	* @returns The values on success, or every error that stopped them.
 	* @remarks
@@ -1538,7 +1514,7 @@ var Form = class {
 		});
 	}
 	/**
-	* Return every answer to the ones the form opened with: the schema's defaults, overlaid with
+	* Returns every answer to the ones the form opened with: the schema's defaults, overlaid with
 	* any seeded `values`. Reset the runtime disabled state to the schema's declarations.
 	*
 	* @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended.
@@ -1547,12 +1523,7 @@ var Form = class {
 		this.#gate();
 		this.#batch(() => {
 			for (const name of Object.keys(this.#values)) delete this.#values[name];
-			for (const [name, value] of Object.entries(this.#baseline)) Object.defineProperty(this.#values, name, {
-				value,
-				enumerable: true,
-				configurable: true,
-				writable: true
-			});
+			for (const [name, value] of Object.entries(this.#baseline)) defineEntry(this.#values, name, value);
 			this.#touched.clear();
 			this.#disabled.clear();
 			this.#invalidations.clear();
@@ -1562,7 +1533,7 @@ var Form = class {
 		});
 	}
 	/**
-	* Tear the form down, abandoning it when it has not settled.
+	* Tears the form down, abandoning it when it has not settled.
 	*
 	* @remarks
 	* Destroying twice does nothing the second time. A settled form keeps its `settled` status and
@@ -1640,12 +1611,7 @@ var Form = class {
 		const disabled = this.disabled;
 		for (const field of this.#schema.fields) {
 			const value = Object.hasOwn(this.#values, field.name) ? this.#values[field.name] : void 0;
-			if (!disabled.has(field.name) && value !== void 0) Object.defineProperty(answers, field.name, {
-				value,
-				enumerable: true,
-				configurable: true,
-				writable: true
-			});
+			if (!disabled.has(field.name) && value !== void 0) defineEntry(answers, field.name, value);
 		}
 		return Object.freeze(answers);
 	}
@@ -1670,7 +1636,7 @@ var Form = class {
 //#endregion
 //#region src/core/factories.ts
 /**
-* Open a form against a schema.
+* Opens a form against a schema.
 *
 * @param schema - The form to ask. It is copied, and the copy is what the form asks.
 * @param options - The form's settings.
@@ -1681,8 +1647,10 @@ var Form = class {
 * @throws A {@link FormError} coded `SCHEMA` when the schema is malformed, `FIELD` when
 *   `options.values` names a field the schema does not declare, and `CONTROL` when a seeded value
 *   is one its field's control cannot hold.
-* @example
+* @example Open a form, answer it, and settle it
 * ```ts
+* import { createForm } from '@orkestrel/form'
+*
 * const form = createForm({
 * 	label: 'Sign up',
 * 	fields: [
@@ -1692,13 +1660,14 @@ var Form = class {
 * })
 *
 * form.fill({ email: 'ada@example.com', terms: true })
-* form.submit() // { success: true, value: { email: 'ada@example.com', terms: true } }
+* const result = form.submit() // { success: true, value: { email: 'ada@example.com', terms: true } }
+* const answers = await form.answer // { email: 'ada@example.com', terms: true }
 * ```
 */
 function createForm(schema, options) {
 	return new Form(schema, options);
 }
 //#endregion
-export { ALPHANUMERIC_PATTERN, CHOICE_LIMIT, COLOR_PATTERN, DATETIME_PATTERN, DATE_PATTERN, EMAIL_PATTERN, FIELD_CONTROLS, FIELD_LIMIT, FORM_STATUSES, Form, FormError, GROUP_LIMIT, INTEGER_PATTERN, LIST_LIMIT, NAME_LIMIT, NODE_LIMIT, PATTERN_LIMIT, RULE_MESSAGES, STRING_LIMIT, TEXT_LIMIT, TIME_PATTERN, URL_PATTERN, appliesRule, auditSchema, cloneChoices, cloneFormField, cloneFormSchema, cloneValue, computeDefaults, createForm, evaluateField, evaluateForm, extractChanges, extractGroups, formatMessage, isFieldChoice, isFieldControl, isFieldError, isFieldRule, isFieldValue, isFormError, isFormField, isFormGroup, isFormSchema, isFormStatus, isFormValues, matchesAnswer, matchesField, matchesValue, matchesValues, parseForm, parseValue, parseValues, serializeForm };
+export { ALPHANUMERIC_PATTERN, CHOICE_LIMIT, COLOR_PATTERN, DATETIME_PATTERN, DATE_PATTERN, EMAIL_PATTERN, FIELD_BASE_KEYS, FIELD_CONTROLS, FIELD_KEYS, FIELD_LIMIT, FORM_STATUSES, Form, FormError, GROUP_LIMIT, INTEGER_PATTERN, LIST_LIMIT, NAME_LIMIT, NODE_LIMIT, PATTERN_LIMIT, RULE_MESSAGES, STRING_LIMIT, TEXT_LIMIT, TIME_PATTERN, URL_PATTERN, appliesRule, auditSchema, cloneChoices, cloneFormField, cloneFormSchema, cloneValue, computeDefaults, createFieldError, createForm, defineEntry, evaluateField, evaluateForm, extractChanges, extractGroups, formatMessage, freezeEntry, isFieldChoice, isFieldControl, isFieldError, isFieldRule, isFieldValue, isFormError, isFormField, isFormGroup, isFormSchema, isFormStatus, isFormValues, matchesAnswer, matchesField, matchesValue, matchesValues, parseForm, parseValue, parseValues, serializeForm };
 
 //# sourceMappingURL=index.js.map