@bquery/bquery 1.6.0 → 1.8.1

package/src/forms/create-form.ts

@@ -0,0 +1,320 @@
+/**
+ * Reactive form creation and management.
+ *
+ * @module bquery/forms
+ */
+
+import { computed, signal } from '../reactive/index';
+import { isPrototypePollutionKey } from '../core/utils/object';
+import { isPromise } from '../core/utils/type-guards';
+import type {
+  CrossFieldValidator,
+  FieldConfig,
+  Form,
+  FormConfig,
+  FormErrors,
+  FormField,
+  FormFields,
+  ValidationResult,
+  Validator,
+} from './types';
+
+/**
+ * Determines whether a validator returned a valid result.
+ * @internal
+ */
+const isValid = (result: ValidationResult): boolean => result === true || result === undefined;
+
+/**
+ * Runs a single validator, normalising sync and async results.
+ * @internal
+ */
+const runValidator = async <T>(validator: Validator<T>, value: T): Promise<string | undefined> => {
+  const result = validator(value);
+  const resolved = isPromise(result) ? await result : result;
+  return isValid(resolved) ? undefined : (resolved as string);
+};
+
+/**
+ * Creates a reactive form field from its configuration.
+ * @internal
+ */
+const createField = <T>(config: FieldConfig<T>): FormField<T> => {
+  const initial = config.initialValue;
+  const value = signal<T>(initial);
+  const error = signal('');
+  const isTouched = signal(false);
+
+  const isDirty = computed(() => !Object.is(value.value, initial));
+  const isPristine = computed(() => !isDirty.value);
+
+  return {
+    value,
+    error,
+    isDirty,
+    isTouched,
+    isPristine,
+    touch: () => {
+      isTouched.value = true;
+    },
+    reset: () => {
+      value.value = initial;
+      error.value = '';
+      isTouched.value = false;
+    },
+  };
+};
+
+/**
+ * Validates a single field against its validators.
+ * Sets the field's error signal.
+ *
+ * @returns The first error message, or an empty string if valid.
+ * @internal
+ */
+const validateSingleField = async <T>(
+  field: FormField<T>,
+  validators: Validator<T>[] | undefined
+): Promise<string> => {
+  if (!validators || validators.length === 0) {
+    field.error.value = '';
+    return '';
+  }
+
+  for (const validator of validators) {
+    const errorMsg = await runValidator(validator, field.value.value);
+    if (errorMsg) {
+      field.error.value = errorMsg;
+      return errorMsg;
+    }
+  }
+
+  field.error.value = '';
+  return '';
+};
+
+/**
+ * Creates a fully reactive form with field-level validation,
+ * dirty/touched tracking, cross-field validation, and submission handling.
+ *
+ * Each field's `value`, `error`, `isDirty`, `isTouched`, and `isPristine`
+ * are reactive signals/computed values that can be used in effects, computed
+ * values, or directly read/written.
+ *
+ * @template T - Shape of the form values (e.g. `{ name: string; age: number }`)
+ * @param config - Form configuration with field definitions, validators, and submit handler
+ * @returns A reactive {@link Form} instance
+ *
+ * @example
+ * ```ts
+ * import { createForm, required, email, min } from '@bquery/bquery/forms';
+ *
+ * const form = createForm({
+ *   fields: {
+ *     name:  { initialValue: '', validators: [required()] },
+ *     email: { initialValue: '', validators: [required(), email()] },
+ *     age:   { initialValue: 0,  validators: [min(18, 'Must be 18+')] },
+ *   },
+ *   onSubmit: async (values) => {
+ *     await fetch('/api/register', {
+ *       method: 'POST',
+ *       body: JSON.stringify(values),
+ *     });
+ *   },
+ * });
+ *
+ * // Read reactive state
+ * console.log(form.isValid.value);          // true (initially, before validation runs)
+ * console.log(form.fields.name.value.value); // ''
+ *
+ * // Update a field
+ * form.fields.name.value.value = 'Ada';
+ *
+ * // Validate and submit
+ * await form.handleSubmit();
+ * ```
+ */
+export const createForm = <T extends Record<string, unknown>>(config: FormConfig<T>): Form<T> => {
+  // Build reactive field objects
+  const fieldEntries = Object.entries(config.fields) as [
+    keyof T & string,
+    FieldConfig<T[keyof T]>,
+  ][];
+
+  const fields = {} as FormFields<T>;
+  const errors = {} as FormErrors<T>;
+
+  for (const [name, fieldConfig] of fieldEntries) {
+    const field = createField(fieldConfig as FieldConfig<T[typeof name]>);
+    (fields as Record<string, FormField>)[name] = field;
+    (errors as Record<string, typeof field.error>)[name] = field.error;
+  }
+
+  const isSubmitting = signal(false);
+
+  // Computed: form is valid when all error signals are empty
+  const isFormValid = computed(() => {
+    for (const name of Object.keys(fields)) {
+      if ((fields as Record<string, FormField>)[name].error.value !== '') {
+        return false;
+      }
+    }
+    return true;
+  });
+
+  // Computed: form is dirty when any field is dirty
+  const isFormDirty = computed(() => {
+    for (const name of Object.keys(fields)) {
+      if ((fields as Record<string, FormField>)[name].isDirty.value) {
+        return true;
+      }
+    }
+    return false;
+  });
+
+  /**
+   * Validate a single field by name.
+   */
+  const validateField = async (name: keyof T & string): Promise<void> => {
+    const field = (fields as Record<string, FormField>)[name];
+    const fieldConfig = (config.fields as Record<string, FieldConfig>)[name];
+    if (!field || !fieldConfig) return;
+    await validateSingleField(field, fieldConfig.validators);
+  };
+
+  /**
+   * Validate all fields (per-field + cross-field).
+   * Returns `true` if the entire form is valid.
+   */
+  const validate = async (): Promise<boolean> => {
+    let hasError = false;
+
+    // Per-field validation
+    for (const [name, fieldConfig] of fieldEntries) {
+      const field = (fields as Record<string, FormField>)[name];
+      const error = await validateSingleField(field, (fieldConfig as FieldConfig).validators);
+      if (error) hasError = true;
+    }
+
+    // Cross-field validation
+    if (config.crossValidators && config.crossValidators.length > 0) {
+      const values = getValues();
+      for (const crossValidator of config.crossValidators as CrossFieldValidator<T>[]) {
+        const crossErrors = await crossValidator(values);
+        if (crossErrors) {
+          for (const [fieldName, errorMsg] of Object.entries(crossErrors) as [
+            string,
+            string | undefined,
+          ][]) {
+            if (errorMsg) {
+              const field = (fields as Record<string, FormField>)[fieldName];
+              if (field) {
+                // Only set cross-field error if no per-field error exists
+                if (field.error.value === '') {
+                  field.error.value = errorMsg;
+                }
+                hasError = true;
+              }
+            }
+          }
+        }
+      }
+    }
+
+    return !hasError;
+  };
+
+  /**
+   * Validate all fields and, if valid, invoke the onSubmit handler.
+   * Prevents concurrent submissions by setting isSubmitting before validation.
+   */
+  const handleSubmit = async (): Promise<void> => {
+    if (isSubmitting.value) return;
+    isSubmitting.value = true;
+
+    try {
+      const valid = await validate();
+      if (!valid) return;
+
+      if (config.onSubmit) {
+        await config.onSubmit(getValues());
+      }
+    } finally {
+      isSubmitting.value = false;
+    }
+  };
+
+  /**
+   * Reset every field to its initial value and clear all errors.
+   */
+  const reset = (): void => {
+    for (const name of Object.keys(fields)) {
+      (fields as Record<string, FormField>)[name].reset();
+    }
+  };
+
+  /**
+   * Return a plain object snapshot of all current field values.
+   */
+  const getValues = (): T => {
+    const values = {} as Record<string, unknown>;
+    for (const name of Object.keys(fields)) {
+      values[name] = (fields as Record<string, FormField>)[name].value.value;
+    }
+    return values as T;
+  };
+
+  /**
+   * Bulk-set field values from a partial object.
+   * Only fields present in the object are updated; missing keys are left unchanged.
+   */
+  const setValues = (values: Partial<T>): void => {
+    for (const [name, val] of Object.entries(values)) {
+      // Ignore inherited keys and prototype-pollution vectors before mutating field state.
+      if (isPrototypePollutionKey(name) || !Object.prototype.hasOwnProperty.call(fields, name)) {
+        continue;
+      }
+
+      const field = (fields as Record<string, FormField>)[name];
+      if (!field) {
+        continue;
+      }
+      field.value.value = val;
+    }
+  };
+
+  /**
+   * Bulk-set field error messages from a partial object.
+   * Useful for applying server-side validation errors.
+   * Only fields present in the object are updated; missing keys are left unchanged.
+   */
+  const setErrors = (errorMap: Partial<Record<keyof T & string, string>>): void => {
+    for (const [name, msg] of Object.entries(errorMap)) {
+      // Ignore inherited keys and prototype-pollution vectors before mutating field state.
+      if (isPrototypePollutionKey(name) || !Object.prototype.hasOwnProperty.call(fields, name)) {
+        continue;
+      }
+
+      const field = (fields as Record<string, FormField>)[name];
+      if (!field) {
+        continue;
+      }
+      field.error.value = (msg as string) ?? '';
+    }
+  };
+
+  return {
+    fields,
+    errors,
+    isValid: isFormValid,
+    isDirty: isFormDirty,
+    isSubmitting,
+    handleSubmit,
+    validateField,
+    validate,
+    reset,
+    getValues,
+    setValues,
+    setErrors,
+  };
+};

