feat(core): debounced form listeners

Author: harry-whorlow

packages/form-core/src/FieldApi.d.ts

@@ -978,6 +978,7 @@ export class FieldApi<
   timeoutIds: {
     validations: Record<ValidationCause, ReturnType<typeof setTimeout> | null>
     listeners: Record<ListenerCause, ReturnType<typeof setTimeout> | null>
+    formListeners: Record<ListenerCause, ReturnType<typeof setTimeout> | null>
   }
 
   /**
@@ -1011,6 +1012,7 @@ export class FieldApi<
     this.timeoutIds = {
       validations: {} as Record<ValidationCause, never>,
       listeners: {} as Record<ListenerCause, never>,
+      formListeners: {} as Record<ListenerCause, never>,
     }
 
     this.store = new Derived({
@@ -1703,13 +1705,27 @@ export class FieldApi<
   }
 
   private triggerOnBlurListener() {
-    const debounceMs = this.options.listeners?.onBlurDebounceMs
-    this.form.options.listeners?.onBlur?.({
-      formApi: this.form,
-      fieldApi: this,
-    })
+    const formDebounceMs = this.form.options.listeners?.onBlurDebounceMs
+    if (formDebounceMs && formDebounceMs > 0) {
+      if (this.timeoutIds.formListeners.blur) {
+        clearTimeout(this.timeoutIds.formListeners.blur)
+      }
+
+      this.timeoutIds.formListeners.blur = setTimeout(() => {
+        this.form.options.listeners?.onBlur?.({
+          formApi: this.form,
+          fieldApi: this,
+        })
+      }, formDebounceMs)
+    } else {
+      this.form.options.listeners?.onBlur?.({
+        formApi: this.form,
+        fieldApi: this,
+      })
+    }
 
-    if (debounceMs && debounceMs > 0) {
+    const fieldDebounceMs = this.options.listeners?.onBlurDebounceMs
+    if (fieldDebounceMs && fieldDebounceMs > 0) {
       if (this.timeoutIds.listeners.blur) {
         clearTimeout(this.timeoutIds.listeners.blur)
       }
@@ -1719,7 +1735,7 @@ export class FieldApi<
           value: this.state.value,
           fieldApi: this,
         })
-      }, debounceMs)
+      }, fieldDebounceMs)
     } else {
       this.options.listeners?.onBlur?.({
         value: this.state.value,
@@ -1729,14 +1745,27 @@ export class FieldApi<
   }
 
   private triggerOnChangeListener() {
-    const debounceMs = this.options.listeners?.onChangeDebounceMs
+    const formDebounceMs = this.form.options.listeners?.onChangeDebounceMs
+    if (formDebounceMs && formDebounceMs > 0) {
+      if (this.timeoutIds.formListeners.blur) {
+        clearTimeout(this.timeoutIds.formListeners.blur)
+      }
 
-    this.form.options.listeners?.onChange?.({
-      formApi: this.form,
-      fieldApi: this,
-    })
+      this.timeoutIds.formListeners.blur = setTimeout(() => {
+        this.form.options.listeners?.onChange?.({
+          formApi: this.form,
+          fieldApi: this,
+        })
+      }, formDebounceMs)
+    } else {
+      this.form.options.listeners?.onChange?.({
+        formApi: this.form,
+        fieldApi: this,
+      })
+    }
 
-    if (debounceMs && debounceMs > 0) {
+    const fieldDebounceMs = this.options.listeners?.onChangeDebounceMs
+    if (fieldDebounceMs && fieldDebounceMs > 0) {
       if (this.timeoutIds.listeners.change) {
         clearTimeout(this.timeoutIds.listeners.change)
       }
@@ -1746,7 +1775,7 @@ export class FieldApi<
           value: this.state.value,
           fieldApi: this,
         })
-      }, debounceMs)
+      }, fieldDebounceMs)
     } else {
       this.options.listeners?.onChange?.({
         value: this.state.value,

packages/form-core/src/FieldApi.ts

@@ -265,6 +265,7 @@ export interface FormListeners<
     >
     fieldApi: AnyFieldApi
   }) => void
+  onChangeDebounceMs?: number
 
   onBlur?: (props: {
     formApi: FormApi<
@@ -281,6 +282,7 @@ export interface FormListeners<
     >
     fieldApi: AnyFieldApi
   }) => void
+  onBlurDebounceMs?: number
 
   onMount?: (props: {
     formApi: FormApi<

packages/form-core/src/FormApi.d.ts

@@ -0,0 +1,2 @@
+import type { FormOptions } from './FormApi';
+export declare function formOptions<T extends Partial<FormOptions<any, any, any, any, any, any, any, any, any, any>>>(defaultOpts: T): T;

packages/form-core/src/FormApi.ts

@@ -0,0 +1,8 @@
+export * from './FormApi';
+export * from './FieldApi';
+export * from './utils';
+export * from './util-types';
+export * from './types';
+export * from './mergeForm';
+export * from './formOptions';
+export * from './standardSchemaValidator';

packages/form-core/src/formOptions.d.ts

@@ -0,0 +1,6 @@
+import type { FormApi } from './FormApi';
+/**
+ * @private
+ */
+export declare function mutateMergeDeep(target: object | null | undefined, source: object | null | undefined): object;
+export declare function mergeForm<TFormData>(baseForm: FormApi<NoInfer<TFormData>, any, any, any, any, any, any, any, any, any>, state: Partial<FormApi<TFormData, any, any, any, any, any, any, any, any, any>['state']>): FormApi<NoInfer<TFormData>, any, any, any, any, any, any, any, any, any>;

