@tanstack/db 0.0.20 → 0.0.21

package/dist/cjs/local-storage.d.cts

@@ -0,0 +1,141 @@
+import { CollectionConfig, DeleteMutationFnParams, InsertMutationFnParams, ResolveType, SyncConfig, UpdateMutationFnParams, UtilsRecord } from './types.cjs';
+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>): {
+    id: string;
+    sync: SyncConfig<ResolveType<TExplicit, TSchema, TFallback>, string | number> & {
+        manualTrigger?: () => void;
+    };
+    onInsert: (params: InsertMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>) => Promise<any>;
+    onUpdate: (params: UpdateMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>) => Promise<any>;
+    onDelete: (params: DeleteMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>) => Promise<any>;
+    utils: {
+        clearStorage: ClearStorageFn;
+        getStorageSize: GetStorageSizeFn;
+    };
+    schema?: TSchema | undefined;
+    getKey: (item: ResolveType<TExplicit, TSchema, TFallback>) => string | number;
+};

package/dist/esm/index.d.ts

@@ -6,4 +6,6 @@ export * from './errors.js';
 export * from './proxy.js';
 export * from './query/index.js';
 export * from './optimistic-action.js';
+export * from './local-only.js';
+export * from './local-storage.js';
 export type { Collection } from './collection.js';

package/dist/esm/index.js

@@ -4,6 +4,8 @@ import { createTransaction, getActiveTransaction } from "./transactions.js";
 import { NonRetriableError } from "./errors.js";
 import { createArrayChangeProxy, createChangeProxy, withArrayChangeTracking, withChangeTracking } from "./proxy.js";
 import { createOptimisticAction } from "./optimistic-action.js";
+import { localOnlyCollectionOptions } from "./local-only.js";
+import { localStorageCollectionOptions } from "./local-storage.js";
 import { BaseQueryBuilder, Query } from "./query/builder/index.js";
 import { add, and, avg, coalesce, concat, count, eq, gt, gte, ilike, inArray, length, like, lower, lt, lte, max, min, not, or, sum, upper } from "./query/builder/functions.js";
 import { compileQuery } from "./query/compiler/index.js";
