@octanejs/formisch 0.0.1

package/src/core/form/createFormStore/createFormStore.ts

@@ -0,0 +1,56 @@
+import type * as v from 'valibot';
+import { type FieldSchema, initializeFieldStore } from '../../field/index.ts';
+import { createSignal } from '../../framework/index.ts';
+import type { EmptyInput, FormConfig, FormSchema, InternalFormStore } from '../../types/index.ts';
+
+/**
+ * The default empty input of a form. Required string fields start as an empty
+ * string, while every other type starts as `undefined`.
+ */
+export const DEFAULT_EMPTY_INPUT: EmptyInput = { string: '' };
+
+/**
+ * Creates a new internal form store from the provided configuration.
+ * Initializes the field store hierarchy, sets validation modes, and
+ * creates form state signals.
+ *
+ * @param config The form configuration.
+ * @param parse The schema parse function.
+ *
+ * @returns The internal form store.
+ */
+// @__NO_SIDE_EFFECTS__
+export function createFormStore(
+	config: FormConfig,
+	parse: (input: unknown) => Promise<v.SafeParseResult<FormSchema>>,
+): InternalFormStore {
+	// Create partial store object
+	const store: Partial<InternalFormStore> = {};
+
+	// Merge configured empty input on top of the defaults before initializing so
+	// the field stores can read it from the form store
+	store.emptyInput = { ...DEFAULT_EMPTY_INPUT, ...config.emptyInput };
+
+	// Set form config and validation
+	store.validators = 0;
+	store.validate = config.validate ?? 'submit';
+	store.revalidate = config.revalidate ?? 'input';
+	store.parse = parse;
+
+	// Initialize form state signals
+	store.isSubmitting = createSignal(false);
+	store.isSubmitted = createSignal(false);
+	store.isValidating = createSignal(false);
+
+	// Initialize field store hierarchy from schema
+	initializeFieldStore(
+		store as InternalFormStore,
+		store,
+		config.schema as FieldSchema,
+		config.initialInput,
+		[],
+	);
+
+	// Return initialized store
+	return store as InternalFormStore;
+}

package/src/core/form/createFormStore/index.ts

@@ -0,0 +1 @@
+export * from './createFormStore.ts';

package/src/core/form/decodeFormData/decodeFormData.ts