packages/form-core/src/index.d.ts

@@ -0,0 +1,9 @@
+import type { FormApi, FormAsyncValidateOrFn, FormValidateOrFn } from './FormApi';
+import type { AnyFieldMeta } from './FieldApi';
+import type { DeepKeys } from './util-types';
+type ArrayFieldMode = 'insert' | 'remove' | 'swap' | 'move';
+export declare const defaultFieldMeta: AnyFieldMeta;
+export declare function metaHelper<TFormData, TOnMount extends undefined | FormValidateOrFn<TFormData>, TOnChange extends undefined | FormValidateOrFn<TFormData>, TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnBlur extends undefined | FormValidateOrFn<TFormData>, TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnSubmit extends undefined | FormValidateOrFn<TFormData>, TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>, TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>, TSubmitMeta>(formApi: FormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnServer, TSubmitMeta>): {
+    handleArrayFieldMetaShift: (field: DeepKeys<TFormData>, index: number, mode: ArrayFieldMode, secondIndex?: number) => void;
+};
+export {};

packages/form-core/src/mergeForm.d.ts

@@ -0,0 +1,106 @@
+import type { ValidationSource } from './types';
+export type TStandardSchemaValidatorValue<TData, TSource extends ValidationSource = ValidationSource> = {
+    value: TData;
+    validationSource: TSource;
+};
+export type TStandardSchemaValidatorIssue<TSource extends ValidationSource = ValidationSource> = TSource extends 'form' ? {
+    form: Record<string, StandardSchemaV1Issue[]>;
+    fields: Record<string, StandardSchemaV1Issue[]>;
+} : TSource extends 'field' ? StandardSchemaV1Issue[] : never;
+export declare const standardSchemaValidators: {
+    validate<TSource extends ValidationSource = ValidationSource>({ value, validationSource, }: TStandardSchemaValidatorValue<unknown, TSource>, schema: StandardSchemaV1): TStandardSchemaValidatorIssue<TSource> | undefined;
+    validateAsync<TSource extends ValidationSource>({ value, validationSource, }: TStandardSchemaValidatorValue<unknown, TSource>, schema: StandardSchemaV1): Promise<TStandardSchemaValidatorIssue<TSource> | undefined>;
+};
+export declare const isStandardSchemaValidator: (validator: unknown) => validator is StandardSchemaV1;
+/**
+ * The Standard Schema interface.
+ */
+export type StandardSchemaV1<Input = unknown, Output = Input> = {
+    /**
+     * The Standard Schema properties.
+     */
+    readonly '~standard': StandardSchemaV1Props<Input, Output>;
+};
+/**
+ * The Standard Schema properties interface.
+ */
+interface StandardSchemaV1Props<Input = unknown, Output = Input> {
+    /**
+     * The version number of the standard.
+     */
+    readonly version: 1;
+    /**
+     * The vendor name of the schema library.
+     */
+    readonly vendor: string;
+    /**
+     * Validates unknown input values.
+     */
+    readonly validate: (value: unknown) => StandardSchemaV1Result<Output> | Promise<StandardSchemaV1Result<Output>>;
+    /**
+     * Inferred types associated with the schema.
+     */
+    readonly types?: StandardSchemaV1Types<Input, Output> | undefined;
+}
+/**
+ * The result interface of the validate function.
+ */
+type StandardSchemaV1Result<Output> = StandardSchemaV1SuccessResult<Output> | StandardSchemaV1FailureResult;
+/**
+ * The result interface if validation succeeds.
+ */
+interface StandardSchemaV1SuccessResult<Output> {
+    /**
+     * The typed output value.
+     */
+    readonly value: Output;
+    /**
+     * The non-existent issues.
+     */
+    readonly issues?: undefined;
+}
+/**
+ * The result interface if validation fails.
+ */
+interface StandardSchemaV1FailureResult {
+    /**
+     * The issues of failed validation.
+     */
+    readonly issues: ReadonlyArray<StandardSchemaV1Issue>;
+}
+/**
+ * The issue interface of the failure output.
+ */
+export interface StandardSchemaV1Issue {
+    /**
+     * The error message of the issue.
+     */
+    readonly message: string;
+    /**
+     * The path of the issue, if any.
+     */
+    readonly path?: ReadonlyArray<PropertyKey | StandardSchemaV1PathSegment> | undefined;
+}
+/**
+ * The path segment interface of the issue.
+ */
+interface StandardSchemaV1PathSegment {
+    /**
+     * The key representing a path segment.
+     */
+    readonly key: PropertyKey;
+}
+/**
+ * The Standard Schema types interface.
+ */
+interface StandardSchemaV1Types<Input = unknown, Output = Input> {
+    /**
+     * The input type of the schema.
+     */
+    readonly input: Input;
+    /**
+     * The output type of the schema.
+     */
+    readonly output: Output;
+}
+export {};