package/src/forms/index.ts

@@ -0,0 +1,70 @@
+/**
+ * Form handling module for bQuery.js.
+ *
+ * Provides a reactive, TypeScript-first form API with field-level
+ * and cross-field validation, dirty/touched tracking, and submission
+ * handling — all backed by bQuery's signal-based reactivity system.
+ *
+ * @module bquery/forms
+ *
+ * @example
+ * ```ts
+ * import { createForm, required, email, min } from '@bquery/bquery/forms';
+ *
+ * const form = createForm({
+ *   fields: {
+ *     name:  { initialValue: '', validators: [required()] },
+ *     email: { initialValue: '', validators: [required(), email()] },
+ *     age:   { initialValue: 0,  validators: [min(18, 'Must be 18+')] },
+ *   },
+ *   onSubmit: async (values) => {
+ *     await fetch('/api/register', {
+ *       method: 'POST',
+ *       body: JSON.stringify(values),
+ *     });
+ *   },
+ * });
+ *
+ * // Reactive access
+ * console.log(form.isValid.value);          // boolean
+ * console.log(form.fields.name.error.value); // '' or error message
+ *
+ * // Submit
+ * await form.handleSubmit();
+ * ```
+ */
+
+export { createForm } from './create-form';
+export { useFormField } from './use-field';
+
+export {
+  custom,
+  customAsync,
+  email,
+  matchField,
+  max,
+  maxLength,
+  min,
+  minLength,
+  pattern,
+  required,
+  url,
+} from './validators';
+
+export type {
+  AsyncValidator,
+  CrossFieldValidator,
+  FieldConfig,
+  Form,
+  FormConfig,
+  FormErrors,
+  FormField,
+  FormFieldValidationMode,
+  FormFields,
+  SubmitHandler,
+  SyncValidator,
+  UseFormFieldOptions,
+  UseFormFieldReturn,
+  ValidationResult,
+  Validator,
+} from './types';

