@orkestrel/form 0.0.5 → 0.0.7

package/dist/src/core/index.js

@@ -1,4 +1,4 @@
-import { arrayOf, attempt, cloneJSONRecord, isArray, isBoolean, isBoundedJSONRecord, isContractError, isFiniteNumber, isFunction, isInteger, isRecord, isString, keyOf, parseNumber, readArrayEntries, recordOf, unionOf } from "@orkestrel/contract";
+import { arrayOf, attempt, cloneJSONRecord, isArray, isBoolean, isBoundedJSONRecord, isContractError, isFiniteNumber, isFunction, isInstance, isInteger, isRecord, isString, keyOf, parseNumber, readArrayEntries, recordOf, unionOf } from "@orkestrel/contract";
 import { Emitter } from "@orkestrel/emitter";
 //#region src/core/constants.ts
 /** Lists every field control, in the order declared by the public contract. */
@@ -106,23 +106,23 @@ var DATE_PATTERN = Object.freeze(/^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01
 var TIME_PATTERN = Object.freeze(/^(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d)?$/);
 /** 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)?$/);
-/** Caps the accepted source length for an authored regular expression. */
+/** Caps the accepted source length for an authored regular expression, at 256. */
 var PATTERN_LIMIT = 256;
-/** Caps the number of fields one schema may declare. */
+/** Caps the number of fields one schema may declare, at 512. */
 var FIELD_LIMIT = 512;
-/** Caps the number of groups one schema may declare. */
+/** Caps the number of groups one schema may declare, at 64. */
 var GROUP_LIMIT = 64;
-/** Caps the 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;
-/** Caps the 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;
-/** Caps the 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;
-/** Caps the 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;
-/** Caps the 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;
-/** Caps the 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
@@ -165,7 +165,7 @@ var FormError = class extends Error {
 * @returns True if the value is a {@link FormError} instance; false otherwise.
 */
 function isFormError(input) {
-	return input instanceof FormError;
+	return isInstance(input, FormError);
 }
 //#endregion
 //#region src/core/validators.ts
@@ -190,6 +190,10 @@ function isFormStatus(input) {
 /**
 * 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 True if the value is a field value; false otherwise.
 */
@@ -349,6 +353,10 @@ function isFormGroup(input) {
 /**
 * 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 True if the value is a structurally valid form schema; false otherwise.
 */
@@ -513,7 +521,7 @@ function defineEntry(target, name, value) {
 *
 * @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 just filled.
+* configurable, so the record a parser hands back cannot be edited through the key it filled.
 *
 * @example
 * ```ts
@@ -533,6 +541,10 @@ function freezeEntry(target, name, value) {
 /**
 * 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 True if the control can hold the value; false otherwise.
@@ -713,6 +725,10 @@ function evaluateForm(schema, values, options) {
 /**
 * 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.
 */
@@ -786,6 +802,10 @@ function matchesValues(a, b) {
 /**
 * 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}`.
 * @param messages - Optional rule-specific message replacements.
@@ -1165,6 +1185,10 @@ function parseForm(input) {
 /**
 * 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.
 * @returns The typed or lexically coerced field value, or `undefined` on refusal.
@@ -1210,7 +1234,8 @@ function parseValues(schema, input) {
 //#endregion
 //#region src/core/Form.ts
 /**
-* Represents 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.
@@ -1622,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: [
@@ -1633,7 +1660,8 @@ 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) {