packages/form-core/src/metaHelper.d.ts

@@ -0,0 +1,73 @@
+import type { DeepKeys } from './util-types';
+export type ValidationError = unknown;
+export type ValidationSource = 'form' | 'field';
+/**
+ * "server" is only intended for SSR/SSG validation and should not execute anything
+ * @private
+ */
+export type ValidationCause = 'change' | 'blur' | 'submit' | 'mount' | 'server';
+/**
+ * @private
+ */
+export type ListenerCause = 'change' | 'blur' | 'submit' | 'mount';
+/**
+ * @private
+ */
+export type ValidationErrorMapKeys = `on${Capitalize<ValidationCause>}`;
+/**
+ * @private
+ */
+export type ValidationErrorMap<TOnMountReturn = unknown, TOnChangeReturn = unknown, TOnChangeAsyncReturn = unknown, TOnBlurReturn = unknown, TOnBlurAsyncReturn = unknown, TOnSubmitReturn = unknown, TOnSubmitAsyncReturn = unknown, TOnServerReturn = unknown> = {
+    onMount?: TOnMountReturn;
+    onChange?: TOnChangeReturn | TOnChangeAsyncReturn;
+    onBlur?: TOnBlurReturn | TOnBlurAsyncReturn;
+    onSubmit?: TOnSubmitReturn | TOnSubmitAsyncReturn;
+    onServer?: TOnServerReturn;
+};
+/**
+ * @private allows tracking the source of the errors in the error map
+ */
+export type ValidationErrorMapSource = {
+    onMount?: ValidationSource;
+    onChange?: ValidationSource;
+    onBlur?: ValidationSource;
+    onSubmit?: ValidationSource;
+    onServer?: ValidationSource;
+};
+/**
+ * @private
+ */
+export type FormValidationErrorMap<TOnMountReturn = unknown, TOnChangeReturn = unknown, TOnChangeAsyncReturn = unknown, TOnBlurReturn = unknown, TOnBlurAsyncReturn = unknown, TOnSubmitReturn = unknown, TOnSubmitAsyncReturn = unknown, TOnServerReturn = unknown> = {
+    onMount?: TOnMountReturn;
+    onChange?: TOnChangeReturn | TOnChangeAsyncReturn;
+    onBlur?: TOnBlurReturn | TOnBlurAsyncReturn;
+    onSubmit?: TOnSubmitReturn | TOnSubmitAsyncReturn;
+    onServer?: TOnServerReturn;
+};
+export type FormValidationError<TFormData> = ValidationError | GlobalFormValidationError<TFormData>;
+/**
+ * @private
+ *
+ * @example
+ * ```tsx
+ * {
+ *   form: 'This form contains an error',
+ *   fields: {
+ *     age: "Must be 13 or older to register"
+ *   }
+ * }
+ * ````
+ */
+export type GlobalFormValidationError<TFormData> = {
+    form?: ValidationError;
+    fields: Partial<Record<DeepKeys<TFormData>, ValidationError>>;
+};
+/**
+ * @private
+ */
+export interface UpdateMetaOptions {
+    /**
+     * @default false
+     */
+    dontUpdateMeta?: boolean;
+}

