@orkestrel/form 0.0.5 → 0.0.7

package/README.md

@@ -1,14 +1,16 @@
 # @orkestrel/form
 
-The environment-agnostic form document for the `@orkestrel` line — a schema of field controls, the
-answers given against it, declarative validation carried as data, and a submit that settles exactly
-once. A terminal prompt and a browser form ask the same thing in different places, so this package
-ships what they share and neither renders nor reads input itself. Its `answer` promise is the
-parking seam a server needs: hand the document out, wait, receive the answers back. A live form can
-take a field out and put it back with `disable` and `enable`, and exported budgets bound what one
-schema and its answers may retain, so a document that arrives from a wire costs a known maximum
-before anything decides to trust it.
-Built on `@orkestrel/contract` and `@orkestrel/emitter`.
+> The environment-agnostic form document: a `FormSchema` stating what is asked, a `Form` holding
+> the answers given against it, declarative `FieldRule` data stating what those answers must
+> satisfy, and one submit that settles the form exactly once.
+
+A terminal prompt and a browser form ask the same thing in different places, so this package ships
+what they share and neither renders nor reads input itself. Its `answer` promise is the parking seam
+a server needs: hand the document out, wait, receive the answers back. A live form can take a field
+out and put it back with `disable` and `enable`, and exported budgets bound what one schema and its
+answers may retain, so a document that arrives from a wire costs a known maximum before anything
+decides to trust it. Built on `@orkestrel/contract` and `@orkestrel/emitter`, and part of the
+`@orkestrel` line.
 
 ## Install
 

package/dist/src/core/index.cjs

@@ -107,23 +107,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
@@ -166,7 +166,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 (0, _orkestrel_contract.isInstance)(input, FormError);
 }
 //#endregion
 //#region src/core/validators.ts
@@ -191,6 +191,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.
 */
@@ -350,6 +354,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.
 */
@@ -514,7 +522,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
@@ -534,6 +542,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.
@@ -714,6 +726,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.
 */
@@ -787,6 +803,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.
@@ -1166,6 +1186,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.
@@ -1211,7 +1235,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.
@@ -1623,8 +1648,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: [
@@ -1634,7 +1661,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) {