@bquery/bquery 1.6.0 → 1.8.1

package/src/forms/use-field.ts

@@ -0,0 +1,231 @@
+/**
+ * Standalone reactive field composable.
+ *
+ * @module bquery/forms
+ */
+
+import { debounce } from '../core/utils/function';
+import { isPromise } from '../core/utils/type-guards';
+import { Computed } from '../reactive/computed';
+import { Signal } from '../reactive/core';
+import { computed, effect, signal } from '../reactive/index';
+import type { MaybeSignal } from '../reactive/index';
+import { isReadonlySignal } from '../reactive/readonly';
+import type { UseFormFieldOptions, UseFormFieldReturn, ValidationResult, Validator } from './types';
+
+/**
+ * Determines whether a validator returned a valid result.
+ * @internal
+ */
+const isValidationSuccess = (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 isValidationSuccess(resolved) ? undefined : (resolved as string);
+};
+
+/**
+ * Creates a standalone reactive form field with optional automatic validation.
+ *
+ * This helper is useful when you want field-level state without creating a full form,
+ * or when you want to bind an existing signal to the forms validation model.
+ *
+ * @template T - The type of the field value
+ * @param initialValue - Plain initial value, an existing writable signal to reuse, or a
+ * computed / readonly reactive source to snapshot
+ * @param options - Validation mode, validators, debounce, and initial error configuration
+ * @returns A reactive field handle with validation helpers
+ *
+ * @example
+ * ```ts
+ * import { useFormField, required } from '@bquery/bquery/forms';
+ *
+ * const email = useFormField('', {
+ *   validators: [required()],
+ *   validateOn: 'blur',
+ * });
+ *
+ * email.value.value = 'ada@example.com';
+ * email.touch();
+ * ```
+ */
+export const useFormField = <T>(
+  initialValue: MaybeSignal<T>,
+  options: UseFormFieldOptions<T> = {}
+): UseFormFieldReturn<T> => {
+  let value: Signal<T>;
+
+  if (isSignal(initialValue)) {
+    value = initialValue as Signal<T>;
+  } else {
+    const startingValue: T =
+      isReadonlySignal<T>(initialValue) || isComputedValue<T>(initialValue)
+        ? initialValue.peek()
+        : (initialValue as T);
+    value = signal(startingValue);
+  }
+
+  const initial = value.peek();
+  const error = signal(options.initialError ?? '');
+  const isTouched = signal(false);
+  const isValidating = signal(false);
+  const isDirty = computed(() => !Object.is(value.value, initial));
+  const isPristine = computed(() => !isDirty.value);
+  const isValid = computed(() => error.value === '');
+  const validateOn = options.validateOn ?? 'manual';
+  const debounceMs = Math.max(0, options.debounceMs ?? 0);
+
+  let validationId = 0;
+  let changeInitialized = false;
+  let suppressNextChangeValidation = false;
+  let isDestroyed = false;
+  let stopChangeValidationEffect: (() => void) | undefined;
+
+  const logValidationError = (validationError: unknown): void => {
+    console.error('bQuery forms: Error in scheduled field validation', validationError);
+  };
+
+  const runValidation = async (): Promise<boolean> => {
+    const currentValidationId = ++validationId;
+    const validators = options.validators;
+
+    if (!validators || validators.length === 0) {
+      error.value = '';
+      isValidating.value = false;
+      return true;
+    }
+
+    isValidating.value = true;
+
+    try {
+      const currentValue = value.peek();
+
+      for (const validator of validators) {
+        const nextError = await runValidator(validator, currentValue);
+
+        if (currentValidationId !== validationId) {
+          return error.peek() === '';
+        }
+
+        if (nextError) {
+          error.value = nextError;
+          return false;
+        }
+      }
+
+      if (currentValidationId === validationId) {
+        error.value = '';
+      }
+      return true;
+    } finally {
+      if (currentValidationId === validationId) {
+        isValidating.value = false;
+      }
+    }
+  };
+
+  const debouncedValidate = debounce(() => {
+    void runValidation().catch(logValidationError);
+  }, debounceMs);
+
+  const scheduleValidation = (): void => {
+    if (isDestroyed) {
+      return;
+    }
+
+    if (debounceMs > 0) {
+      debouncedValidate();
+      return;
+    }
+
+    void runValidation().catch(logValidationError);
+  };
+
+  if (validateOn === 'change' || validateOn === 'both') {
+    stopChangeValidationEffect = effect(() => {
+      void value.value;
+
+      if (!changeInitialized) {
+        changeInitialized = true;
+        return;
+      }
+
+      if (suppressNextChangeValidation) {
+        suppressNextChangeValidation = false;
+        return;
+      }
+
+      scheduleValidation();
+    });
+  }
+
+  const destroy = (): void => {
+    if (isDestroyed) {
+      return;
+    }
+
+    isDestroyed = true;
+    validationId += 1;
+    debouncedValidate.cancel();
+    stopChangeValidationEffect?.();
+    stopChangeValidationEffect = undefined;
+    isDirty.dispose();
+    isPristine.dispose();
+    isValid.dispose();
+    isValidating.value = false;
+  };
+
+  return {
+    value,
+    error,
+    isDirty,
+    isTouched,
+    isPristine,
+    isValid,
+    isValidating,
+    touch: () => {
+      isTouched.value = true;
+      if (validateOn === 'blur' || validateOn === 'both') {
+        scheduleValidation();
+      }
+    },
+    reset: () => {
+      validationId += 1;
+      debouncedValidate.cancel();
+      if (!Object.is(value.peek(), initial)) {
+        suppressNextChangeValidation = true;
+      }
+      value.value = initial;
+      error.value = options.initialError ?? '';
+      isTouched.value = false;
+      isValidating.value = false;
+    },
+    validate: async () => {
+      debouncedValidate.cancel();
+      return runValidation();
+    },
+    destroy,
+  };
+};
+
+/**
+ * Determines whether a value looks like a writable signal.
+ * @internal
+ */
+const isSignal = (value: unknown): value is Signal<unknown> => {
+  return value instanceof Signal;
+};
+
+/**
+ * Determines whether a value is a computed reactive source.
+ * @internal
+ */
+const isComputedValue = <T>(value: unknown): value is Computed<T> => {
+  return value instanceof Computed;
+};

