@tanstack/db/dist/esm/local-storage.d.ts

A reactive client store for building super fast apps on sync

import { CollectionConfig, DeleteMutationFnParams, InsertMutationFnParams, ResolveType, UpdateMutationFnParams, UtilsRecord } from './types.js';
import { StandardSchemaV1 } from '@standard-schema/spec';
/**
 * Storage API interface - subset of DOM Storage that we need
 */
export type StorageApi = Pick<Storage, `getItem` | `setItem` | `removeItem`>;
/**
 * Storage event API - subset of Window for 'storage' events only
 */
export type StorageEventApi = {
    addEventListener: (type: `storage`, listener: (event: StorageEvent) => void) => void;
    removeEventListener: (type: `storage`, listener: (event: StorageEvent) => void) => void;
};
/**
 * Configuration interface for localStorage collection options
 * @template TExplicit - The explicit type of items in the collection (highest priority)
 * @template TSchema - The schema type for validation and type inference (second priority)
 * @template TFallback - The fallback type if no explicit or schema type is provided
 *
 * @remarks
 * Type resolution follows a priority order:
 * 1. If you provide an explicit type via generic parameter, it will be used
 * 2. If no explicit type is provided but a schema is, the schema's output type will be inferred
 * 3. If neither explicit type nor schema is provided, the fallback type will be used
 *
 * You should provide EITHER an explicit type OR a schema, but not both, as they would conflict.
 */
export interface LocalStorageCollectionConfig<TExplicit = unknown, TSchema extends StandardSchemaV1 = never, TFallback extends object = Record<string, unknown>> {
    /**
     * The key to use for storing the collection data in localStorage/sessionStorage
     */
    storageKey: string;
    /**
     * Storage API to use (defaults to window.localStorage)
     * Can be any object that implements the Storage interface (e.g., sessionStorage)
     */
    storage?: StorageApi;
    /**
     * Storage event API to use for cross-tab synchronization (defaults to window)
     * Can be any object that implements addEventListener/removeEventListener for storage events
     */
    storageEventApi?: StorageEventApi;
    /**
     * Collection identifier (defaults to "local-collection:{storageKey}" if not provided)
     */
    id?: string;
    schema?: TSchema;
    getKey: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>[`getKey`];
    sync?: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>[`sync`];
    /**
     * Optional asynchronous handler function called before an insert operation
     * @param params Object containing transaction and collection information
     * @returns Promise resolving to any value
     */
    onInsert?: (params: InsertMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>) => Promise<any>;
    /**
     * Optional asynchronous handler function called before an update operation
     * @param params Object containing transaction and collection information
     * @returns Promise resolving to any value
     */
    onUpdate?: (params: UpdateMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>) => Promise<any>;
    /**
     * Optional asynchronous handler function called before a delete operation
     * @param params Object containing transaction and collection information
     * @returns Promise resolving to any value
     */
    onDelete?: (params: DeleteMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>) => Promise<any>;
}
/**
 * Type for the clear utility function
 */
export type ClearStorageFn = () => void;
/**
 * Type for the getStorageSize utility function
 */
export type GetStorageSizeFn = () => number;
/**
 * LocalStorage collection utilities type
 */
export interface LocalStorageCollectionUtils extends UtilsRecord {
    clearStorage: ClearStorageFn;
    getStorageSize: GetStorageSizeFn;
}
/**
 * Creates localStorage collection options for use with a standard Collection
 *
 * This function creates a collection that persists data to localStorage/sessionStorage
 * and synchronizes changes across browser tabs using storage events.
 *
 * @template TExplicit - The explicit type of items in the collection (highest priority)
 * @template TSchema - The schema type for validation and type inference (second priority)
 * @template TFallback - The fallback type if no explicit or schema type is provided
 * @param config - Configuration options for the localStorage collection
 * @returns Collection options with utilities including clearStorage and getStorageSize
 *
 * @example
 * // Basic localStorage collection
 * const collection = createCollection(
 *   localStorageCollectionOptions({
 *     storageKey: 'todos',
 *     getKey: (item) => item.id,
 *   })
 * )
 *
 * @example
 * // localStorage collection with custom storage
 * const collection = createCollection(
 *   localStorageCollectionOptions({
 *     storageKey: 'todos',
 *     storage: window.sessionStorage, // Use sessionStorage instead
 *     getKey: (item) => item.id,
 *   })
 * )
 *
 * @example
 * // localStorage collection with mutation handlers
 * const collection = createCollection(
 *   localStorageCollectionOptions({
 *     storageKey: 'todos',
 *     getKey: (item) => item.id,
 *     onInsert: async ({ transaction }) => {
 *       console.log('Item inserted:', transaction.mutations[0].modified)
 *     },
 *   })
 * )
 */
export declare function localStorageCollectionOptions<TExplicit = unknown, TSchema extends StandardSchemaV1 = never, TFallback extends object = Record<string, unknown>>(config: LocalStorageCollectionConfig<TExplicit, TSchema, TFallback>): Omit<CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>, `id`> & {
    id: string;
    utils: LocalStorageCollectionUtils;
};