@@ -0,0 +1,436 @@
+import type { FormSchema } from '../../types/index.ts';
+
+// Matches decimal number with optional sign, fraction and exponent (e.g. "42",
+// "-7", "+0.5", ".5", "1.5e3"), rejecting junk like hex or "Infinity"
+// eslint-disable-next-line security/detect-unsafe-regex
+const NUMBER_REGEX = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/u;
+
+// Matches timezone-less ISO date and time with optional seconds and fractional
+// seconds (e.g. "2023-06-15T14:30" or "2023-06-15T14:30:45.123"), as emitted by
+// `<input type="datetime-local">`
+const ISO_DATE_TIME_REGEX =
+	// eslint-disable-next-line security/detect-unsafe-regex
+	/^\d{4}-(?:0[1-9]|1[0-2])-(?:[12]\d|0[1-9]|3[01])T(?:0\d|1\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?$/u;
+
+// Hint: Maximum number of items allowed per array field. A numeric path
+// segment is used as an array index, so a single crafted key like
+// `["items",1000000000]` would set the array length to one billion. Creating
+// the sparse array is cheap, but every later pass that walks it by length
+// then runs in O(length), such as `fillDefaults` and the schema validation
+// the caller runs on the result. An array of booleans even writes a value at
+// every index, so a tiny request can exhaust CPU and memory. The limit is a
+// fixed number because a legitimate sparse array (one checked checkbox at a
+// high index, the rest unchecked and absent) is indistinguishable from an
+// attack; only the index magnitude differs. Throwing rather than truncating
+// avoids silently returning wrong data.
+const MAX_ARRAY_LENGTH = 5000;
+
+/**
+ * Internal schema type with the structural properties that are read while
+ * traversing a Valibot schema.
+ */
+interface InternalSchema {
+	readonly type: string;
+	readonly wrapped?: InternalSchema;
+	readonly getter?: (input: undefined) => InternalSchema;
+	readonly entries?: Record<string, InternalSchema>;
+	readonly item?: InternalSchema;
+	readonly items?: InternalSchema[];
+	readonly options?: InternalSchema[];
+}
+
+/**
+ * Unwraps wrapper and lazy schemas until a concrete schema is reached.
+ *
+ * @param schema The schema to unwrap.
+ *
+ * @returns The unwrapped schema.
+ */
+function unwrapSchema(schema: InternalSchema): InternalSchema {
+	switch (schema.type) {
+		case 'exact_optional':
+		case 'nullable':
+		case 'nullish':
+		case 'optional':
+		case 'undefinedable':
+		case 'non_nullable':
+		case 'non_nullish':
+		case 'non_optional':
+			return unwrapSchema(schema.wrapped!);
+		case 'lazy':
+			return unwrapSchema(schema.getter!(undefined));
+		default:
+			return schema;
+	}
+}
+
+/**
+ * Returns the child schema for the given key by traversing objects, arrays,
+ * tuples and schema options. Returns `undefined` if no child schema is found.
+ *
+ * @param schema The parent schema.
+ * @param key The path key.
+ *
+ * @returns The child schema or `undefined`.
+ */
+function getChildSchema(
+	schema: InternalSchema | undefined,
+	key: string | number,
+): InternalSchema | undefined {
+	if (schema) {
+		// Unwrap schema before reading its structure
+		const unwrapped = unwrapSchema(schema);
+
+		// If schema is object, return entry schema
+		if (
+			unwrapped.type === 'object' ||
+			unwrapped.type === 'loose_object' ||
+			unwrapped.type === 'strict_object'
+		) {
+			return unwrapped.entries![key];
+		}
+
+		// If schema is array, return item schema
+		if (unwrapped.type === 'array') {
+			return unwrapped.item;
+		}
+
+		// If schema is tuple, return item schema at index
+		if (
+			unwrapped.type === 'tuple' ||
+			unwrapped.type === 'loose_tuple' ||
+			unwrapped.type === 'strict_tuple'
+		) {
+			return unwrapped.items![key as number];
+		}
+
+		// If schema has options, return first matching child schema
+		if (
+			unwrapped.type === 'union' ||
+			unwrapped.type === 'intersect' ||
+			unwrapped.type === 'variant'
+		) {
+			// Hint: The first matching option is used. For a union or variant where
+			// the same key has different types across options, the value is decoded
+			// based on the first option, since the matching branch is only known
+			// during validation.
+			for (const option of unwrapped.options!) {
+				const childSchema = getChildSchema(option, key);
+				if (childSchema !== undefined) {
+					return childSchema;
+				}
+			}
+		}
+	}
+}
+
+/**
+ * Decodes a stringified date based on its format. Empty strings become `null`.
+ *
+ * @param value The stringified value.
+ *
+ * @returns The decoded date.
+ */
+function decodeDate(value: string): Date | null | undefined {
+	if (!value || value === 'null') {
+		return null;
+	}
+	if (value === 'undefined') {
+		return undefined;
+	}
+	// Hint: A timezone-less date and time (from `<input type="datetime-local">`)
+	// is interpreted as local time by `new Date`, so it is forced to UTC. Dates,
+	// months and full timestamps are already parsed as UTC.
+	if (ISO_DATE_TIME_REGEX.test(value)) {
+		return new Date(`${value}Z`);
+	}
+	return new Date(value);
+}
+
+/**
+ * Decodes a stringified boolean. Empty strings become `null`.
+ *
+ * @param value The stringified value.
+ *
+ * @returns The decoded boolean.
+ */
+function decodeBoolean(value: string): boolean | null | undefined {
+	if (!value || value === 'null') {
+		return null;
+	}
+	if (value === 'undefined') {
+		return undefined;
+	}
+	return !(value === 'false' || value === 'off' || value === '0');
+}
+
+/**
+ * Decodes a stringified number. Empty strings become `null` and non-numeric
+ * values become `NaN`.
+ *
+ * @param value The stringified value.
+ *
+ * @returns The decoded number.
+ */
+function decodeNumber(value: string): number | null | undefined {
+	if (!value || value === 'null') {
+		return null;
+	}
+	if (value === 'undefined') {
+		return undefined;
+	}
+	if (NUMBER_REGEX.test(value)) {
+		return Number(value);
+	}
+	return NaN;
+}
+
+/**
+ * Decodes a stringified bigint. Empty strings become `null` and invalid values
+ * are returned unchanged.
+ *
+ * @param value The stringified value.
+ *
+ * @returns The decoded bigint.
+ */
+function decodeBigint(value: string): bigint | string | null | undefined {
+	if (!value || value === 'null') {
+		return null;
+	}
+	if (value === 'undefined') {
+		return undefined;
+	}
+	try {
+		return BigInt(value);
+	} catch {
+		return value;
+	}
+}
+
+/**
+ * Decodes a single form data value based on the concrete schema type. Files
+ * and unknown types are returned unchanged.
+ *
+ * @param value The form data value.
+ * @param schema The schema of the value.
+ *
+ * @returns The decoded value.
+ */
+function decodeValue(value: FormDataEntryValue, schema: InternalSchema | undefined): unknown {
+	// Non-string values (files) and unknown schemas are returned unchanged
+	if (typeof value !== 'string' || !schema) {
+		return value;
+	}
+
+	// Decode value based on concrete schema type
+	switch (unwrapSchema(schema).type) {
+		case 'number':
+			return decodeNumber(value);
+		case 'boolean':
+			return decodeBoolean(value);
+		case 'date':
+			return decodeDate(value);
+		case 'bigint':
+			return decodeBigint(value);
+		default:
+			return value;
+	}
+}
+
+/**
+ * Fills in default values that are lost during the form data transfer. Booleans
+ * of unchecked checkboxes become `false` and absent arrays become empty. Only
+ * containers that are present in the decoded data are completed.
+ *
+ * @param schema The schema of the value.
+ * @param parent The parent object or array holding the value.
+ * @param key The key of the value within its parent.
+ */
+function fillDefaults(
+	schema: InternalSchema,
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	parent: any,
+	key: string | number,
+): void {
+	// Unwrap schema before reading its structure
+	const unwrappedSchema = unwrapSchema(schema);
+
+	// If schema is boolean, default absent (unchecked checkbox) values to `false`
+	// Hint: Only `undefined` is treated as absent so that a decoded `null` (e.g.
+	// from a nullable boolean) is preserved instead of being coerced to `false`.
+	if (unwrappedSchema.type === 'boolean') {
+		if (parent[key] === undefined) {
+			parent[key] = false;
+		}
+
+		// Otherwise, if schema is array, default absent arrays and complete items
+	} else if (unwrappedSchema.type === 'array') {
+		if (Array.isArray(parent[key])) {
+			for (let index = 0; index < parent[key].length; index++) {
+				fillDefaults(unwrappedSchema.item!, parent[key], index);
+			}
+		} else {
+			parent[key] = [];
+		}
+
+		// Otherwise, if schema is tuple, complete items of present tuples
+	} else if (
+		unwrappedSchema.type === 'tuple' ||
+		unwrappedSchema.type === 'loose_tuple' ||
+		unwrappedSchema.type === 'strict_tuple'
+	) {
+		if (Array.isArray(parent[key])) {
+			for (let index = 0; index < unwrappedSchema.items!.length; index++) {
+				fillDefaults(unwrappedSchema.items![index], parent[key], index);
+			}
+		}
+
+		// Otherwise, if schema is object, complete present entries
+	} else if (
+		unwrappedSchema.type === 'object' ||
+		unwrappedSchema.type === 'loose_object' ||
+		unwrappedSchema.type === 'strict_object'
+	) {
+		if (parent[key] && typeof parent[key] === 'object') {
+			for (const entryKey in unwrappedSchema.entries) {
+				fillDefaults(unwrappedSchema.entries[entryKey], parent[key], entryKey);
+			}
+		}
+
+		// Otherwise, if schema has options, complete for each option
+		// Hint: Defaults from every option are applied because the matching branch
+		// of a union or variant is only known during validation, not while
+		// decoding. This is correct for intersect (all options apply) and harmless
+		// for object options (unknown keys are ignored on parse). A `strictObject`
+		// option may reject the extra keys though, so reliably decoding such a
+		// variant would require resolving its branch via the discriminator, which
+		// is not possible before validation.
+	} else if (
+		unwrappedSchema.type === 'union' ||
+		unwrappedSchema.type === 'intersect' ||
+		unwrappedSchema.type === 'variant'
+	) {
+		for (const option of unwrappedSchema.options!) {
+			fillDefaults(option, parent, key);
+		}
+	}
+}
+
+/**
+ * Decodes the entries of a form data object into nested form values using the
+ * Valibot schema as the source of truth. Information that is lost during the
+ * transfer via HTTP, like numbers, booleans, dates and unchecked checkboxes,
+ * is restored based on the schema.
+ *
+ * The keys of the form data are expected to be the stringified field paths that
+ * Formisch assigns to its field elements (for example `["todos",0,"label"]`).
+ *
+ * @param schema The form schema.
+ * @param formData The form data object.
+ *
+ * @returns The decoded form values.
+ */
+// @__NO_SIDE_EFFECTS__
+export function decodeFormData<TSchema extends FormSchema>(
+	schema: TSchema,
+	formData: FormData,
+): unknown {
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	const values: any = {};
+
+	// Build nested values from form data entries
+	formData.forEach((value, key) => {
+		// Convert stringified key back to field path array, ignore invalid JSON
+		let path: unknown = null;
+		try {
+			path = JSON.parse(key);
+		} catch {
+			// Ignore invalid JSON keys
+		}
+
+		// Only process valid, non-empty field paths whose value is not empty
+		// (unselected) file input
+		if (
+			Array.isArray(path) &&
+			path.length > 0 &&
+			(typeof value === 'string' || value.size > 0 || value.name !== '')
+		) {
+			// Create temporary references for parent value and schema
+			let parentValue = values;
+			let parentSchema: InternalSchema | undefined = schema as InternalSchema;
+
+			// Traverse path segments and build nested structure based on schema
+			for (let index = 0; index < path.length; index++) {
+				const segment = path[index];
+
+				// Skip invalid keys and keys that could pollute object prototype
+				if (
+					(typeof segment !== 'string' && typeof segment !== 'number') ||
+					segment === '' ||
+					segment === '__proto__' ||
+					segment === 'prototype' ||
+					segment === 'constructor'
+				) {
+					break;
+				}
+
+				// Arrays are indexed by numbers; string segments would write properties
+				// like `length` or `push` that inflate or corrupt them
+				if (Array.isArray(parentValue)) {
+					if (typeof segment === 'string') {
+						break;
+					}
+
+					// Throw on oversized array index (see MAX_ARRAY_LENGTH)
+					if (segment >= MAX_ARRAY_LENGTH) {
+						throw new Error(`Array exceeds the maximum length of ${MAX_ARRAY_LENGTH}`);
+					}
+				}
+
+				// Get child schema for current segment
+				const childSchema = getChildSchema(parentSchema, segment);
+
+				// If segment is last one, set or append decoded value
+				if (index === path.length - 1) {
+					const unwrappedSchema = childSchema && unwrapSchema(childSchema);
+
+					// If schema is dynamic array, append decoded item
+					if (unwrappedSchema && unwrappedSchema.type === 'array') {
+						parentValue[segment] ??= [];
+						parentValue[segment].push(decodeValue(value, unwrappedSchema.item));
+
+						// Otherwise, set decoded value
+					} else {
+						parentValue[segment] = decodeValue(value, childSchema);
+					}
+
+					// Otherwise, create next container and continue traversing
+				} else {
+					if (parentValue[segment] == null) {
+						// Create array for array and tuple schemas, object otherwise
+						const schemaType = childSchema && unwrapSchema(childSchema).type;
+						parentValue[segment] =
+							schemaType === 'array' ||
+							schemaType === 'tuple' ||
+							schemaType === 'loose_tuple' ||
+							schemaType === 'strict_tuple'
+								? []
+								: {};
+
+						// Otherwise, stop on conflicting scalar value to avoid writing a
+						// property to a non-object, which throws in strict mode
+					} else if (typeof parentValue[segment] !== 'object') {
+						break;
+					}
+					parentValue = parentValue[segment];
+					parentSchema = childSchema;
+				}
+			}
+		}
+	});
+
+	// Fill in default values that are lost during transfer
+	fillDefaults(schema as InternalSchema, { values }, 'values');
+
+	return values;
+}

package/src/core/form/decodeFormData/index.ts

@@ -0,0 +1 @@
+export * from './decodeFormData.ts';

package/src/core/form/index.ts

@@ -0,0 +1,4 @@
+export * from './createFormStore/index.ts';
+export * from './decodeFormData/index.ts';
+export * from './validateFormInput/index.ts';
+export * from './validateIfRequired/index.ts';

package/src/core/form/validateFormInput/index.ts

@@ -0,0 +1 @@
+export * from './validateFormInput.ts';

package/src/core/form/validateFormInput/validateFormInput.ts

@@ -0,0 +1,138 @@
+import type * as v from 'valibot';
+import { focusFieldElement, getFieldInput, walkFieldStore } from '../../field/index.ts';
+import { batch, untrack } from '../../framework/index.ts';
+import type { InternalFormStore, Schema } from '../../types/index.ts';
+
+/**
+ * Validate form input config interface.
+ */
+export interface ValidateFormInputConfig {
+	/**
+	 * Whether to focus the first field with an error.
+	 */
+	readonly shouldFocus?: boolean | undefined;
+}
+
+/**
+ * Validates the form input using the configured Valibot schema. Parses the
+ * current form input, processes validation issues, assigns errors to fields,
+ * and optionally focuses the first field with an error.
+ *
+ * @param internalFormStore The form store to validate.
+ * @param config The validation configuration.
+ *
+ * @returns The Valibot validation result.
+ */
+export async function validateFormInput(
+	internalFormStore: InternalFormStore,
+	config?: ValidateFormInputConfig,
+): Promise<v.SafeParseResult<Schema>> {
+	// Update validation state
+	internalFormStore.validators++;
+	internalFormStore.isValidating.value = true;
+
+	try {
+		// Parse form input with Valibot schema
+		const result = await internalFormStore.parse(untrack(() => getFieldInput(internalFormStore)));
+
+		// Create variables for root and nested errors
+		let rootErrors: [string, ...string[]] | undefined;
+		let nestedErrors: Record<string, [string, ...string[]] | undefined> | undefined;
+
+		// Process validation issues into error variables
+		if (result.issues) {
+			// Initialize nested errors object
+			nestedErrors = {};
+
+			// Process each validation issue
+			for (const issue of result.issues) {
+				// If issue has path, assign to nested errors
+				if (issue.path) {
+					// Initialize path array
+					const path = [];
+
+					// Build path from issue path items
+					for (const pathItem of issue.path) {
+						const key = pathItem.key;
+						const keyType = typeof key;
+						const itemType = pathItem.type;
+						// Skip unsupported path types
+						if (
+							(keyType !== 'string' && keyType !== 'number') ||
+							itemType === 'map' ||
+							itemType === 'set'
+						) {
+							break;
+						}
+
+						// Add key to path
+						path.push(key);
+					}
+
+					// Convert path to name of field
+					const name = JSON.stringify(path);
+
+					// Append or initialize nested errors
+					const fieldErrors = nestedErrors[name];
+					if (fieldErrors) {
+						fieldErrors.push(issue.message);
+					} else {
+						nestedErrors[name] = [issue.message];
+					}
+
+					// Otherwise, assign to root errors
+				} else {
+					if (rootErrors) {
+						rootErrors.push(issue.message);
+					} else {
+						rootErrors = [issue.message];
+					}
+				}
+			}
+		}
+
+		// Create variable to decide if first error field should be focused
+		let shouldFocus = config?.shouldFocus ?? false;
+
+		// Batch error, focus and validation state updates together so reactive
+		// subscribers observe a single consistent update
+		batch(() => {
+			// Untracked to avoid subscribing a surrounding reactive scope to the
+			// form structure.
+			untrack(() => {
+				// Set or reset errors on each field store.
+				walkFieldStore(internalFormStore, (internalFieldStore) => {
+					if (internalFieldStore.path.length === 0) {
+						internalFieldStore.errors.value = rootErrors ?? null;
+					} else {
+						const fieldErrors = nestedErrors?.[internalFieldStore.name] ?? null;
+						internalFieldStore.errors.value = fieldErrors;
+
+						// Focus the first erroring field whose element can actually receive
+						// focus, so the focus is not consumed by a field without a focusable
+						// element (e.g. unmounted or hidden)
+						if (shouldFocus && fieldErrors && focusFieldElement(internalFieldStore)) {
+							shouldFocus = false;
+						}
+					}
+				});
+			});
+
+			// Reset validation state of form
+			internalFormStore.validators--;
+			internalFormStore.isValidating.value = internalFormStore.validators > 0;
+		});
+
+		// Return validation result
+		return result;
+
+		// If parsing throws, still reset validation state so form does not stay
+		// stuck in a validating state
+	} catch (error) {
+		batch(() => {
+			internalFormStore.validators--;
+			internalFormStore.isValidating.value = internalFormStore.validators > 0;
+		});
+		throw error;
+	}
+}

package/src/core/form/validateIfRequired/index.ts

@@ -0,0 +1 @@
+export * from './validateIfRequired.ts';

package/src/core/form/validateIfRequired/validateIfRequired.ts

@@ -0,0 +1,31 @@
+import { getFieldBool } from '../../field/index.ts';
+import { untrack } from '../../framework/index.ts';
+import type { InternalFieldStore, InternalFormStore, ValidationMode } from '../../types/index.ts';
+import { validateFormInput } from '../validateFormInput/validateFormInput.ts';
+
+/**
+ * Validates the form input if required based on the validation mode and form
+ * state. Determines whether to use initial validation mode, revalidation mode,
+ * or skip validation entirely.
+ *
+ * @param internalFormStore The form store to validate.
+ * @param internalFieldStore The field store that triggered validation.
+ * @param validationMode The validation mode that triggered this check.
+ */
+export function validateIfRequired(
+	internalFormStore: InternalFormStore,
+	internalFieldStore: InternalFieldStore,
+	validationMode: ValidationMode,
+): void {
+	if (
+		validationMode ===
+		(internalFormStore.validate === 'initial' ||
+		(internalFormStore.validate === 'submit'
+			? untrack(() => internalFormStore.isSubmitted.value)
+			: untrack(() => getFieldBool(internalFieldStore, 'errors')))
+			? internalFormStore.revalidate
+			: internalFormStore.validate)
+	) {
+		validateFormInput(internalFormStore);
+	}
+}