@@ -38,6 +40,8 @@ export {
   length,
   like,
   liveQueryCollectionOptions,
+  localOnlyCollectionOptions,
+  localStorageCollectionOptions,
   lower,
   lt,
   lte,

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;"}

package/dist/esm/local-only.d.ts

@@ -0,0 +1,114 @@
+import { DeleteMutationFnParams, InsertMutationFnParams, ResolveType, SyncConfig, UpdateMutationFnParams, UtilsRecord } from './types.js';
+import { StandardSchemaV1 } from '@standard-schema/spec';
+/**
+ * Configuration interface for Local-only 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
+ * @template TKey - The type of the key returned by getKey
+ *
+ * @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 LocalOnlyCollectionConfig<TExplicit = unknown, TSchema extends StandardSchemaV1 = never, TFallback extends Record<string, unknown> = Record<string, unknown>, TKey extends string | number = string | number> {
+    /**
+     * Standard Collection configuration properties
+     */
+    id?: string;
+    schema?: TSchema;
+    getKey: (item: ResolveType<TExplicit, TSchema, TFallback>) => TKey;
+    /**
+     * Optional initial data to populate the collection with on creation
+     * This data will be applied during the initial sync process
+     */
+    initialData?: Array<ResolveType<TExplicit, TSchema, TFallback>>;
+    /**
+     * Optional asynchronous handler function called after an insert operation
+     * @param params Object containing transaction and collection information
+     * @returns Promise resolving to any value
+     */
+    onInsert?: (params: InsertMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>, TKey, LocalOnlyCollectionUtils>) => Promise<any>;
+    /**
+     * Optional asynchronous handler function called after an update operation
+     * @param params Object containing transaction and collection information
+     * @returns Promise resolving to any value
+     */
+    onUpdate?: (params: UpdateMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>, TKey, LocalOnlyCollectionUtils>) => Promise<any>;
+    /**
+     * Optional asynchronous handler function called after a delete operation
+     * @param params Object containing transaction and collection information
+     * @returns Promise resolving to any value
+     */
+    onDelete?: (params: DeleteMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>, TKey, LocalOnlyCollectionUtils>) => Promise<any>;
+}
+/**
+ * Local-only collection utilities type (currently empty but matches the pattern)
+ */
+export interface LocalOnlyCollectionUtils extends UtilsRecord {
+}
+/**
+ * Creates Local-only collection options for use with a standard Collection
+ *
+ * This is an in-memory collection that doesn't sync with external sources but uses a loopback sync config
+ * that immediately "syncs" all optimistic changes to the collection, making them permanent.
+ * Perfect for local-only data that doesn't need persistence or external synchronization.
+ *
+ * @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
+ * @template TKey - The type of the key returned by getKey
+ * @param config - Configuration options for the Local-only collection
+ * @returns Collection options with utilities (currently empty but follows the pattern)
+ *
+ * @example
+ * // Basic local-only collection
+ * const collection = createCollection(
+ *   localOnlyCollectionOptions({
+ *     getKey: (item) => item.id,
+ *   })
+ * )
+ *
+ * @example
+ * // Local-only collection with initial data
+ * const collection = createCollection(
+ *   localOnlyCollectionOptions({
+ *     getKey: (item) => item.id,
+ *     initialData: [
+ *       { id: 1, name: 'Item 1' },
+ *       { id: 2, name: 'Item 2' },
+ *     ],
+ *   })
+ * )
+ *
+ * @example
+ * // Local-only collection with mutation handlers
+ * const collection = createCollection(
+ *   localOnlyCollectionOptions({
+ *     getKey: (item) => item.id,
+ *     onInsert: async ({ transaction }) => {
+ *       console.log('Item inserted:', transaction.mutations[0].modified)
+ *       // Custom logic after insert
+ *     },
+ *   })
+ * )
+ */
+export declare function localOnlyCollectionOptions<TExplicit = unknown, TSchema extends StandardSchemaV1 = never, TFallback extends Record<string, unknown> = Record<string, unknown>, TKey extends string | number = string | number>(config: LocalOnlyCollectionConfig<TExplicit, TSchema, TFallback, TKey>): {
+    sync: SyncConfig<ResolveType<TExplicit, TSchema, TFallback>, TKey>;
+    onInsert: (params: InsertMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>, TKey, LocalOnlyCollectionUtils>) => Promise<any>;
+    onUpdate: (params: UpdateMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>, TKey, LocalOnlyCollectionUtils>) => Promise<any>;
+    onDelete: (params: DeleteMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>, TKey, LocalOnlyCollectionUtils>) => Promise<any>;
+    utils: LocalOnlyCollectionUtils;
+    startSync: boolean;
+    gcTime: number;
+    /**
+     * Standard Collection configuration properties
+     */
+    id?: string;
+    schema?: TSchema | undefined;
+    getKey: (item: ResolveType<TExplicit, TSchema, TFallback>) => TKey;
+};

package/dist/esm/local-only.js

