@valfuse-node/form 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,554 @@
+type ValfuseRuleError = {
+    message: string;
+    code?: string;
+    type?: string;
+    metadata?: Record<string, unknown>;
+};
+type ValfuseErrorType = "validation" | "server" | "manual" | "custom";
+type ValfuseError = {
+    message: string;
+    type?: ValfuseErrorType | string;
+    code?: string;
+    metadata?: Record<string, unknown>;
+};
+type ValfuseFieldErrors<TFieldName extends string = string> = Partial<Record<TFieldName, string | ValfuseError>>;
+
+type ValfuseRegexValue = RegExp | {
+    pattern: string;
+    flags?: string;
+};
+type ValfuseStringRequiredRule = {
+    name: "required";
+    error: ValfuseRuleError;
+};
+type ValfuseStringMinRule = {
+    name: "min";
+    value: number;
+    error: ValfuseRuleError;
+};
+type ValfuseStringMaxRule = {
+    name: "max";
+    value: number;
+    error: ValfuseRuleError;
+};
+type ValfuseStringLengthRule = {
+    name: "length";
+    value: number;
+    error: ValfuseRuleError;
+};
+type ValfuseStringEmailRule = {
+    name: "email";
+    error: ValfuseRuleError;
+};
+type ValfuseStringUrlRule = {
+    name: "url";
+    error: ValfuseRuleError;
+};
+type ValfuseStringUuidRule = {
+    name: "uuid";
+    error: ValfuseRuleError;
+};
+type ValfuseStringRegexRule = {
+    name: "regex";
+    value: ValfuseRegexValue;
+    error: ValfuseRuleError;
+};
+type ValfuseStringIncludesRule = {
+    name: "includes";
+    value: string;
+    error: ValfuseRuleError;
+};
+type ValfuseStringStartsWithRule = {
+    name: "startsWith";
+    value: string;
+    error: ValfuseRuleError;
+};
+type ValfuseStringEndsWithRule = {
+    name: "endsWith";
+    value: string;
+    error: ValfuseRuleError;
+};
+type ValfuseStringRule = ValfuseStringRequiredRule | ValfuseStringMinRule | ValfuseStringMaxRule | ValfuseStringLengthRule | ValfuseStringEmailRule | ValfuseStringUrlRule | ValfuseStringUuidRule | ValfuseStringRegexRule | ValfuseStringIncludesRule | ValfuseStringStartsWithRule | ValfuseStringEndsWithRule;
+type ValfuseNumberRequiredRule = {
+    name: "required";
+    error: ValfuseRuleError;
+};
+type ValfuseNumberMinRule = {
+    name: "min";
+    value: number;
+    error: ValfuseRuleError;
+};
+type ValfuseNumberMaxRule = {
+    name: "max";
+    value: number;
+    error: ValfuseRuleError;
+};
+type ValfuseNumberGtRule = {
+    name: "gt";
+    value: number;
+    error: ValfuseRuleError;
+};
+type ValfuseNumberGteRule = {
+    name: "gte";
+    value: number;
+    error: ValfuseRuleError;
+};
+type ValfuseNumberLtRule = {
+    name: "lt";
+    value: number;
+    error: ValfuseRuleError;
+};
+type ValfuseNumberLteRule = {
+    name: "lte";
+    value: number;
+    error: ValfuseRuleError;
+};
+type ValfuseNumberIntRule = {
+    name: "int";
+    error: ValfuseRuleError;
+};
+type ValfuseNumberPositiveRule = {
+    name: "positive";
+    error: ValfuseRuleError;
+};
+type ValfuseNumberNonnegativeRule = {
+    name: "nonnegative";
+    error: ValfuseRuleError;
+};
+type ValfuseNumberNegativeRule = {
+    name: "negative";
+    error: ValfuseRuleError;
+};
+type ValfuseNumberNonpositiveRule = {
+    name: "nonpositive";
+    error: ValfuseRuleError;
+};
+type ValfuseNumberMultipleOfRule = {
+    name: "multipleOf";
+    value: number;
+    error: ValfuseRuleError;
+};
+type ValfuseNumberRule = ValfuseNumberRequiredRule | ValfuseNumberMinRule | ValfuseNumberMaxRule | ValfuseNumberGtRule | ValfuseNumberGteRule | ValfuseNumberLtRule | ValfuseNumberLteRule | ValfuseNumberIntRule | ValfuseNumberPositiveRule | ValfuseNumberNonnegativeRule | ValfuseNumberNegativeRule | ValfuseNumberNonpositiveRule | ValfuseNumberMultipleOfRule;
+type ValfuseBooleanRequiredRule = {
+    name: "required";
+    error: ValfuseRuleError;
+};
+type ValfuseBooleanLiteralRule = {
+    name: "literal";
+    value: boolean;
+    error: ValfuseRuleError;
+};
+type ValfuseBooleanAcceptedRule = {
+    name: "accepted";
+    error: ValfuseRuleError;
+};
+type ValfuseBooleanRule = ValfuseBooleanRequiredRule | ValfuseBooleanLiteralRule | ValfuseBooleanAcceptedRule;
+type ValfuseArrayRequiredRule = {
+    name: "required";
+    error: ValfuseRuleError;
+};
+type ValfuseArrayMinRule = {
+    name: "min";
+    value: number;
+    error: ValfuseRuleError;
+};
+type ValfuseArrayMaxRule = {
+    name: "max";
+    value: number;
+    error: ValfuseRuleError;
+};
+type ValfuseArrayLengthRule = {
+    name: "length";
+    value: number;
+    error: ValfuseRuleError;
+};
+type ValfuseArrayNonemptyRule = {
+    name: "nonempty";
+    error: ValfuseRuleError;
+};
+type ValfuseArrayRule = ValfuseArrayRequiredRule | ValfuseArrayMinRule | ValfuseArrayMaxRule | ValfuseArrayLengthRule | ValfuseArrayNonemptyRule;
+type ValfuseObjectRequiredRule = {
+    name: "required";
+    error: ValfuseRuleError;
+};
+type ValfuseObjectShapeRule = {
+    name: "shape";
+    value: Record<string, unknown>;
+    error: ValfuseRuleError;
+};
+type ValfuseObjectRule = ValfuseObjectRequiredRule | ValfuseObjectShapeRule;
+type ValfuseCustomRule = {
+    name: "custom";
+    validate: (value: unknown, allValues: Record<string, unknown>) => boolean;
+    error: ValfuseRuleError;
+};
+type ValfuseRefineRule = {
+    name: "refine";
+    validate: (value: unknown, allValues: Record<string, unknown>) => boolean;
+    error: ValfuseRuleError;
+};
+type ValfuseMatchFieldRule = {
+    name: "matchField";
+    value: string;
+    error: ValfuseRuleError;
+};
+type ValfuseOneOfRule = {
+    name: "oneOf";
+    value: unknown[];
+    error: ValfuseRuleError;
+};
+type ValfuseNotOneOfRule = {
+    name: "notOneOf";
+    value: unknown[];
+    error: ValfuseRuleError;
+};
+type ValfuseGenericRule = ValfuseCustomRule | ValfuseRefineRule | ValfuseMatchFieldRule | ValfuseOneOfRule | ValfuseNotOneOfRule;
+
+/**
+ * A function that transforms a raw field value before validation runs.
+ * Applied on every change, on `setValue`, and before `handleSubmit`.
+ *
+ * @example
+ * transform: t.pipe(t.trim, t.toLowerCase)
+ * transform: t.toNumber
+ * transform: (v) => String(v).replace(/\s+/g, "-")
+ */
+type ValfuseTransformer = (value: unknown) => unknown;
+type ValfuseStringFieldSchema = {
+    type: "string";
+    rules: (ValfuseStringRule | ValfuseGenericRule)[];
+    /** Optional transform applied to the value before validation and before submit. */
+    transform?: ValfuseTransformer;
+};
+type ValfuseNumberFieldSchema = {
+    type: "number";
+    rules: (ValfuseNumberRule | ValfuseGenericRule)[];
+    /** Optional transform applied to the value before validation and before submit. */
+    transform?: ValfuseTransformer;
+};
+type ValfuseBooleanFieldSchema = {
+    type: "boolean";
+    rules: (ValfuseBooleanRule | ValfuseGenericRule)[];
+    /** Optional transform applied to the value before validation and before submit. */
+    transform?: ValfuseTransformer;
+};
+type ValfuseArrayFieldSchema = {
+    type: "array";
+    rules: (ValfuseArrayRule | ValfuseGenericRule)[];
+    /** Optional transform applied to the value before validation and before submit. */
+    transform?: ValfuseTransformer;
+};
+type ValfuseObjectFieldSchema = {
+    type: "object";
+    rules: (ValfuseObjectRule | ValfuseGenericRule)[];
+    /** Optional transform applied to the value before validation and before submit. */
+    transform?: ValfuseTransformer;
+};
+type ValfuseFieldSchema = ValfuseStringFieldSchema | ValfuseNumberFieldSchema | ValfuseBooleanFieldSchema | ValfuseArrayFieldSchema | ValfuseObjectFieldSchema;
+type ValfuseSchema = Record<string, ValfuseFieldSchema>;
+/** Alias for {@link ValfuseFieldErrors} — preferred for setErrors input typing */
+type SetErrorsInput<TFieldName extends string = string> = ValfuseFieldErrors<TFieldName>;
+
+/**
+ * Controls when validation is triggered:
+ *
+ * | Mode         | Behaviour                                                               |
+ * |--------------|-------------------------------------------------------------------------|
+ * | `onSubmit`   | Validate only when the form is submitted (default)                      |
+ * | `onBlur`     | Validate when a field loses focus                                       |
+ * | `onChange`   | Validate on every keystroke / value change                              |
+ */
+type ValfuseFormMode = "onSubmit" | "onBlur" | "onChange";
+/** A single field error */
+interface ValfuseFieldError {
+    message: string;
+    /** Error originator: "validation" | "server" | "manual" | "custom" */
+    type?: string;
+    /** Optional semantic code (e.g. "email.required", "auth.not_found") */
+    code?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Map of field names to their error */
+type ValfuseFormErrors<TSchema extends Record<string, unknown>> = {
+    [K in keyof TSchema]?: ValfuseFieldError;
+};
+/** Map of dirty fields (value changed from default) */
+type ValfuseDirtyFields<TSchema extends Record<string, unknown>> = {
+    [K in keyof TSchema]?: true;
+};
+/** Map of touched fields (user interacted with) */
+type ValfuseTouchedFields<TSchema extends Record<string, unknown>> = {
+    [K in keyof TSchema]?: true;
+};
+/** Reactive form state exposed to consumers */
+interface ValfuseFormState<TSchema extends Record<string, unknown>> {
+    /** All current field validation errors */
+    readonly errors: ValfuseFormErrors<TSchema>;
+    /** `true` while an async submit handler is running */
+    readonly isSubmitting: boolean;
+    /** `true` after the form has been submitted at least once */
+    readonly isSubmitted: boolean;
+    /** `true` if the most recent submission completed successfully */
+    readonly isSubmitSuccessful: boolean;
+    /** Total number of submit attempts */
+    readonly submitCount: number;
+    /** `true` if any field value differs from its default value */
+    readonly isDirty: boolean;
+    /** `true` if current values pass schema validation and there are no active errors */
+    readonly isValid: boolean;
+    /** Map of fields whose current value differs from the default */
+    readonly dirtyFields: ValfuseDirtyFields<TSchema>;
+    /** Map of fields the user has interacted with */
+    readonly touchedFields: ValfuseTouchedFields<TSchema>;
+    /** The defaultValues that were passed to useValfuseForm */
+    readonly defaultValues: Readonly<TSchema>;
+}
+/**
+ * Callback passed to `form.watch(callback)`.
+ * Called every time any field value changes.
+ */
+type ValfuseWatchCallback<TSchema extends Record<string, unknown>> = (values: TSchema, info?: {
+    name?: string;
+    type?: string;
+}) => void;
+/**
+ * Callable type for `form.watch`:
+ *
+ * ```ts
+ * form.watch()                          // → TSchema (all values)
+ * form.watch("email")                   // → TSchema["email"]
+ * form.watch(["email", "name"])         // → Array of values
+ * form.watch((values, info) => void)    // → () => void  (unsubscribe)
+ * ```
+ */
+interface ValfuseWatchFunction<TSchema extends Record<string, unknown>> {
+    (): TSchema;
+    <TName extends keyof TSchema & string>(name: TName): TSchema[TName];
+    (names: Array<keyof TSchema & string>): Array<TSchema[keyof TSchema]>;
+    (callback: ValfuseWatchCallback<TSchema>): () => void;
+}
+/** Props returned by `form.register(name)` — spread onto input element (React) */
+interface ValfuseRegisterReturn {
+    name: string;
+    value?: string | number | readonly string[] | undefined;
+    onChange: (e: unknown) => void;
+    onBlur: () => void;
+}
+/** Props returned by `form.register(name)` — for Vue v-model compatibility */
+interface ValfuseVueRegisterReturn {
+    name: string;
+    modelValue: unknown;
+    "onUpdate:modelValue": (value: unknown) => void;
+    onBlur: () => void;
+}
+/**
+ * Opaque control object — passed to ValfuseController.
+ * Internal fields are prefixed with `_` and not part of the public API.
+ */
+interface ValfuseFormControl<TSchema extends Record<string, unknown>> {
+    /** @internal Current field values */
+    _values: TSchema;
+    /** @internal Current validation errors */
+    _errors: ValfuseFormErrors<TSchema>;
+    /** @internal Update a single field value */
+    _updateField: <TName extends keyof TSchema & string>(name: TName, value: TSchema[TName]) => void;
+    /** @internal Mark a field as touched */
+    _touchField: (name: string) => void;
+    /** @internal Set of names of fields the user has interacted with */
+    _touchedFields: ReadonlySet<keyof TSchema>;
+}
+/** Props passed to useValfuseForm */
+interface UseValfuseFormProps<TSchema extends Record<string, unknown>> {
+    schema: ValfuseSchema;
+    defaultValues: TSchema;
+    mode?: ValfuseFormMode;
+    reValidateMode?: "onChange" | "onBlur" | "onSubmit";
+}
+/**
+ * Return type of useValfuseForm — defined as interface so adapters can implement it.
+ * This is the core form contract that React, Vue, and other adapters must fulfill.
+ */
+interface UseValfuseFormReturn<TSchema extends Record<string, unknown>> {
+    /**
+     * Registers an input field.
+     * Returns props to spread onto the input element.
+     */
+    register: <TName extends keyof TSchema & string>(name: TName) => ValfuseRegisterReturn;
+    /** Passed to ValfuseController for controlled inputs */
+    control: ValfuseFormControl<TSchema>;
+    /**
+     * Wraps form submission: validates first, then calls onValid.
+     * Returns an event handler to pass to form onSubmit.
+     */
+    handleSubmit: (onValid: (values: TSchema) => void | Promise<void>) => (e?: unknown) => Promise<void>;
+    /** Reactive form state */
+    formState: ValfuseFormState<TSchema>;
+    /** Inject external errors (e.g. from API responses) */
+    setErrors: (errors: Partial<Record<string, ValfuseFieldError>>) => void;
+    /** Clear one, many, or all field errors */
+    clearErrors: (name?: keyof TSchema | Array<keyof TSchema>) => void;
+    /**
+     * Programmatically set a field value.
+     * Pass { shouldValidate: true } to run validation immediately.
+     */
+    setValue: <TName extends keyof TSchema>(name: TName, value: TSchema[TName], options?: {
+        shouldValidate?: boolean;
+    }) => void;
+    /**
+     * Manually trigger validation.
+     * - No argument → validate all fields
+     * - Single name → validate one field
+     * - Array of names → validate those fields
+     *
+     * Returns true if all triggered fields are valid, false otherwise.
+     */
+    trigger: (name?: keyof TSchema & string | Array<keyof TSchema & string>) => boolean;
+    /**
+     * Watch field values:
+     *
+     * ```ts
+     * form.watch()                           // all current values
+     * form.watch("email")                    // single field value
+     * form.watch(["email", "name"])          // array of values
+     * const unsub = form.watch((values, info) => { ... }); // subscribe
+     * unsub();                               // unsubscribe
+     * ```
+     */
+    watch: ValfuseWatchFunction<TSchema>;
+    /** Reset the form to default values (or provided partial values) */
+    reset: (values?: Partial<TSchema>) => void;
+    /** Get a single field value (Vue only) */
+    getValue?: <TName extends keyof TSchema>(name: TName) => TSchema[TName];
+    /** Get all field values (Vue only) */
+    getValues?: () => TSchema;
+}
+
+declare function createSchema<T extends ValfuseSchema>(definition: T): T;
+
+declare function validateSchema(schema: ValfuseSchema, values: Record<string, unknown>): Record<string, ValfuseError>;
+
+/**
+ * Applies each field's `transform` function to the corresponding value,
+ * returning a new object with the transformed values.
+ *
+ * Fields without a `transform` definition are passed through unchanged.
+ * The original `values` object is never mutated.
+ *
+ * @example
+ * transformValues(schema, { email: "  HELLO@EMAIL.COM  ", age: "25" })
+ * // → { email: "hello@email.com", age: 25 }
+ */
+declare function transformValues(schema: ValfuseSchema, values: Record<string, unknown>): Record<string, unknown>;
+
+declare function normalizeError(error: string | ValfuseError): ValfuseError;
+
+/**
+ * Compose multiple transformers left-to-right (output of each feeds into the next).
+ *
+ * @example
+ * t.pipe(t.trim, t.toLowerCase)("  HELLO@EMAIL.COM  ") → "hello@email.com"
+ */
+declare function pipe(...fns: ValfuseTransformer[]): ValfuseTransformer;
+/**
+ * Built-in transformers — import as `import { t } from "@valfuse-node/form"`.
+ *
+ * @example
+ * transform: t.trim
+ * transform: t.toNumber
+ * transform: t.pipe(t.trim, t.toLowerCase)
+ */
+declare const t: {
+    readonly trim: ValfuseTransformer;
+    readonly trimStart: ValfuseTransformer;
+    readonly trimEnd: ValfuseTransformer;
+    readonly toLowerCase: ValfuseTransformer;
+    readonly toUpperCase: ValfuseTransformer;
+    readonly toTitleCase: ValfuseTransformer;
+    readonly toSentenceCase: ValfuseTransformer;
+    readonly collapseSpaces: ValfuseTransformer;
+    readonly toNumber: ValfuseTransformer;
+    readonly toInteger: ValfuseTransformer;
+    readonly toFloat: ValfuseTransformer;
+    readonly toBoolean: ValfuseTransformer;
+    readonly pipe: typeof pipe;
+};
+
+/** Form values state */
+interface FormValuesState<TSchema extends Record<string, unknown>> {
+    values: TSchema;
+    defaultValues: TSchema;
+}
+/** Create initial values state from default values */
+declare function createValuesState<TSchema extends Record<string, unknown>>(defaultValues: TSchema): FormValuesState<TSchema>;
+/** Update a single field value */
+declare function updateValue<TSchema extends Record<string, unknown>>(state: FormValuesState<TSchema>, key: keyof TSchema & string, value: unknown): FormValuesState<TSchema>;
+/** Reset values to default (or provided partial overrides) */
+declare function resetValues<TSchema extends Record<string, unknown>>(state: FormValuesState<TSchema>, newValues?: Partial<TSchema>): FormValuesState<TSchema>;
+/** Check if form is dirty (any field differs from default) */
+declare function computeIsDirty<TSchema extends Record<string, unknown>>(state: FormValuesState<TSchema>): boolean;
+/** Get all dirty fields */
+declare function computeDirtyFields<TSchema extends Record<string, unknown>>(state: FormValuesState<TSchema>): ValfuseDirtyFields<TSchema>;
+/** Check if a specific field is dirty */
+declare function isFieldDirty<TSchema extends Record<string, unknown>>(state: FormValuesState<TSchema>, key: keyof TSchema & string): boolean;
+/** Get a single field value */
+declare function getValue<TSchema extends Record<string, unknown>, TName extends keyof TSchema>(state: FormValuesState<TSchema>, name: TName): TSchema[TName];
+/** Get all values as plain object */
+declare function getValues<TSchema extends Record<string, unknown>>(state: FormValuesState<TSchema>): TSchema;
+
+/** Form touched state */
+interface FormTouchedState {
+    touchedFields: Set<string>;
+}
+/** Create initial touched state (empty) */
+declare function createTouchedState(): FormTouchedState;
+/** Mark a field as touched */
+declare function markTouched(state: FormTouchedState, name: string): FormTouchedState;
+/** Mark a field as untouched */
+declare function markUntouched(state: FormTouchedState, name: string): FormTouchedState;
+/** Reset touched state (clear all) */
+declare function resetTouched(): FormTouchedState;
+/** Check if a field is touched */
+declare function isTouched(state: FormTouchedState, name: string): boolean;
+/** Convert touched Set to Record for public API */
+declare function toTouchedFieldsRecord(state: FormTouchedState): ValfuseTouchedFields<Record<string, unknown>>;
+
+/** Form errors state */
+interface FormErrorsState {
+    errors: Record<string, ValfuseFieldError>;
+}
+/** Create initial errors state (empty) */
+declare function createErrorsState(): FormErrorsState;
+/** Set errors for specific fields (e.g., from server or setErrors call) */
+declare function setErrors(state: FormErrorsState, fieldErrors: Partial<Record<string, ValfuseFieldError>>): FormErrorsState;
+/** Set a single field error */
+declare function setFieldError(state: FormErrorsState, name: string, error: ValfuseFieldError | null): FormErrorsState;
+/** Clear errors for specific fields */
+declare function clearFieldErrors(state: FormErrorsState, names?: string | string[]): FormErrorsState;
+/** Reset errors state (clear all) */
+declare function resetErrors(): FormErrorsState;
+/** Check if there are any errors */
+declare function hasErrors(state: FormErrorsState): boolean;
+/** Get error for a specific field */
+declare function getFieldError(state: FormErrorsState, name: string): ValfuseFieldError | undefined;
+/** Convert errors state to form errors type */
+declare function toFormErrors<TSchema extends Record<string, unknown>>(state: FormErrorsState): ValfuseFormErrors<TSchema>;
+
+/** Form submission state */
+interface FormSubmissionState {
+    isSubmitting: boolean;
+    isSubmitted: boolean;
+    isSubmitSuccessful: boolean;
+    submitCount: number;
+}
+/** Create initial submission state */
+declare function createSubmissionState(): FormSubmissionState;
+/** Start submission */
+declare function startSubmit(state: FormSubmissionState): FormSubmissionState;
+/** End submission successfully */
+declare function endSubmitSuccess(state: FormSubmissionState): FormSubmissionState;
+/** End submission with failure */
+declare function endSubmitFailure(state: FormSubmissionState): FormSubmissionState;
+/** Reset submission state */
+declare function resetSubmission(): FormSubmissionState;
+
+export { type FormErrorsState, type FormSubmissionState, type FormTouchedState, type FormValuesState, type SetErrorsInput, type UseValfuseFormProps, type UseValfuseFormReturn, type ValfuseArrayFieldSchema, type ValfuseArrayRule, type ValfuseBooleanFieldSchema, type ValfuseBooleanRule, type ValfuseCustomRule, type ValfuseDirtyFields, type ValfuseError, type ValfuseErrorType, type ValfuseFieldError, type ValfuseFieldErrors, type ValfuseFieldSchema, type ValfuseFormControl, type ValfuseFormErrors, type ValfuseFormMode, type ValfuseFormState, type ValfuseGenericRule, type ValfuseMatchFieldRule, type ValfuseNotOneOfRule, type ValfuseNumberFieldSchema, type ValfuseNumberRule, type ValfuseObjectFieldSchema, type ValfuseObjectRule, type ValfuseOneOfRule, type ValfuseRefineRule, type ValfuseRegexValue, type ValfuseRegisterReturn, type ValfuseRuleError, type ValfuseSchema, type ValfuseStringFieldSchema, type ValfuseStringRule, type ValfuseTouchedFields, type ValfuseTransformer, type ValfuseVueRegisterReturn, type ValfuseWatchCallback, type ValfuseWatchFunction, clearFieldErrors, computeDirtyFields, computeIsDirty, createErrorsState, createSchema, createSubmissionState, createTouchedState, createValuesState, endSubmitFailure, endSubmitSuccess, getFieldError, getValue, getValues, hasErrors, isFieldDirty, isTouched, markTouched, markUntouched, normalizeError, resetErrors, resetSubmission, resetTouched, resetValues, setErrors, setFieldError, startSubmit, t, toFormErrors, toTouchedFieldsRecord, transformValues, updateValue, validateSchema };