@tanstack/db 0.0.20 → 0.0.21

package/dist/esm/local-storage.js

@@ -0,0 +1,267 @@
+function validateJsonSerializable(value, operation) {
+  try {
+    JSON.stringify(value);
+  } catch (error) {
+    throw new Error(
+      `Cannot ${operation} item because it cannot be JSON serialized: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+function generateUuid() {
+  return crypto.randomUUID();
+}
+function localStorageCollectionOptions(config) {
+  if (!config.storageKey) {
+    throw new Error(`[LocalStorageCollection] storageKey must be provided.`);
+  }
+  const storage = config.storage || (typeof window !== `undefined` ? window.localStorage : null);
+  if (!storage) {
+    throw new Error(
+      `[LocalStorageCollection] No storage available. Please provide a storage option or ensure window.localStorage is available.`
+    );
+  }
+  const storageEventApi = config.storageEventApi || (typeof window !== `undefined` ? window : null);
+  if (!storageEventApi) {
+    throw new Error(
+      `[LocalStorageCollection] No storage event API available. Please provide a storageEventApi option or ensure window is available.`
+    );
+  }
+  const lastKnownData = /* @__PURE__ */ new Map();
+  const sync = createLocalStorageSync(
+    config.storageKey,
+    storage,
+    storageEventApi,
+    config.getKey,
+    lastKnownData
+  );
+  const triggerLocalSync = () => {
+    if (sync.manualTrigger) {
+      sync.manualTrigger();
+    }
+  };
+  const saveToStorage = (dataMap) => {
+    try {
+      const objectData = {};
+      dataMap.forEach((storedItem, key) => {
+        objectData[String(key)] = storedItem;
+      });
+      const serialized = JSON.stringify(objectData);
+      storage.setItem(config.storageKey, serialized);
+    } catch (error) {
+      console.error(
+        `[LocalStorageCollection] Error saving data to storage key "${config.storageKey}":`,
+        error
+      );
+      throw error;
+    }
+  };
+  const clearStorage = () => {
+    storage.removeItem(config.storageKey);
+  };
+  const getStorageSize = () => {
+    const data = storage.getItem(config.storageKey);
+    return data ? new Blob([data]).size : 0;
+  };
+  const wrappedOnInsert = async (params) => {
+    params.transaction.mutations.forEach((mutation) => {
+      validateJsonSerializable(mutation.modified, `insert`);
+    });
+    let handlerResult = {};
+    if (config.onInsert) {
+      handlerResult = await config.onInsert(params) ?? {};
+    }
+    const currentData = loadFromStorage(
+      config.storageKey,
+      storage
+    );
+    params.transaction.mutations.forEach((mutation) => {
+      const key = config.getKey(mutation.modified);
+      const storedItem = {
+        versionKey: generateUuid(),
+        data: mutation.modified
+      };
+      currentData.set(key, storedItem);
+    });
+    saveToStorage(currentData);
+    triggerLocalSync();
+    return handlerResult;
+  };
+  const wrappedOnUpdate = async (params) => {
+    params.transaction.mutations.forEach((mutation) => {
+      validateJsonSerializable(mutation.modified, `update`);
+    });
+    let handlerResult = {};
+    if (config.onUpdate) {
+      handlerResult = await config.onUpdate(params) ?? {};
+    }
+    const currentData = loadFromStorage(
+      config.storageKey,
+      storage
+    );
+    params.transaction.mutations.forEach((mutation) => {
+      const key = config.getKey(mutation.modified);
+      const storedItem = {
+        versionKey: generateUuid(),
+        data: mutation.modified
+      };
+      currentData.set(key, storedItem);
+    });
+    saveToStorage(currentData);
+    triggerLocalSync();
+    return handlerResult;
+  };
+  const wrappedOnDelete = async (params) => {
+    let handlerResult = {};
+    if (config.onDelete) {
+      handlerResult = await config.onDelete(params) ?? {};
+    }
+    const currentData = loadFromStorage(
+      config.storageKey,
+      storage
+    );
+    params.transaction.mutations.forEach((mutation) => {
+      const key = config.getKey(mutation.original);
+      currentData.delete(key);
+    });
+    saveToStorage(currentData);
+    triggerLocalSync();
+    return handlerResult;
+  };
+  const {
+    storageKey: _storageKey,
+    storage: _storage,
+    storageEventApi: _storageEventApi,
+    onInsert: _onInsert,
+    onUpdate: _onUpdate,
+    onDelete: _onDelete,
+    id,
+    ...restConfig
+  } = config;
+  const collectionId = id ?? `local-collection:${config.storageKey}`;
+  return {
+    ...restConfig,
+    id: collectionId,
+    sync,
+    onInsert: wrappedOnInsert,
+    onUpdate: wrappedOnUpdate,
+    onDelete: wrappedOnDelete,
+    utils: {
+      clearStorage,
+      getStorageSize
+    }
+  };
+}
+function loadFromStorage(storageKey, storage) {
+  try {
+    const rawData = storage.getItem(storageKey);
+    if (!rawData) {
+      return /* @__PURE__ */ new Map();
+    }
+    const parsed = JSON.parse(rawData);
+    const dataMap = /* @__PURE__ */ new Map();
+    if (typeof parsed === `object` && parsed !== null && !Array.isArray(parsed)) {
+      Object.entries(parsed).forEach(([key, value]) => {
+        if (value && typeof value === `object` && `versionKey` in value && `data` in value) {
+          const storedItem = value;
+          dataMap.set(key, storedItem);
+        } else {
+          throw new Error(
+            `[LocalStorageCollection] Invalid data format in storage key "${storageKey}" for key "${key}".`
+          );
+        }
+      });
+    } else {
+      throw new Error(
+        `[LocalStorageCollection] Invalid data format in storage key "${storageKey}". Expected object format.`
+      );
+    }
+    return dataMap;
+  } catch (error) {
+    console.warn(
+      `[LocalStorageCollection] Error loading data from storage key "${storageKey}":`,
+      error
+    );
+    return /* @__PURE__ */ new Map();
+  }
+}
+function createLocalStorageSync(storageKey, storage, storageEventApi, getKey, lastKnownData) {
+  let syncParams = null;
+  const findChanges = (oldData, newData) => {
+    const changes = [];
+    oldData.forEach((oldStoredItem, key) => {
+      const newStoredItem = newData.get(key);
+      if (!newStoredItem) {
+        changes.push({ type: `delete`, key, value: oldStoredItem.data });
+      } else if (oldStoredItem.versionKey !== newStoredItem.versionKey) {
+        changes.push({ type: `update`, key, value: newStoredItem.data });
+      }
+    });
+    newData.forEach((newStoredItem, key) => {
+      if (!oldData.has(key)) {
+        changes.push({ type: `insert`, key, value: newStoredItem.data });
+      }
+    });
+    return changes;
+  };
+  const processStorageChanges = () => {
+    if (!syncParams) return;
+    const { begin, write, commit } = syncParams;
+    const newData = loadFromStorage(storageKey, storage);
+    const changes = findChanges(lastKnownData, newData);
+    if (changes.length > 0) {
+      begin();
+      changes.forEach(({ type, value }) => {
+        if (value) {
+          validateJsonSerializable(value, type);
+          write({ type, value });
+        }
+      });
+      commit();
+      lastKnownData.clear();
+      newData.forEach((storedItem, key) => {
+        lastKnownData.set(key, storedItem);
+      });
+    }
+  };
+  const syncConfig = {
+    sync: (params) => {
+      const { begin, write, commit } = params;
+      syncParams = params;
+      const initialData = loadFromStorage(storageKey, storage);
+      if (initialData.size > 0) {
+        begin();
+        initialData.forEach((storedItem) => {
+          validateJsonSerializable(storedItem.data, `load`);
+          write({ type: `insert`, value: storedItem.data });
+        });
+        commit();
+      }
+      lastKnownData.clear();
+      initialData.forEach((storedItem, key) => {
+        lastKnownData.set(key, storedItem);
+      });
+      const handleStorageEvent = (event) => {
+        if (event.key !== storageKey || event.storageArea !== storage) {
+          return;
+        }
+        processStorageChanges();
+      };
+      storageEventApi.addEventListener(`storage`, handleStorageEvent);
+    },
+    /**
+     * Get sync metadata - returns storage key information
+     * @returns Object containing storage key and storage type metadata
+     */
+    getSyncMetadata: () => ({
+      storageKey,
+      storageType: storage === (typeof window !== `undefined` ? window.localStorage : null) ? `localStorage` : `custom`
+    }),
+    // Manual trigger function for local updates
+    manualTrigger: processStorageChanges
+  };
+  return syncConfig;
+}
+export {
+  localStorageCollectionOptions
+};
+//# sourceMappingURL=local-storage.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"local-storage.js","sources":["../../src/local-storage.ts"],"sourcesContent":["import type {\n  CollectionConfig,\n  DeleteMutationFnParams,\n  InsertMutationFnParams,\n  ResolveType,\n  SyncConfig,\n  UpdateMutationFnParams,\n  UtilsRecord,\n} from \"./types\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\n\n/**\n * Storage API interface - subset of DOM Storage that we need\n */\nexport type StorageApi = Pick<Storage, `getItem` | `setItem` | `removeItem`>\n\n/**\n * Storage event API - subset of Window for 'storage' events only\n */\nexport type StorageEventApi = {\n  addEventListener: (\n    type: `storage`,\n    listener: (event: StorageEvent) => void\n  ) => void\n  removeEventListener: (\n    type: `storage`,\n    listener: (event: StorageEvent) => void\n  ) => void\n}\n\n/**\n * Internal storage format that includes version tracking\n */\ninterface StoredItem<T> {\n  versionKey: string\n  data: T\n}\n\n/**\n * Configuration interface for localStorage 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 *\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 LocalStorageCollectionConfig<\n  TExplicit = unknown,\n  TSchema extends StandardSchemaV1 = never,\n  TFallback extends object = Record<string, unknown>,\n> {\n  /**\n   * The key to use for storing the collection data in localStorage/sessionStorage\n   */\n  storageKey: string\n\n  /**\n   * Storage API to use (defaults to window.localStorage)\n   * Can be any object that implements the Storage interface (e.g., sessionStorage)\n   */\n  storage?: StorageApi\n\n  /**\n   * Storage event API to use for cross-tab synchronization (defaults to window)\n   * Can be any object that implements addEventListener/removeEventListener for storage events\n   */\n  storageEventApi?: StorageEventApi\n\n  /**\n   * Collection identifier (defaults to \"local-collection:{storageKey}\" if not provided)\n   */\n  id?: string\n  schema?: TSchema\n  getKey: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>[`getKey`]\n  sync?: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>[`sync`]\n\n  /**\n   * Optional asynchronous handler function called before 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<ResolveType<TExplicit, TSchema, TFallback>>\n  ) => Promise<any>\n\n  /**\n   * Optional asynchronous handler function called before 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<ResolveType<TExplicit, TSchema, TFallback>>\n  ) => Promise<any>\n\n  /**\n   * Optional asynchronous handler function called before 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<ResolveType<TExplicit, TSchema, TFallback>>\n  ) => Promise<any>\n}\n\n/**\n * Type for the clear utility function\n */\nexport type ClearStorageFn = () => void\n\n/**\n * Type for the getStorageSize utility function\n */\nexport type GetStorageSizeFn = () => number\n\n/**\n * LocalStorage collection utilities type\n */\nexport interface LocalStorageCollectionUtils extends UtilsRecord {\n  clearStorage: ClearStorageFn\n  getStorageSize: GetStorageSizeFn\n}\n\n/**\n * Validates that a value can be JSON serialized\n * @param value - The value to validate for JSON serialization\n * @param operation - The operation type being performed (for error messages)\n * @throws Error if the value cannot be JSON serialized\n */\nfunction validateJsonSerializable(value: any, operation: string): void {\n  try {\n    JSON.stringify(value)\n  } catch (error) {\n    throw new Error(\n      `Cannot ${operation} item because it cannot be JSON serialized: ${\n        error instanceof Error ? error.message : String(error)\n      }`\n    )\n  }\n}\n\n/**\n * Generate a UUID for version tracking\n * @returns A unique identifier string for tracking data versions\n */\nfunction generateUuid(): string {\n  return crypto.randomUUID()\n}\n\n/**\n * Creates localStorage collection options for use with a standard Collection\n *\n * This function creates a collection that persists data to localStorage/sessionStorage\n * and synchronizes changes across browser tabs using storage events.\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 * @param config - Configuration options for the localStorage collection\n * @returns Collection options with utilities including clearStorage and getStorageSize\n *\n * @example\n * // Basic localStorage collection\n * const collection = createCollection(\n *   localStorageCollectionOptions({\n *     storageKey: 'todos',\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * @example\n * // localStorage collection with custom storage\n * const collection = createCollection(\n *   localStorageCollectionOptions({\n *     storageKey: 'todos',\n *     storage: window.sessionStorage, // Use sessionStorage instead\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * @example\n * // localStorage collection with mutation handlers\n * const collection = createCollection(\n *   localStorageCollectionOptions({\n *     storageKey: 'todos',\n *     getKey: (item) => item.id,\n *     onInsert: async ({ transaction }) => {\n *       console.log('Item inserted:', transaction.mutations[0].modified)\n *     },\n *   })\n * )\n */\nexport function localStorageCollectionOptions<\n  TExplicit = unknown,\n  TSchema extends StandardSchemaV1 = never,\n  TFallback extends object = Record<string, unknown>,\n>(config: LocalStorageCollectionConfig<TExplicit, TSchema, TFallback>) {\n  type ResolvedType = ResolveType<TExplicit, TSchema, TFallback>\n\n  // Validate required parameters\n  if (!config.storageKey) {\n    throw new Error(`[LocalStorageCollection] storageKey must be provided.`)\n  }\n\n  // Default to window.localStorage if no storage is provided\n  const storage =\n    config.storage ||\n    (typeof window !== `undefined` ? window.localStorage : null)\n\n  if (!storage) {\n    throw new Error(\n      `[LocalStorageCollection] No storage available. Please provide a storage option or ensure window.localStorage is available.`\n    )\n  }\n\n  // Default to window for storage events if not provided\n  const storageEventApi =\n    config.storageEventApi || (typeof window !== `undefined` ? window : null)\n\n  if (!storageEventApi) {\n    throw new Error(\n      `[LocalStorageCollection] No storage event API available. Please provide a storageEventApi option or ensure window is available.`\n    )\n  }\n\n  // Track the last known state to detect changes\n  const lastKnownData = new Map<string | number, StoredItem<ResolvedType>>()\n\n  // Create the sync configuration\n  const sync = createLocalStorageSync<ResolvedType>(\n    config.storageKey,\n    storage,\n    storageEventApi,\n    config.getKey,\n    lastKnownData\n  )\n\n  /**\n   * Manual trigger function for local sync updates\n   * Forces a check for storage changes and updates the collection if needed\n   */\n  const triggerLocalSync = () => {\n    if (sync.manualTrigger) {\n      sync.manualTrigger()\n    }\n  }\n\n  /**\n   * Save data to storage\n   * @param dataMap - Map of items with version tracking to save to storage\n   */\n  const saveToStorage = (\n    dataMap: Map<string | number, StoredItem<ResolvedType>>\n  ): void => {\n    try {\n      // Convert Map to object format for storage\n      const objectData: Record<string, StoredItem<ResolvedType>> = {}\n      dataMap.forEach((storedItem, key) => {\n        objectData[String(key)] = storedItem\n      })\n      const serialized = JSON.stringify(objectData)\n      storage.setItem(config.storageKey, serialized)\n    } catch (error) {\n      console.error(\n        `[LocalStorageCollection] Error saving data to storage key \"${config.storageKey}\":`,\n        error\n      )\n      throw error\n    }\n  }\n\n  /**\n   * Removes all collection data from the configured storage\n   */\n  const clearStorage: ClearStorageFn = (): void => {\n    storage.removeItem(config.storageKey)\n  }\n\n  /**\n   * Get the size of the stored data in bytes (approximate)\n   * @returns The approximate size in bytes of the stored collection data\n   */\n  const getStorageSize: GetStorageSizeFn = (): number => {\n    const data = storage.getItem(config.storageKey)\n    return data ? new Blob([data]).size : 0\n  }\n\n  /*\n   * Create wrapper handlers for direct persistence operations that perform actual storage operations\n   * Wraps the user's onInsert handler to also save changes to localStorage\n   */\n  const wrappedOnInsert = async (\n    params: InsertMutationFnParams<ResolvedType>\n  ) => {\n    // Validate that all values in the transaction can be JSON serialized\n    params.transaction.mutations.forEach((mutation) => {\n      validateJsonSerializable(mutation.modified, `insert`)\n    })\n\n    // Call the user handler BEFORE persisting changes (if provided)\n    let handlerResult: any = {}\n    if (config.onInsert) {\n      handlerResult = (await config.onInsert(params)) ?? {}\n    }\n\n    // Always persist to storage\n    // Load current data from storage\n    const currentData = loadFromStorage<ResolvedType>(\n      config.storageKey,\n      storage\n    )\n\n    // Add new items with version keys\n    params.transaction.mutations.forEach((mutation) => {\n      const key = config.getKey(mutation.modified)\n      const storedItem: StoredItem<ResolvedType> = {\n        versionKey: generateUuid(),\n        data: mutation.modified,\n      }\n      currentData.set(key, storedItem)\n    })\n\n    // Save to storage\n    saveToStorage(currentData)\n\n    // Manually trigger local sync since storage events don't fire for current tab\n    triggerLocalSync()\n\n    return handlerResult\n  }\n\n  const wrappedOnUpdate = async (\n    params: UpdateMutationFnParams<ResolvedType>\n  ) => {\n    // Validate that all values in the transaction can be JSON serialized\n    params.transaction.mutations.forEach((mutation) => {\n      validateJsonSerializable(mutation.modified, `update`)\n    })\n\n    // Call the user handler BEFORE persisting changes (if provided)\n    let handlerResult: any = {}\n    if (config.onUpdate) {\n      handlerResult = (await config.onUpdate(params)) ?? {}\n    }\n\n    // Always persist to storage\n    // Load current data from storage\n    const currentData = loadFromStorage<ResolvedType>(\n      config.storageKey,\n      storage\n    )\n\n    // Update items with new version keys\n    params.transaction.mutations.forEach((mutation) => {\n      const key = config.getKey(mutation.modified)\n      const storedItem: StoredItem<ResolvedType> = {\n        versionKey: generateUuid(),\n        data: mutation.modified,\n      }\n      currentData.set(key, storedItem)\n    })\n\n    // Save to storage\n    saveToStorage(currentData)\n\n    // Manually trigger local sync since storage events don't fire for current tab\n    triggerLocalSync()\n\n    return handlerResult\n  }\n\n  const wrappedOnDelete = async (\n    params: DeleteMutationFnParams<ResolvedType>\n  ) => {\n    // Call the user handler BEFORE persisting changes (if provided)\n    let handlerResult: any = {}\n    if (config.onDelete) {\n      handlerResult = (await config.onDelete(params)) ?? {}\n    }\n\n    // Always persist to storage\n    // Load current data from storage\n    const currentData = loadFromStorage<ResolvedType>(\n      config.storageKey,\n      storage\n    )\n\n    // Remove items\n    params.transaction.mutations.forEach((mutation) => {\n      // For delete operations, mutation.original contains the full object\n      const key = config.getKey(mutation.original)\n      currentData.delete(key)\n    })\n\n    // Save to storage\n    saveToStorage(currentData)\n\n    // Manually trigger local sync since storage events don't fire for current tab\n    triggerLocalSync()\n\n    return handlerResult\n  }\n\n  // Extract standard Collection config properties\n  const {\n    storageKey: _storageKey,\n    storage: _storage,\n    storageEventApi: _storageEventApi,\n    onInsert: _onInsert,\n    onUpdate: _onUpdate,\n    onDelete: _onDelete,\n    id,\n    ...restConfig\n  } = config\n\n  // Default id to a pattern based on storage key if not provided\n  const collectionId = id ?? `local-collection:${config.storageKey}`\n\n  return {\n    ...restConfig,\n    id: collectionId,\n    sync,\n    onInsert: wrappedOnInsert,\n    onUpdate: wrappedOnUpdate,\n    onDelete: wrappedOnDelete,\n    utils: {\n      clearStorage,\n      getStorageSize,\n    },\n  }\n}\n\n/**\n * Load data from storage and return as a Map\n * @param storageKey - The key used to store data in the storage API\n * @param storage - The storage API to load from (localStorage, sessionStorage, etc.)\n * @returns Map of stored items with version tracking, or empty Map if loading fails\n */\nfunction loadFromStorage<T extends object>(\n  storageKey: string,\n  storage: StorageApi\n): Map<string | number, StoredItem<T>> {\n  try {\n    const rawData = storage.getItem(storageKey)\n    if (!rawData) {\n      return new Map()\n    }\n\n    const parsed = JSON.parse(rawData)\n    const dataMap = new Map<string | number, StoredItem<T>>()\n\n    // Handle object format where keys map to StoredItem values\n    if (\n      typeof parsed === `object` &&\n      parsed !== null &&\n      !Array.isArray(parsed)\n    ) {\n      Object.entries(parsed).forEach(([key, value]) => {\n        // Runtime check to ensure the value has the expected StoredItem structure\n        if (\n          value &&\n          typeof value === `object` &&\n          `versionKey` in value &&\n          `data` in value\n        ) {\n          const storedItem = value as StoredItem<T>\n          dataMap.set(key, storedItem)\n        } else {\n          throw new Error(\n            `[LocalStorageCollection] Invalid data format in storage key \"${storageKey}\" for key \"${key}\".`\n          )\n        }\n      })\n    } else {\n      throw new Error(\n        `[LocalStorageCollection] Invalid data format in storage key \"${storageKey}\". Expected object format.`\n      )\n    }\n\n    return dataMap\n  } catch (error) {\n    console.warn(\n      `[LocalStorageCollection] Error loading data from storage key \"${storageKey}\":`,\n      error\n    )\n    return new Map()\n  }\n}\n\n/**\n * Internal function to create localStorage sync configuration\n * Creates a sync configuration that handles localStorage persistence and cross-tab synchronization\n * @param storageKey - The key used for storing data in localStorage\n * @param storage - The storage API to use (localStorage, sessionStorage, etc.)\n * @param storageEventApi - The event API for listening to storage changes\n * @param getKey - Function to extract the key from an item\n * @param lastKnownData - Map tracking the last known state for change detection\n * @returns Sync configuration with manual trigger capability\n */\nfunction createLocalStorageSync<T extends object>(\n  storageKey: string,\n  storage: StorageApi,\n  storageEventApi: StorageEventApi,\n  getKey: (item: T) => string | number,\n  lastKnownData: Map<string | number, StoredItem<T>>\n): SyncConfig<T> & { manualTrigger?: () => void } {\n  let syncParams: Parameters<SyncConfig<T>[`sync`]>[0] | null = null\n\n  /**\n   * Compare two Maps to find differences using version keys\n   * @param oldData - The previous state of stored items\n   * @param newData - The current state of stored items\n   * @returns Array of changes with type, key, and value information\n   */\n  const findChanges = (\n    oldData: Map<string | number, StoredItem<T>>,\n    newData: Map<string | number, StoredItem<T>>\n  ): Array<{\n    type: `insert` | `update` | `delete`\n    key: string | number\n    value?: T\n  }> => {\n    const changes: Array<{\n      type: `insert` | `update` | `delete`\n      key: string | number\n      value?: T\n    }> = []\n\n    // Check for deletions and updates\n    oldData.forEach((oldStoredItem, key) => {\n      const newStoredItem = newData.get(key)\n      if (!newStoredItem) {\n        changes.push({ type: `delete`, key, value: oldStoredItem.data })\n      } else if (oldStoredItem.versionKey !== newStoredItem.versionKey) {\n        changes.push({ type: `update`, key, value: newStoredItem.data })\n      }\n    })\n\n    // Check for insertions\n    newData.forEach((newStoredItem, key) => {\n      if (!oldData.has(key)) {\n        changes.push({ type: `insert`, key, value: newStoredItem.data })\n      }\n    })\n\n    return changes\n  }\n\n  /**\n   * Process storage changes and update collection\n   * Loads new data from storage, compares with last known state, and applies changes\n   */\n  const processStorageChanges = () => {\n    if (!syncParams) return\n\n    const { begin, write, commit } = syncParams\n\n    // Load the new data\n    const newData = loadFromStorage<T>(storageKey, storage)\n\n    // Find the specific changes\n    const changes = findChanges(lastKnownData, newData)\n\n    if (changes.length > 0) {\n      begin()\n      changes.forEach(({ type, value }) => {\n        if (value) {\n          validateJsonSerializable(value, type)\n          write({ type, value })\n        }\n      })\n      commit()\n\n      // Update lastKnownData\n      lastKnownData.clear()\n      newData.forEach((storedItem, key) => {\n        lastKnownData.set(key, storedItem)\n      })\n    }\n  }\n\n  const syncConfig: SyncConfig<T> & { manualTrigger?: () => void } = {\n    sync: (params: Parameters<SyncConfig<T>[`sync`]>[0]) => {\n      const { begin, write, commit } = params\n\n      // Store sync params for later use\n      syncParams = params\n\n      // Initial load\n      const initialData = loadFromStorage<T>(storageKey, storage)\n      if (initialData.size > 0) {\n        begin()\n        initialData.forEach((storedItem) => {\n          validateJsonSerializable(storedItem.data, `load`)\n          write({ type: `insert`, value: storedItem.data })\n        })\n        commit()\n      }\n\n      // Update lastKnownData\n      lastKnownData.clear()\n      initialData.forEach((storedItem, key) => {\n        lastKnownData.set(key, storedItem)\n      })\n\n      // Listen for storage events from other tabs\n      const handleStorageEvent = (event: StorageEvent) => {\n        // Only respond to changes to our specific key and from our storage\n        if (event.key !== storageKey || event.storageArea !== storage) {\n          return\n        }\n\n        processStorageChanges()\n      }\n\n      // Add storage event listener for cross-tab sync\n      storageEventApi.addEventListener(`storage`, handleStorageEvent)\n\n      // Note: Cleanup is handled automatically by the collection when it's disposed\n    },\n\n    /**\n     * Get sync metadata - returns storage key information\n     * @returns Object containing storage key and storage type metadata\n     */\n    getSyncMetadata: () => ({\n      storageKey,\n      storageType:\n        storage === (typeof window !== `undefined` ? window.localStorage : null)\n          ? `localStorage`\n          : `custom`,\n    }),\n\n    // Manual trigger function for local updates\n    manualTrigger: processStorageChanges,\n  }\n\n  return syncConfig\n}\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tanstack/db",
   "description": "A reactive client store for building super fast apps on sync",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "dependencies": {
     "@electric-sql/d2mini": "^0.1.6",
     "@standard-schema/spec": "^1.0.0"

package/src/index.ts

@@ -7,6 +7,8 @@ export * from "./errors"
 export * from "./proxy"
 export * from "./query/index.js"
 export * from "./optimistic-action"
+export * from "./local-only"
+export * from "./local-storage"
 
 // Re-export some stuff explicitly to ensure the type & value is exported
 export type { Collection } from "./collection"

package/src/local-only.ts

@@ -0,0 +1,302 @@
+import type {
+  DeleteMutationFnParams,
+  InsertMutationFnParams,
+  OperationType,
+  ResolveType,
+  SyncConfig,
+  UpdateMutationFnParams,
+  UtilsRecord,
+} from "./types"
+import type { 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 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>) {
+  type ResolvedType = ResolveType<TExplicit, TSchema, TFallback>
+
+  const { initialData, onInsert, onUpdate, onDelete, ...restConfig } = config
+
+  // Create the sync configuration with transaction confirmation capability
+  const syncResult = createLocalOnlySync<ResolvedType, TKey>(initialData)
+
+  /**
+   * Create wrapper handlers that call user handlers first, then confirm transactions
+   * Wraps the user's onInsert handler to also confirm the transaction immediately
+   */
+  const wrappedOnInsert = async (
+    params: InsertMutationFnParams<ResolvedType, TKey, LocalOnlyCollectionUtils>
+  ) => {
+    // Call user handler first if provided
+    let handlerResult
+    if (onInsert) {
+      handlerResult = (await onInsert(params)) ?? {}
+    }
+
+    // Then synchronously confirm the transaction by looping through mutations
+    syncResult.confirmOperationsSync(params.transaction.mutations)
+
+    return handlerResult
+  }
+
+  /**
+   * Wrapper for onUpdate handler that also confirms the transaction immediately
+   */
+  const wrappedOnUpdate = async (
+    params: UpdateMutationFnParams<ResolvedType, TKey, LocalOnlyCollectionUtils>
+  ) => {
+    // Call user handler first if provided
+    let handlerResult
+    if (onUpdate) {
+      handlerResult = (await onUpdate(params)) ?? {}
+    }
+
+    // Then synchronously confirm the transaction by looping through mutations
+    syncResult.confirmOperationsSync(params.transaction.mutations)
+
+    return handlerResult
+  }
+
+  /**
+   * Wrapper for onDelete handler that also confirms the transaction immediately
+   */
+  const wrappedOnDelete = async (
+    params: DeleteMutationFnParams<ResolvedType, TKey, LocalOnlyCollectionUtils>
+  ) => {
+    // Call user handler first if provided
+    let handlerResult
+    if (onDelete) {
+      handlerResult = (await onDelete(params)) ?? {}
+    }
+
+    // Then synchronously confirm the transaction by looping through mutations
+    syncResult.confirmOperationsSync(params.transaction.mutations)
+
+    return handlerResult
+  }
+
+  return {
+    ...restConfig,
+    sync: syncResult.sync,
+    onInsert: wrappedOnInsert,
+    onUpdate: wrappedOnUpdate,
+    onDelete: wrappedOnDelete,
+    utils: {} as LocalOnlyCollectionUtils,
+    startSync: true,
+    gcTime: 0,
+  }
+}
+
+/**
+ * Internal function to create Local-only sync configuration with transaction confirmation
+ *
+ * This captures the sync functions and provides synchronous confirmation of operations.
+ * It creates a loopback sync that immediately confirms all optimistic operations,
+ * making them permanent in the collection.
+ *
+ * @param initialData - Optional array of initial items to populate the collection
+ * @returns Object with sync configuration and confirmOperationsSync function
+ */
+function createLocalOnlySync<T extends object, TKey extends string | number>(
+  initialData?: Array<T>
+) {
+  // Capture sync functions for transaction confirmation
+  let syncBegin: (() => void) | null = null
+  let syncWrite: ((message: { type: OperationType; value: T }) => void) | null =
+    null
+  let syncCommit: (() => void) | null = null
+
+  const sync: SyncConfig<T, TKey> = {
+    /**
+     * 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
+
+      // Capture sync functions for later use by confirmOperationsSync
+      syncBegin = begin
+      syncWrite = write
+      syncCommit = commit
+
+      // Apply initial data if provided
+      if (initialData && initialData.length > 0) {
+        begin()
+        initialData.forEach((item) => {
+          write({
+            type: `insert`,
+            value: item,
+          })
+        })
+        commit()
+      }
+
+      // Return empty unsubscribe function - no ongoing sync needed
+      return () => {}
+    },
+    /**
+     * Get sync metadata - returns empty object for local-only collections
+     * @returns Empty metadata object
+     */
+    getSyncMetadata: () => ({}),
+  }
+
+  /**
+   * Synchronously confirms optimistic operations by immediately writing through sync
+   *
+   * This loops through transaction mutations and applies them to move from optimistic to synced state.
+   * It's called after user handlers to make optimistic changes permanent.
+   *
+   * @param mutations - Array of mutation objects from the transaction
+   */
+  const confirmOperationsSync = (mutations: Array<any>) => {
+    if (!syncBegin || !syncWrite || !syncCommit) {
+      return // Sync not initialized yet, which is fine
+    }
+
+    // Immediately write back through sync interface
+    syncBegin()
+    mutations.forEach((mutation) => {
+      if (syncWrite) {
+        syncWrite({
+          type: mutation.type,
+          value: mutation.modified,
+        })
+      }
+    })
+    syncCommit()
+  }
+
+  return {
+    sync,
+    confirmOperationsSync,
+  }
+}