@@ -0,0 +1,96 @@
+function localOnlyCollectionOptions(config) {
+  const { initialData, onInsert, onUpdate, onDelete, ...restConfig } = config;
+  const syncResult = createLocalOnlySync(initialData);
+  const wrappedOnInsert = async (params) => {
+    let handlerResult;
+    if (onInsert) {
+      handlerResult = await onInsert(params) ?? {};
+    }
+    syncResult.confirmOperationsSync(params.transaction.mutations);
+    return handlerResult;
+  };
+  const wrappedOnUpdate = async (params) => {
+    let handlerResult;
+    if (onUpdate) {
+      handlerResult = await onUpdate(params) ?? {};
+    }
+    syncResult.confirmOperationsSync(params.transaction.mutations);
+    return handlerResult;
+  };
+  const wrappedOnDelete = async (params) => {
+    let handlerResult;
+    if (onDelete) {
+      handlerResult = await onDelete(params) ?? {};
+    }
+    syncResult.confirmOperationsSync(params.transaction.mutations);
+    return handlerResult;
+  };
+  return {
+    ...restConfig,
+    sync: syncResult.sync,
+    onInsert: wrappedOnInsert,
+    onUpdate: wrappedOnUpdate,
+    onDelete: wrappedOnDelete,
+    utils: {},
+    startSync: true,
+    gcTime: 0
+  };
+}
+function createLocalOnlySync(initialData) {
+  let syncBegin = null;
+  let syncWrite = null;
+  let syncCommit = null;
+  const sync = {
+    /**
+     * Sync function that captures sync parameters and applies initial data
+     * @param params - Sync parameters containing begin, write, and commit functions
+     * @returns Unsubscribe function (empty since no ongoing sync is needed)
+     */
+    sync: (params) => {
+      const { begin, write, commit } = params;
+      syncBegin = begin;
+      syncWrite = write;
+      syncCommit = commit;
+      if (initialData && initialData.length > 0) {
+        begin();
+        initialData.forEach((item) => {
+          write({
+            type: `insert`,
+            value: item
+          });
+        });
+        commit();
+      }
+      return () => {
+      };
+    },
+    /**
+     * Get sync metadata - returns empty object for local-only collections
+     * @returns Empty metadata object
+     */
+    getSyncMetadata: () => ({})
+  };
+  const confirmOperationsSync = (mutations) => {
+    if (!syncBegin || !syncWrite || !syncCommit) {
+      return;
+    }
+    syncBegin();
+    mutations.forEach((mutation) => {
+      if (syncWrite) {
+        syncWrite({
+          type: mutation.type,
+          value: mutation.modified
+        });
+      }
+    });
+    syncCommit();
+  };
+  return {
+    sync,
+    confirmOperationsSync
+  };
+}
+export {
+  localOnlyCollectionOptions
+};
+//# sourceMappingURL=local-only.js.map

