@matthew.ngo/reform/dist/features/persistence/types.d.ts

A flexible and powerful React form management library with advanced validation, state observation, and multi-group support

/**
 * Defines types and interfaces for form persistence functionality.
 * This module provides the type definitions for saving, restoring, and
 * auto-saving form state across sessions.
 */
import { FormGroup } from '../../core/form/form-groups';
/**
 * Storage provider interface for form persistence
 *
 * @template T - The type of form data
 */
export interface StorageProvider<T> {
    /**
     * Save form data to storage
     *
     * @param key - Storage key
     * @param data - Form data to save
     * @returns Promise that resolves when data is saved
     */
    save: (key: string, data: FormPersistenceData<T>) => Promise<void>;
    /**
     * Load form data from storage
     *
     * @param key - Storage key
     * @returns Promise that resolves with the loaded data, or null if not found
     */
    load: (key: string) => Promise<FormPersistenceData<T> | null>;
    /**
     * Remove form data from storage
     *
     * @param key - Storage key
     * @returns Promise that resolves when data is removed
     */
    remove: (key: string) => Promise<void>;
}
/**
 * Data structure for persisted form state
 *
 * @template T - The type of form data
 */
export interface FormPersistenceData<T> {
    /** Form groups data */
    groups: FormGroup<T>[];
    /** Timestamp when the data was saved */
    timestamp: number;
    /** Version of the data format (for future migrations) */
    version: string;
    /** Additional metadata about the saved state */
    metadata?: Record<string, any>;
}
/**
 * Configuration options for form persistence
 *
 * @template T - The type of form data
 */
export interface FormPersistenceConfig<T> {
    /**
     * Whether form persistence is enabled
     * Default: false
     */
    enabled?: boolean;
    /**
     * Storage key to use when persisting form state
     * Default: 'reform-form-state'
     */
    storageKey?: string;
    /**
     * Custom storage provider
     * If not provided, localStorage will be used
     */
    storageProvider?: StorageProvider<T>;
    /**
     * Whether to enable auto-save functionality
     * Default: false
     */
    autoSave?: boolean;
    /**
     * Auto-save interval in milliseconds
     * Default: 5000 (5 seconds)
     */
    autoSaveInterval?: number;
    /**
     * Whether to debounce auto-save on form changes
     * Default: true
     */
    debounceAutoSave?: boolean;
    /**
     * Debounce delay in milliseconds
     * Default: 500 (0.5 seconds)
     */
    debounceDelay?: number;
    /**
     * Callback fired before saving form state
     * Return false to prevent saving
     *
     * @param groups - Form groups to be saved
     * @returns Whether to proceed with saving
     */
    onBeforeSave?: (groups: FormGroup<T>[]) => boolean | Promise<boolean>;
    /**
     * Callback fired after form state is saved
     *
     * @param groups - Form groups that were saved
     */
    onAfterSave?: (groups: FormGroup<T>[]) => void;
    /**
     * Callback fired after form state is restored
     *
     * @param groups - Form groups that were restored
     */
    onAfterRestore?: (groups: FormGroup<T>[]) => void;
    /**
     * Additional metadata to save with the form state
     */
    metadata?: Record<string, any> | (() => Record<string, any>);
}
/**
 * Return type of the useFormPersistence hook
 *
 * @template T - The type of form data
 */
export interface FormPersistenceReturn<T> {
    /**
     * Whether form state is currently being saved
     */
    isSaving: boolean;
    /**
     * Whether form state is currently being loaded
     */
    isLoading: boolean;
    /**
     * Last time the form state was saved (timestamp)
     */
    lastSaved: number | null;
    /**
     * Manually save the current form state
     *
     * @returns Promise that resolves when save is complete
     */
    saveState: () => Promise<void>;
    /**
     * Manually load form state from storage
     *
     * @returns Promise that resolves when load is complete
     */
    loadState: () => Promise<void>;
    /**
     * Clear saved form state from storage
     *
     * @returns Promise that resolves when clear is complete
     */
    clearState: () => Promise<void>;
    /**
     * Reset auto-save timer (if auto-save is enabled)
     */
    resetAutoSaveTimer: () => void;
    /**
     * Enable or disable auto-save functionality
     *
     * @param enabled - Whether auto-save should be enabled
     */
    setAutoSave: (enabled: boolean) => void;
    /**
     * Whether auto-save is currently enabled
     */
    isAutoSaveEnabled: boolean;
}