package/src/forms/types.ts

@@ -0,0 +1,203 @@
+/**
+ * Form module types and interfaces.
+ *
+ * @module bquery/forms
+ */
+
+import type { Computed, Signal } from '../reactive/index';
+
+/**
+ * Result of a single validation rule.
+ * A string indicates an error message; `true` or `undefined` means valid.
+ */
+export type ValidationResult = string | true | undefined;
+
+/**
+ * Synchronous validator function.
+ *
+ * @param value - The current field value
+ * @returns A validation result — `true` / `undefined` for valid, or an error string
+ */
+export type SyncValidator<T = unknown> = (value: T) => ValidationResult;
+
+/**
+ * Asynchronous validator function.
+ *
+ * @param value - The current field value
+ * @returns A promise resolving to a validation result
+ */
+export type AsyncValidator<T = unknown> = (value: T) => Promise<ValidationResult>;
+
+/**
+ * Either a sync or async validator.
+ */
+export type Validator<T = unknown> = SyncValidator<T> | AsyncValidator<T>;
+
+/**
+ * Configuration for a single form field.
+ *
+ * @template T - The type of the field value
+ */
+export type FieldConfig<T = unknown> = {
+  /** Initial value for this field */
+  initialValue: T;
+  /** Validation rules applied in order; stops at first failure */
+  validators?: Validator<T>[];
+};
+
+/**
+ * Reactive state for a single form field.
+ *
+ * @template T - The type of the field value
+ */
+export type FormField<T = unknown> = {
+  /** Reactive signal holding the current value */
+  value: Signal<T>;
+  /** Reactive signal for the first validation error (empty string when valid) */
+  error: Signal<string>;
+  /** Whether the field value differs from its initial value */
+  isDirty: Computed<boolean>;
+  /** Whether the field has been interacted with (blur / explicit touch) */
+  isTouched: Signal<boolean>;
+  /** Whether the field has never been modified */
+  isPristine: Computed<boolean>;
+  /** Mark the field as touched */
+  touch: () => void;
+  /** Reset the field to its initial value and clear errors */
+  reset: () => void;
+};
+
+/**
+ * Controls when {@link useFormField} runs validation automatically.
+ */
+export type FormFieldValidationMode = 'manual' | 'change' | 'blur' | 'both';
+
+/**
+ * Configuration for {@link useFormField}.
+ *
+ * @template T - The type of the field value
+ */
+export type UseFormFieldOptions<T = unknown> = {
+  /** Validation rules applied in order; stops at first failure */
+  validators?: Validator<T>[];
+  /** When validation should run automatically. Defaults to `'manual'`. */
+  validateOn?: FormFieldValidationMode;
+  /** Delay automatic validation by the given milliseconds. Defaults to `0`. */
+  debounceMs?: number;
+  /** Initial error message for the field. Defaults to an empty string. */
+  initialError?: string;
+};
+
+/**
+ * Return value of {@link useFormField}.
+ *
+ * Extends the standard field state with validation helpers for standalone field usage.
+ *
+ * @template T - The type of the field value
+ */
+export type UseFormFieldReturn<T = unknown> = FormField<T> & {
+  /** Whether the current field has no validation error */
+  isValid: Computed<boolean>;
+  /** Reactive signal: `true` while async validation is still running */
+  isValidating: Signal<boolean>;
+  /** Validate the current field value immediately */
+  validate: () => Promise<boolean>;
+  /** Cancel pending timers and automatic validation subscriptions */
+  destroy: () => void;
+};
+
+/**
+ * Map of field names to their reactive field state.
+ */
+export type FormFields<T extends Record<string, unknown>> = {
+  [K in keyof T]: FormField<T[K]>;
+};
+
+/**
+ * Map of field names to their error strings (reactive signals).
+ */
+export type FormErrors<T extends Record<string, unknown>> = {
+  [K in keyof T]: Signal<string>;
+};
+
+/**
+ * Cross-field validation function.
+ * Receives all current field values and returns a map of field name → error message,
+ * or an empty object / undefined if all fields are valid.
+ */
+export type CrossFieldValidator<T extends Record<string, unknown>> = (
+  values: T
+) =>
+  | Partial<Record<keyof T, string>>
+  | undefined
+  | Promise<Partial<Record<keyof T, string>> | undefined>;
+
+/**
+ * Submit handler function.
+ *
+ * @template T - Shape of the form values
+ */
+export type SubmitHandler<T extends Record<string, unknown>> = (values: T) => void | Promise<void>;
+
+/**
+ * Configuration for `createForm()`.
+ *
+ * @template T - Shape of the form values
+ *
+ * @example
+ * ```ts
+ * const config: FormConfig<{ name: string; age: number }> = {
+ *   fields: {
+ *     name: { initialValue: '', validators: [required('Name is required')] },
+ *     age: { initialValue: 0, validators: [min(1, 'Must be positive')] },
+ *   },
+ *   onSubmit: (values) => console.log(values),
+ * };
+ * ```
+ */
+export type FormConfig<T extends Record<string, unknown>> = {
+  /** Per-field configuration with initial values and validators */
+  fields: { [K in keyof T]: FieldConfig<T[K]> };
+  /** Optional cross-field validators run after per-field validation */
+  crossValidators?: CrossFieldValidator<T>[];
+  /** Callback invoked on successful form submission */
+  onSubmit?: SubmitHandler<T>;
+};
+
+/**
+ * Return value of `createForm()`.
+ *
+ * @template T - Shape of the form values
+ */
+export type Form<T extends Record<string, unknown>> = {
+  /** Reactive field objects keyed by field name */
+  fields: FormFields<T>;
+  /** Shorthand error signals keyed by field name */
+  errors: FormErrors<T>;
+  /** Computed signal: `true` when all fields pass validation */
+  isValid: Computed<boolean>;
+  /** Computed signal: `true` when any field value differs from initial */
+  isDirty: Computed<boolean>;
+  /** Reactive signal: `true` while the submit handler is executing */
+  isSubmitting: Signal<boolean>;
+  /** Validate all fields and, if valid, call the `onSubmit` handler */
+  handleSubmit: () => Promise<void>;
+  /** Validate a single field by name */
+  validateField: (name: keyof T & string) => Promise<void>;
+  /** Validate all fields without submitting */
+  validate: () => Promise<boolean>;
+  /** Reset the entire form to initial values */
+  reset: () => void;
+  /** Get a snapshot of all current field values */
+  getValues: () => T;
+  /**
+   * Bulk-set field values from a partial object.
+   * Only fields present in the object are updated; missing keys are left unchanged.
+   */
+  setValues: (values: Partial<T>) => void;
+  /**
+   * Bulk-set field error messages from a partial object.
+   * Useful for applying server-side validation errors.
+   */
+  setErrors: (errors: Partial<Record<keyof T & string, string>>) => void;
+};