packages/form-core/src/standardSchemaValidator.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @private
+ */
+export type UnwrapOneLevelOfArray<T> = T extends (infer U)[] ? U : T;
+type Narrowable = string | number | bigint | boolean;
+type NarrowRaw<A> = (A extends [] ? [] : never) | (A extends Narrowable ? A : never) | {
+    [K in keyof A]: A[K] extends Function ? A[K] : NarrowRaw<A[K]>;
+};
+type Try<A1, A2, Catch = never> = A1 extends A2 ? A1 : Catch;
+/**
+ * @private
+ */
+export type Narrow<A> = Try<A, [], NarrowRaw<A>>;
+export interface AnyDeepKeyAndValue {
+    key: string;
+    value: any;
+}
+export type ArrayAccessor<TParent extends AnyDeepKeyAndValue> = `${TParent['key'] extends never ? '' : TParent['key']}[${number}]`;
+export interface ArrayDeepKeyAndValue<in out TParent extends AnyDeepKeyAndValue, in out T extends ReadonlyArray<any>> extends AnyDeepKeyAndValue {
+    key: ArrayAccessor<TParent>;
+    value: T[number] | Nullable<TParent['value']>;
+}
+export type DeepKeyAndValueArray<TParent extends AnyDeepKeyAndValue, T extends ReadonlyArray<any>, TAcc> = DeepKeysAndValuesImpl<NonNullable<T[number]>, ArrayDeepKeyAndValue<TParent, T>, TAcc | ArrayDeepKeyAndValue<TParent, T>>;
+export type TupleAccessor<TParent extends AnyDeepKeyAndValue, TKey extends string> = `${TParent['key'] extends never ? '' : TParent['key']}[${TKey}]`;
+export interface TupleDeepKeyAndValue<in out TParent extends AnyDeepKeyAndValue, in out T, in out TKey extends AllTupleKeys<T>> extends AnyDeepKeyAndValue {
+    key: TupleAccessor<TParent, TKey>;
+    value: T[TKey] | Nullable<TParent['value']>;
+}
+export type AllTupleKeys<T> = T extends any ? keyof T & `${number}` : never;
+export type DeepKeyAndValueTuple<TParent extends AnyDeepKeyAndValue, T extends ReadonlyArray<any>, TAcc, TAllKeys extends AllTupleKeys<T> = AllTupleKeys<T>> = TAllKeys extends any ? DeepKeysAndValuesImpl<NonNullable<T[TAllKeys]>, TupleDeepKeyAndValue<TParent, T, TAllKeys>, TAcc | TupleDeepKeyAndValue<TParent, T, TAllKeys>> : never;
+export type AllObjectKeys<T> = T extends any ? keyof T & (string | number) : never;
+export type ObjectAccessor<TParent extends AnyDeepKeyAndValue, TKey extends string | number> = TParent['key'] extends never ? `${TKey}` : `${TParent['key']}.${TKey}`;
+export type Nullable<T> = T & (undefined | null);
+export type ObjectValue<TParent extends AnyDeepKeyAndValue, T, TKey extends AllObjectKeys<T>> = T[TKey] | Nullable<TParent['value']>;
+export interface ObjectDeepKeyAndValue<in out TParent extends AnyDeepKeyAndValue, in out T, in out TKey extends AllObjectKeys<T>> extends AnyDeepKeyAndValue {
+    key: ObjectAccessor<TParent, TKey>;
+    value: ObjectValue<TParent, T, TKey>;
+}
+export type DeepKeyAndValueObject<TParent extends AnyDeepKeyAndValue, T, TAcc, TAllKeys extends AllObjectKeys<T> = AllObjectKeys<T>> = TAllKeys extends any ? DeepKeysAndValuesImpl<NonNullable<T[TAllKeys]>, ObjectDeepKeyAndValue<TParent, T, TAllKeys>, TAcc | ObjectDeepKeyAndValue<TParent, T, TAllKeys>> : never;
+export type UnknownAccessor<TParent extends AnyDeepKeyAndValue> = TParent['key'] extends never ? string : `${TParent['key']}.${string}`;
+export interface UnknownDeepKeyAndValue<TParent extends AnyDeepKeyAndValue> extends AnyDeepKeyAndValue {
+    key: UnknownAccessor<TParent>;
+    value: unknown;
+}
+export type DeepKeysAndValues<T> = DeepKeysAndValuesImpl<T> extends AnyDeepKeyAndValue ? DeepKeysAndValuesImpl<T> : never;
+export type DeepKeysAndValuesImpl<T, TParent extends AnyDeepKeyAndValue = never, TAcc = never> = unknown extends T ? TAcc | UnknownDeepKeyAndValue<TParent> : unknown extends T ? T : T extends string | number | boolean | bigint | Date ? TAcc : T extends ReadonlyArray<any> ? number extends T['length'] ? DeepKeyAndValueArray<TParent, T, TAcc> : DeepKeyAndValueTuple<TParent, T, TAcc> : keyof T extends never ? TAcc | UnknownDeepKeyAndValue<TParent> : T extends object ? DeepKeyAndValueObject<TParent, T, TAcc> : TAcc;
+export type DeepRecord<T> = {
+    [TRecord in DeepKeysAndValues<T> as TRecord['key']]: TRecord['value'];
+};
+/**
+ * The keys of an object or array, deeply nested.
+ */
+export type DeepKeys<T> = unknown extends T ? string : DeepKeysAndValues<T>['key'];
+/**
+ * Infer the type of a deeply nested property within an object or an array.
+ */
+export type DeepValue<TValue, TAccessor> = unknown extends TValue ? TValue : TAccessor extends DeepKeys<TValue> ? DeepRecord<TValue>[TAccessor] : never;
+export {};