package/dist/esm/local-only.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-only.js","sources":["../../src/local-only.ts"],"sourcesContent":["import type {\n  DeleteMutationFnParams,\n  InsertMutationFnParams,\n  OperationType,\n  ResolveType,\n  SyncConfig,\n  UpdateMutationFnParams,\n  UtilsRecord,\n} from \"./types\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\n\n/**\n * Configuration interface for Local-only collection options\n * @template TExplicit - The explicit type of items in the collection (highest priority)\n * @template TSchema - The schema type for validation and type inference (second priority)\n * @template TFallback - The fallback type if no explicit or schema type is provided\n * @template TKey - The type of the key returned by getKey\n *\n * @remarks\n * Type resolution follows a priority order:\n * 1. If you provide an explicit type via generic parameter, it will be used\n * 2. If no explicit type is provided but a schema is, the schema's output type will be inferred\n * 3. If neither explicit type nor schema is provided, the fallback type will be used\n *\n * You should provide EITHER an explicit type OR a schema, but not both, as they would conflict.\n */\nexport interface LocalOnlyCollectionConfig<\n  TExplicit = unknown,\n  TSchema extends StandardSchemaV1 = never,\n  TFallback extends Record<string, unknown> = Record<string, unknown>,\n  TKey extends string | number = string | number,\n> {\n  /**\n   * Standard Collection configuration properties\n   */\n  id?: string\n  schema?: TSchema\n  getKey: (item: ResolveType<TExplicit, TSchema, TFallback>) => TKey\n\n  /**\n   * Optional initial data to populate the collection with on creation\n   * This data will be applied during the initial sync process\n   */\n  initialData?: Array<ResolveType<TExplicit, TSchema, TFallback>>\n\n  /**\n   * Optional asynchronous handler function called after an insert operation\n   * @param params Object containing transaction and collection information\n   * @returns Promise resolving to any value\n   */\n  onInsert?: (\n    params: InsertMutationFnParams<\n      ResolveType<TExplicit, TSchema, TFallback>,\n      TKey,\n      LocalOnlyCollectionUtils\n    >\n  ) => Promise<any>\n\n  /**\n   * Optional asynchronous handler function called after an update operation\n   * @param params Object containing transaction and collection information\n   * @returns Promise resolving to any value\n   */\n  onUpdate?: (\n    params: UpdateMutationFnParams<\n      ResolveType<TExplicit, TSchema, TFallback>,\n      TKey,\n      LocalOnlyCollectionUtils\n    >\n  ) => Promise<any>\n\n  /**\n   * Optional asynchronous handler function called after a delete operation\n   * @param params Object containing transaction and collection information\n   * @returns Promise resolving to any value\n   */\n  onDelete?: (\n    params: DeleteMutationFnParams<\n      ResolveType<TExplicit, TSchema, TFallback>,\n      TKey,\n      LocalOnlyCollectionUtils\n    >\n  ) => Promise<any>\n}\n\n/**\n * Local-only collection utilities type (currently empty but matches the pattern)\n */\nexport interface LocalOnlyCollectionUtils extends UtilsRecord {}\n\n/**\n * Creates Local-only collection options for use with a standard Collection\n *\n * This is an in-memory collection that doesn't sync with external sources but uses a loopback sync config\n * that immediately \"syncs\" all optimistic changes to the collection, making them permanent.\n * Perfect for local-only data that doesn't need persistence or external synchronization.\n *\n * @template TExplicit - The explicit type of items in the collection (highest priority)\n * @template TSchema - The schema type for validation and type inference (second priority)\n * @template TFallback - The fallback type if no explicit or schema type is provided\n * @template TKey - The type of the key returned by getKey\n * @param config - Configuration options for the Local-only collection\n * @returns Collection options with utilities (currently empty but follows the pattern)\n *\n * @example\n * // Basic local-only collection\n * const collection = createCollection(\n *   localOnlyCollectionOptions({\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * @example\n * // Local-only collection with initial data\n * const collection = createCollection(\n *   localOnlyCollectionOptions({\n *     getKey: (item) => item.id,\n *     initialData: [\n *       { id: 1, name: 'Item 1' },\n *       { id: 2, name: 'Item 2' },\n *     ],\n *   })\n * )\n *\n * @example\n * // Local-only collection with mutation handlers\n * const collection = createCollection(\n *   localOnlyCollectionOptions({\n *     getKey: (item) => item.id,\n *     onInsert: async ({ transaction }) => {\n *       console.log('Item inserted:', transaction.mutations[0].modified)\n *       // Custom logic after insert\n *     },\n *   })\n * )\n */\nexport function localOnlyCollectionOptions<\n  TExplicit = unknown,\n  TSchema extends StandardSchemaV1 = never,\n  TFallback extends Record<string, unknown> = Record<string, unknown>,\n  TKey extends string | number = string | number,\n>(config: LocalOnlyCollectionConfig<TExplicit, TSchema, TFallback, TKey>) {\n  type ResolvedType = ResolveType<TExplicit, TSchema, TFallback>\n\n  const { initialData, onInsert, onUpdate, onDelete, ...restConfig } = config\n\n  // Create the sync configuration with transaction confirmation capability\n  const syncResult = createLocalOnlySync<ResolvedType, TKey>(initialData)\n\n  /**\n   * Create wrapper handlers that call user handlers first, then confirm transactions\n   * Wraps the user's onInsert handler to also confirm the transaction immediately\n   */\n  const wrappedOnInsert = async (\n    params: InsertMutationFnParams<ResolvedType, TKey, LocalOnlyCollectionUtils>\n  ) => {\n    // Call user handler first if provided\n    let handlerResult\n    if (onInsert) {\n      handlerResult = (await onInsert(params)) ?? {}\n    }\n\n    // Then synchronously confirm the transaction by looping through mutations\n    syncResult.confirmOperationsSync(params.transaction.mutations)\n\n    return handlerResult\n  }\n\n  /**\n   * Wrapper for onUpdate handler that also confirms the transaction immediately\n   */\n  const wrappedOnUpdate = async (\n    params: UpdateMutationFnParams<ResolvedType, TKey, LocalOnlyCollectionUtils>\n  ) => {\n    // Call user handler first if provided\n    let handlerResult\n    if (onUpdate) {\n      handlerResult = (await onUpdate(params)) ?? {}\n    }\n\n    // Then synchronously confirm the transaction by looping through mutations\n    syncResult.confirmOperationsSync(params.transaction.mutations)\n\n    return handlerResult\n  }\n\n  /**\n   * Wrapper for onDelete handler that also confirms the transaction immediately\n   */\n  const wrappedOnDelete = async (\n    params: DeleteMutationFnParams<ResolvedType, TKey, LocalOnlyCollectionUtils>\n  ) => {\n    // Call user handler first if provided\n    let handlerResult\n    if (onDelete) {\n      handlerResult = (await onDelete(params)) ?? {}\n    }\n\n    // Then synchronously confirm the transaction by looping through mutations\n    syncResult.confirmOperationsSync(params.transaction.mutations)\n\n    return handlerResult\n  }\n\n  return {\n    ...restConfig,\n    sync: syncResult.sync,\n    onInsert: wrappedOnInsert,\n    onUpdate: wrappedOnUpdate,\n    onDelete: wrappedOnDelete,\n    utils: {} as LocalOnlyCollectionUtils,\n    startSync: true,\n    gcTime: 0,\n  }\n}\n\n/**\n * Internal function to create Local-only sync configuration with transaction confirmation\n *\n * This captures the sync functions and provides synchronous confirmation of operations.\n * It creates a loopback sync that immediately confirms all optimistic operations,\n * making them permanent in the collection.\n *\n * @param initialData - Optional array of initial items to populate the collection\n * @returns Object with sync configuration and confirmOperationsSync function\n */\nfunction createLocalOnlySync<T extends object, TKey extends string | number>(\n  initialData?: Array<T>\n) {\n  // Capture sync functions for transaction confirmation\n  let syncBegin: (() => void) | null = null\n  let syncWrite: ((message: { type: OperationType; value: T }) => void) | null =\n    null\n  let syncCommit: (() => void) | null = null\n\n  const sync: SyncConfig<T, TKey> = {\n    /**\n     * Sync function that captures sync parameters and applies initial data\n     * @param params - Sync parameters containing begin, write, and commit functions\n     * @returns Unsubscribe function (empty since no ongoing sync is needed)\n     */\n    sync: (params) => {\n      const { begin, write, commit } = params\n\n      // Capture sync functions for later use by confirmOperationsSync\n      syncBegin = begin\n      syncWrite = write\n      syncCommit = commit\n\n      // Apply initial data if provided\n      if (initialData && initialData.length > 0) {\n        begin()\n        initialData.forEach((item) => {\n          write({\n            type: `insert`,\n            value: item,\n          })\n        })\n        commit()\n      }\n\n      // Return empty unsubscribe function - no ongoing sync needed\n      return () => {}\n    },\n    /**\n     * Get sync metadata - returns empty object for local-only collections\n     * @returns Empty metadata object\n     */\n    getSyncMetadata: () => ({}),\n  }\n\n  /**\n   * Synchronously confirms optimistic operations by immediately writing through sync\n   *\n   * This loops through transaction mutations and applies them to move from optimistic to synced state.\n   * It's called after user handlers to make optimistic changes permanent.\n   *\n   * @param mutations - Array of mutation objects from the transaction\n   */\n  const confirmOperationsSync = (mutations: Array<any>) => {\n    if (!syncBegin || !syncWrite || !syncCommit) {\n      return // Sync not initialized yet, which is fine\n    }\n\n    // Immediately write back through sync interface\n    syncBegin()\n    mutations.forEach((mutation) => {\n      if (syncWrite) {\n        syncWrite({\n          type: mutation.type,\n          value: mutation.modified,\n        })\n      }\n    })\n    syncCommit()\n  }\n\n  return {\n    sync,\n    confirmOperationsSync,\n  }\n}\n"],"names":[],"mappings":"AAwIO,SAAS,2BAKd,QAAwE;AAGxE,QAAM,EAAE,aAAa,UAAU,UAAU,UAAU,GAAG,eAAe;AAGrE,QAAM,aAAa,oBAAwC,WAAW;AAMtE,QAAM,kBAAkB,OACtB,WACG;AAEH,QAAI;AACJ,QAAI,UAAU;AACZ,sBAAiB,MAAM,SAAS,MAAM,KAAM,CAAA;AAAA,IAC9C;AAGA,eAAW,sBAAsB,OAAO,YAAY,SAAS;AAE7D,WAAO;AAAA,EACT;AAKA,QAAM,kBAAkB,OACtB,WACG;AAEH,QAAI;AACJ,QAAI,UAAU;AACZ,sBAAiB,MAAM,SAAS,MAAM,KAAM,CAAA;AAAA,IAC9C;AAGA,eAAW,sBAAsB,OAAO,YAAY,SAAS;AAE7D,WAAO;AAAA,EACT;AAKA,QAAM,kBAAkB,OACtB,WACG;AAEH,QAAI;AACJ,QAAI,UAAU;AACZ,sBAAiB,MAAM,SAAS,MAAM,KAAM,CAAA;AAAA,IAC9C;AAGA,eAAW,sBAAsB,OAAO,YAAY,SAAS;AAE7D,WAAO;AAAA,EACT;AAEA,SAAO;AAAA,IACL,GAAG;AAAA,IACH,MAAM,WAAW;AAAA,IACjB,UAAU;AAAA,IACV,UAAU;AAAA,IACV,UAAU;AAAA,IACV,OAAO,CAAA;AAAA,IACP,WAAW;AAAA,IACX,QAAQ;AAAA,EAAA;AAEZ;AAYA,SAAS,oBACP,aACA;AAEA,MAAI,YAAiC;AACrC,MAAI,YACF;AACF,MAAI,aAAkC;AAEtC,QAAM,OAA4B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAMhC,MAAM,CAAC,WAAW;AAChB,YAAM,EAAE,OAAO,OAAO,OAAA,IAAW;AAGjC,kBAAY;AACZ,kBAAY;AACZ,mBAAa;AAGb,UAAI,eAAe,YAAY,SAAS,GAAG;AACzC,cAAA;AACA,oBAAY,QAAQ,CAAC,SAAS;AAC5B,gBAAM;AAAA,YACJ,MAAM;AAAA,YACN,OAAO;AAAA,UAAA,CACR;AAAA,QACH,CAAC;AACD,eAAA;AAAA,MACF;AAGA,aAAO,MAAM;AAAA,MAAC;AAAA,IAChB;AAAA;AAAA;AAAA;AAAA;AAAA,IAKA,iBAAiB,OAAO,CAAA;AAAA,EAAC;AAW3B,QAAM,wBAAwB,CAAC,cAA0B;AACvD,QAAI,CAAC,aAAa,CAAC,aAAa,CAAC,YAAY;AAC3C;AAAA,IACF;AAGA,cAAA;AACA,cAAU,QAAQ,CAAC,aAAa;AAC9B,UAAI,WAAW;AACb,kBAAU;AAAA,UACR,MAAM,SAAS;AAAA,UACf,OAAO,SAAS;AAAA,QAAA,CACjB;AAAA,MACH;AAAA,IACF,CAAC;AACD,eAAA;AAAA,EACF;AAEA,SAAO;AAAA,IACL;AAAA,IACA;AAAA,EAAA;AAEJ;"}

package/dist/esm/local-storage.d.ts

@@ -0,0 +1,141 @@
+import { CollectionConfig, DeleteMutationFnParams, InsertMutationFnParams, ResolveType, SyncConfig, 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>): {
+    id: string;
+    sync: SyncConfig<ResolveType<TExplicit, TSchema, TFallback>, string | number> & {
+        manualTrigger?: () => void;
+    };
+    onInsert: (params: InsertMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>) => Promise<any>;
+    onUpdate: (params: UpdateMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>) => Promise<any>;
+    onDelete: (params: DeleteMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>) => Promise<any>;
+    utils: {
+        clearStorage: ClearStorageFn;
+        getStorageSize: GetStorageSizeFn;
+    };
+    schema?: TSchema | undefined;
+    getKey: (item: ResolveType<TExplicit, TSchema, TFallback>) => string | number;
+};