package/src/forms/validators.ts

@@ -0,0 +1,294 @@
+/**
+ * Built-in validation functions for form fields.
+ *
+ * Each factory returns a {@link SyncValidator} that can be passed
+ * to a field's `validators` array in {@link FormConfig}.
+ *
+ * @module bquery/forms
+ */
+
+import type { AsyncValidator, SyncValidator } from './types';
+
+/**
+ * Requires a non-empty value.
+ *
+ * Fails for `undefined`, `null`, empty strings (after trim), and empty arrays.
+ *
+ * @param message - Custom error message (default: `'This field is required'`)
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { required } from '@bquery/bquery/forms';
+ * const validate = required('Name is required');
+ * validate('');    // 'Name is required'
+ * validate('Ada'); // true
+ * ```
+ */
+export const required = (message = 'This field is required'): SyncValidator => {
+  return (value: unknown) => {
+    if (value == null) return message;
+    if (typeof value === 'string' && value.trim() === '') return message;
+    if (Array.isArray(value) && value.length === 0) return message;
+    return true;
+  };
+};
+
+/**
+ * Requires a string to have at least `len` characters.
+ *
+ * Non-string values are coerced via `String()` before checking length.
+ *
+ * @param len - Minimum length
+ * @param message - Custom error message
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { minLength } from '@bquery/bquery/forms';
+ * const validate = minLength(3);
+ * validate('ab');  // 'Must be at least 3 characters'
+ * validate('abc'); // true
+ * ```
+ */
+export const minLength = (len: number, message?: string): SyncValidator<unknown> => {
+  const msg = message ?? `Must be at least ${len} characters`;
+  return (value: unknown) => {
+    const str = typeof value === 'string' ? value : String(value ?? '');
+    return str.length >= len ? true : msg;
+  };
+};
+
+/**
+ * Requires a string to have at most `len` characters.
+ *
+ * Non-string values are coerced via `String()` before checking length.
+ *
+ * @param len - Maximum length
+ * @param message - Custom error message
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { maxLength } from '@bquery/bquery/forms';
+ * const validate = maxLength(10);
+ * validate('hello world!!'); // 'Must be at most 10 characters'
+ * validate('hello');         // true
+ * ```
+ */
+export const maxLength = (len: number, message?: string): SyncValidator<unknown> => {
+  const msg = message ?? `Must be at most ${len} characters`;
+  return (value: unknown) => {
+    const str = typeof value === 'string' ? value : String(value ?? '');
+    return str.length <= len ? true : msg;
+  };
+};
+
+/**
+ * Requires a string to match a regular expression pattern.
+ *
+ * Non-string values are coerced via `String()` before testing.
+ *
+ * @param regex - Pattern to test against
+ * @param message - Custom error message (default: `'Invalid format'`)
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { pattern } from '@bquery/bquery/forms';
+ * const validate = pattern(/^\d+$/, 'Numbers only');
+ * validate('abc'); // 'Numbers only'
+ * validate('123'); // true
+ * ```
+ */
+export const pattern = (regex: RegExp, message = 'Invalid format'): SyncValidator<unknown> => {
+  const safeRegex =
+    regex.global || regex.sticky
+      ? new RegExp(regex.source, regex.flags.replace(/[gy]/g, ''))
+      : regex;
+
+  return (value: unknown) => {
+    const str = typeof value === 'string' ? value : String(value ?? '');
+    safeRegex.lastIndex = 0;
+    return safeRegex.test(str) ? true : message;
+  };
+};
+
+/**
+ * RFC 5322–simplified email validation.
+ *
+ * @param message - Custom error message (default: `'Invalid email address'`)
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { email } from '@bquery/bquery/forms';
+ * const validate = email();
+ * validate('nope');          // 'Invalid email address'
+ * validate('ada@lovelace'); // 'Invalid email address'
+ * validate('ada@love.co');  // true
+ * ```
+ */
+export const email = (message = 'Invalid email address'): SyncValidator<unknown> => {
+  // Intentionally simple — covers the vast majority of valid addresses
+  // without re-implementing the full RFC 5322 grammar.
+  const re = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  return (value: unknown) => {
+    const str = typeof value === 'string' ? value : String(value ?? '');
+    if (str === '') return true; // empty is handled by `required`
+    return re.test(str) ? true : message;
+  };
+};
+
+/**
+ * Requires a string to be a valid URL.
+ *
+ * Uses the native `URL` constructor for validation.
+ *
+ * @param message - Custom error message (default: `'Invalid URL'`)
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { url } from '@bquery/bquery/forms';
+ * const validate = url();
+ * validate('not-a-url');                // 'Invalid URL'
+ * validate('https://example.com');      // true
+ * ```
+ */
+export const url = (message = 'Invalid URL'): SyncValidator<unknown> => {
+  return (value: unknown) => {
+    const str = typeof value === 'string' ? value : String(value ?? '');
+    if (str === '') return true; // empty is handled by `required`
+    try {
+      new URL(str);
+      return true;
+    } catch {
+      return message;
+    }
+  };
+};
+
+/**
+ * Requires a numeric value to be at least `limit`.
+ *
+ * @param limit - Minimum allowed value (inclusive)
+ * @param message - Custom error message
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { min } from '@bquery/bquery/forms';
+ * const validate = min(1, 'Must be positive');
+ * validate(0); // 'Must be positive'
+ * validate(1); // true
+ * ```
+ */
+export const min = (limit: number, message?: string): SyncValidator<unknown> => {
+  const msg = message ?? `Must be at least ${limit}`;
+  return (value: unknown) => {
+    if (value == null) return true;
+    if (typeof value === 'string' && value.trim() === '') return true;
+    const num = typeof value === 'number' ? value : Number(value);
+    return num >= limit ? true : msg;
+  };
+};
+
+/**
+ * Requires a numeric value to be at most `limit`.
+ *
+ * @param limit - Maximum allowed value (inclusive)
+ * @param message - Custom error message
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { max } from '@bquery/bquery/forms';
+ * const validate = max(100, 'Too high');
+ * validate(101); // 'Too high'
+ * validate(100); // true
+ * ```
+ */
+export const max = (limit: number, message?: string): SyncValidator<unknown> => {
+  const msg = message ?? `Must be at most ${limit}`;
+  return (value: unknown) => {
+    if (value == null) return true;
+    if (typeof value === 'string' && value.trim() === '') return true;
+    const num = typeof value === 'number' ? value : Number(value);
+    return num <= limit ? true : msg;
+  };
+};
+
+/**
+ * Creates a custom synchronous validator from any predicate function.
+ *
+ * @param fn - Predicate that returns `true` when the value is valid
+ * @param message - Error message when the predicate returns `false`
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { custom } from '@bquery/bquery/forms';
+ * const isEven = custom((v: number) => v % 2 === 0, 'Must be even');
+ * isEven(3); // 'Must be even'
+ * isEven(4); // true
+ * ```
+ */
+export const custom = <T = unknown>(
+  fn: (value: T) => boolean,
+  message: string
+): SyncValidator<T> => {
+  return (value: T) => (fn(value) ? true : message);
+};
+
+/**
+ * Creates a custom asynchronous validator.
+ *
+ * @param fn - Async predicate that resolves to `true` when valid
+ * @param message - Error message when the predicate resolves to `false`
+ * @returns An async validator function
+ *
+ * @example
+ * ```ts
+ * import { customAsync } from '@bquery/bquery/forms';
+ * const isUnique = customAsync(
+ *   async (name: string) => !(await checkExists(name)),
+ *   'Already taken',
+ * );
+ * ```
+ */
+export const customAsync = <T = unknown>(
+  fn: (value: T) => Promise<boolean>,
+  message: string
+): AsyncValidator<T> => {
+  return async (value: T) => ((await fn(value)) ? true : message);
+};
+
+/**
+ * Requires a field's value to match the current value of a reference signal.
+ *
+ * Typically used for "confirm password" or "confirm email" patterns where
+ * one field must have the same value as another.
+ *
+ * @param ref - A reactive signal whose current value is the comparison target
+ * @param message - Custom error message (default: `'Fields do not match'`)
+ * @returns A sync validator function
+ *
+ * @example
+ * ```ts
+ * import { signal } from '@bquery/bquery/reactive';
+ * import { matchField } from '@bquery/bquery/forms';
+ *
+ * const password = signal('secret');
+ * const confirmPassword = signal('');
+ * const validateConfirmPassword = matchField(password, 'Passwords must match');
+ *
+ * validateConfirmPassword(confirmPassword.value);
+ * ```
+ */
+export const matchField = <T>(
+  ref: { readonly value: T },
+  message = 'Fields do not match'
+): SyncValidator<T> => {
+  return (value: T) => (Object.is(value, ref.value) ? true : message);
+};