@tanstack/db 0.4.11 → 0.4.13

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

@@ -1 +1 @@
-{"version":3,"file":"local-storage.js","sources":["../../src/local-storage.ts"],"sourcesContent":["import {\n  InvalidStorageDataFormatError,\n  InvalidStorageObjectFormatError,\n  NoStorageAvailableError,\n  NoStorageEventApiError,\n  SerializationError,\n  StorageKeyRequiredError,\n} from \"./errors\"\nimport type {\n  BaseCollectionConfig,\n  CollectionConfig,\n  DeleteMutationFnParams,\n  InferSchemaOutput,\n  InsertMutationFnParams,\n  PendingMutation,\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 T - The type of items in the collection\n * @template TSchema - The schema type for validation\n * @template TKey - The type of the key returned by `getKey`\n */\nexport interface LocalStorageCollectionConfig<\n  T extends object = object,\n  TSchema extends StandardSchemaV1 = never,\n  TKey extends string | number = string | number,\n> extends BaseCollectionConfig<T, TKey, TSchema> {\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/**\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   * Accepts mutations from a transaction that belong to this collection and persists them to localStorage.\n   * This should be called in your transaction's mutationFn to persist local-storage data.\n   *\n   * @param transaction - The transaction containing mutations to accept\n   * @example\n   * const localSettings = createCollection(localStorageCollectionOptions({...}))\n   *\n   * const tx = createTransaction({\n   *   mutationFn: async ({ transaction }) => {\n   *     // Make API call first\n   *     await api.save(...)\n   *     // Then persist local-storage mutations after success\n   *     localSettings.utils.acceptMutations(transaction)\n   *   }\n   * })\n   */\n  acceptMutations: (transaction: {\n    mutations: Array<PendingMutation<Record<string, unknown>>>\n  }) => void\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 SerializationError(\n      operation,\n      error instanceof Error ? error.message : String(error)\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 * **Using with Manual Transactions:**\n *\n * For manual transactions, you must call `utils.acceptMutations()` in your transaction's `mutationFn`\n * to persist changes made during `tx.mutate()`. This is necessary because local-storage collections\n * don't participate in the standard mutation handler flow for manual transactions.\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, getStorageSize, and acceptMutations\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 *\n * @example\n * // Using with manual transactions\n * const localSettings = createCollection(\n *   localStorageCollectionOptions({\n *     storageKey: 'user-settings',\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * const tx = createTransaction({\n *   mutationFn: async ({ transaction }) => {\n *     // Use settings data in API call\n *     const settingsMutations = transaction.mutations.filter(m => m.collection === localSettings)\n *     await api.updateUserProfile({ settings: settingsMutations[0]?.modified })\n *\n *     // Persist local-storage mutations after API success\n *     localSettings.utils.acceptMutations(transaction)\n *   }\n * })\n *\n * tx.mutate(() => {\n *   localSettings.insert({ id: 'theme', value: 'dark' })\n *   apiCollection.insert({ id: 2, data: 'profile data' })\n * })\n *\n * await tx.commit()\n */\n\n// Overload for when schema is provided\nexport function localStorageCollectionOptions<\n  T extends StandardSchemaV1,\n  TKey extends string | number = string | number,\n>(\n  config: LocalStorageCollectionConfig<InferSchemaOutput<T>, T, TKey> & {\n    schema: T\n  }\n): CollectionConfig<InferSchemaOutput<T>, TKey, T> & {\n  id: string\n  utils: LocalStorageCollectionUtils\n  schema: T\n}\n\n// Overload for when no schema is provided\n// the type T needs to be passed explicitly unless it can be inferred from the getKey function in the config\nexport function localStorageCollectionOptions<\n  T extends object,\n  TKey extends string | number = string | number,\n>(\n  config: LocalStorageCollectionConfig<T, never, TKey> & {\n    schema?: never // prohibit schema\n  }\n): CollectionConfig<T, TKey> & {\n  id: string\n  utils: LocalStorageCollectionUtils\n  schema?: never // no schema in the result\n}\n\nexport function localStorageCollectionOptions(\n  config: LocalStorageCollectionConfig<any, any, string | number>\n): Omit<CollectionConfig<any, string | number, any>, `id`> & {\n  id: string\n  utils: LocalStorageCollectionUtils\n  schema?: StandardSchemaV1\n} {\n  // Validate required parameters\n  if (!config.storageKey) {\n    throw new StorageKeyRequiredError()\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 NoStorageAvailableError()\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 NoStorageEventApiError()\n  }\n\n  // Track the last known state to detect changes\n  const lastKnownData = new Map<string | number, StoredItem<any>>()\n\n  // Create the sync configuration\n  const sync = createLocalStorageSync<any>(\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<any>>\n  ): void => {\n    try {\n      // Convert Map to object format for storage\n      const objectData: Record<string, StoredItem<any>> = {}\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 (params: InsertMutationFnParams<any>) => {\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<any>(config.storageKey, storage)\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<any> = {\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 (params: UpdateMutationFnParams<any>) => {\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<any>(config.storageKey, storage)\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<any> = {\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 (params: DeleteMutationFnParams<any>) => {\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<any>(config.storageKey, storage)\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  /**\n   * Accepts mutations from a transaction that belong to this collection and persists them to storage\n   */\n  const acceptMutations = (transaction: {\n    mutations: Array<PendingMutation<Record<string, unknown>>>\n  }) => {\n    // Filter mutations that belong to this collection\n    // Use collection ID for filtering if collection reference isn't available yet\n    const collectionMutations = transaction.mutations.filter((m) => {\n      // Try to match by collection reference first\n      if (sync.collection && m.collection === sync.collection) {\n        return true\n      }\n      // Fall back to matching by collection ID\n      return m.collection.id === collectionId\n    })\n\n    if (collectionMutations.length === 0) {\n      return\n    }\n\n    // Validate all mutations can be serialized before modifying storage\n    for (const mutation of collectionMutations) {\n      switch (mutation.type) {\n        case `insert`:\n        case `update`:\n          validateJsonSerializable(mutation.modified, mutation.type)\n          break\n        case `delete`:\n          validateJsonSerializable(mutation.original, mutation.type)\n          break\n      }\n    }\n\n    // Load current data from storage\n    const currentData = loadFromStorage<Record<string, unknown>>(\n      config.storageKey,\n      storage\n    )\n\n    // Apply each mutation\n    for (const mutation of collectionMutations) {\n      // Use the engine's pre-computed key to avoid key derivation issues\n      const key = mutation.key\n\n      switch (mutation.type) {\n        case `insert`:\n        case `update`: {\n          const storedItem: StoredItem<Record<string, unknown>> = {\n            versionKey: generateUuid(),\n            data: mutation.modified,\n          }\n          currentData.set(key, storedItem)\n          break\n        }\n        case `delete`: {\n          currentData.delete(key)\n          break\n        }\n      }\n    }\n\n    // Save to storage\n    saveToStorage(currentData)\n\n    // Confirm the mutations in the collection to move them from optimistic to synced state\n    // This writes them through the sync interface to make them \"synced\" instead of \"optimistic\"\n    sync.confirmOperationsSync(collectionMutations)\n  }\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      acceptMutations,\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 InvalidStorageDataFormatError(storageKey, key)\n        }\n      })\n    } else {\n      throw new InvalidStorageObjectFormatError(storageKey)\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> & {\n  manualTrigger?: () => void\n  collection: any\n  confirmOperationsSync: (mutations: Array<any>) => void\n} {\n  let syncParams: Parameters<SyncConfig<T>[`sync`]>[0] | null = null\n  let collection: any = 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> & {\n    manualTrigger?: () => void\n    collection: any\n  } = {\n    sync: (params: Parameters<SyncConfig<T>[`sync`]>[0]) => {\n      const { begin, write, commit, markReady } = params\n\n      // Store sync params and collection for later use\n      syncParams = params\n      collection = params.collection\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      // Mark collection as ready after initial load\n      markReady()\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    // Collection instance reference\n    collection,\n  }\n\n  /**\n   * Confirms mutations by writing them through the sync interface\n   * This moves mutations from optimistic to synced state\n   * @param mutations - Array of mutation objects to confirm\n   */\n  const confirmOperationsSync = (mutations: Array<any>) => {\n    if (!syncParams) {\n      // Sync not initialized yet, mutations will be handled on next sync\n      return\n    }\n\n    const { begin, write, commit } = syncParams\n\n    // Write the mutations through sync to confirm them\n    begin()\n    mutations.forEach((mutation: any) => {\n      write({\n        type: mutation.type,\n        value:\n          mutation.type === `delete` ? mutation.original : mutation.modified,\n      })\n    })\n    commit()\n  }\n\n  return {\n    ...syncConfig,\n    confirmOperationsSync,\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"local-storage.js","sources":["../../src/local-storage.ts"],"sourcesContent":["import {\n  InvalidStorageDataFormatError,\n  InvalidStorageObjectFormatError,\n  SerializationError,\n  StorageKeyRequiredError,\n} from \"./errors\"\nimport type {\n  BaseCollectionConfig,\n  CollectionConfig,\n  DeleteMutationFnParams,\n  InferSchemaOutput,\n  InsertMutationFnParams,\n  PendingMutation,\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 T - The type of items in the collection\n * @template TSchema - The schema type for validation\n * @template TKey - The type of the key returned by `getKey`\n */\nexport interface LocalStorageCollectionConfig<\n  T extends object = object,\n  TSchema extends StandardSchemaV1 = never,\n  TKey extends string | number = string | number,\n> extends BaseCollectionConfig<T, TKey, TSchema> {\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/**\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   * Accepts mutations from a transaction that belong to this collection and persists them to localStorage.\n   * This should be called in your transaction's mutationFn to persist local-storage data.\n   *\n   * @param transaction - The transaction containing mutations to accept\n   * @example\n   * const localSettings = createCollection(localStorageCollectionOptions({...}))\n   *\n   * const tx = createTransaction({\n   *   mutationFn: async ({ transaction }) => {\n   *     // Make API call first\n   *     await api.save(...)\n   *     // Then persist local-storage mutations after success\n   *     localSettings.utils.acceptMutations(transaction)\n   *   }\n   * })\n   */\n  acceptMutations: (transaction: {\n    mutations: Array<PendingMutation<Record<string, unknown>>>\n  }) => void\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 SerializationError(\n      operation,\n      error instanceof Error ? error.message : String(error)\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 an in-memory storage implementation that mimics the StorageApi interface\n * Used as a fallback when localStorage is not available (e.g., server-side rendering)\n * @returns An object implementing the StorageApi interface using an in-memory Map\n */\nfunction createInMemoryStorage(): StorageApi {\n  const storage = new Map<string, string>()\n\n  return {\n    getItem(key: string): string | null {\n      return storage.get(key) ?? null\n    },\n    setItem(key: string, value: string): void {\n      storage.set(key, value)\n    },\n    removeItem(key: string): void {\n      storage.delete(key)\n    },\n  }\n}\n\n/**\n * Creates a no-op storage event API for environments without window (e.g., server-side)\n * This provides the required interface but doesn't actually listen to any events\n * since cross-tab synchronization is not possible in server environments\n * @returns An object implementing the StorageEventApi interface with no-op methods\n */\nfunction createNoOpStorageEventApi(): StorageEventApi {\n  return {\n    addEventListener: () => {\n      // No-op: cannot listen to storage events without window\n    },\n    removeEventListener: () => {\n      // No-op: cannot remove listeners without window\n    },\n  }\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 * **Fallback Behavior:**\n *\n * When localStorage is not available (e.g., in server-side rendering environments),\n * this function automatically falls back to an in-memory storage implementation.\n * This prevents errors during module initialization and allows the collection to\n * work in any environment, though data will not persist across page reloads or\n * be shared across tabs when using the in-memory fallback.\n *\n * **Using with Manual Transactions:**\n *\n * For manual transactions, you must call `utils.acceptMutations()` in your transaction's `mutationFn`\n * to persist changes made during `tx.mutate()`. This is necessary because local-storage collections\n * don't participate in the standard mutation handler flow for manual transactions.\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, getStorageSize, and acceptMutations\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 *\n * @example\n * // Using with manual transactions\n * const localSettings = createCollection(\n *   localStorageCollectionOptions({\n *     storageKey: 'user-settings',\n *     getKey: (item) => item.id,\n *   })\n * )\n *\n * const tx = createTransaction({\n *   mutationFn: async ({ transaction }) => {\n *     // Use settings data in API call\n *     const settingsMutations = transaction.mutations.filter(m => m.collection === localSettings)\n *     await api.updateUserProfile({ settings: settingsMutations[0]?.modified })\n *\n *     // Persist local-storage mutations after API success\n *     localSettings.utils.acceptMutations(transaction)\n *   }\n * })\n *\n * tx.mutate(() => {\n *   localSettings.insert({ id: 'theme', value: 'dark' })\n *   apiCollection.insert({ id: 2, data: 'profile data' })\n * })\n *\n * await tx.commit()\n */\n\n// Overload for when schema is provided\nexport function localStorageCollectionOptions<\n  T extends StandardSchemaV1,\n  TKey extends string | number = string | number,\n>(\n  config: LocalStorageCollectionConfig<InferSchemaOutput<T>, T, TKey> & {\n    schema: T\n  }\n): CollectionConfig<InferSchemaOutput<T>, TKey, T> & {\n  id: string\n  utils: LocalStorageCollectionUtils\n  schema: T\n}\n\n// Overload for when no schema is provided\n// the type T needs to be passed explicitly unless it can be inferred from the getKey function in the config\nexport function localStorageCollectionOptions<\n  T extends object,\n  TKey extends string | number = string | number,\n>(\n  config: LocalStorageCollectionConfig<T, never, TKey> & {\n    schema?: never // prohibit schema\n  }\n): CollectionConfig<T, TKey> & {\n  id: string\n  utils: LocalStorageCollectionUtils\n  schema?: never // no schema in the result\n}\n\nexport function localStorageCollectionOptions(\n  config: LocalStorageCollectionConfig<any, any, string | number>\n): Omit<CollectionConfig<any, string | number, any>, `id`> & {\n  id: string\n  utils: LocalStorageCollectionUtils\n  schema?: StandardSchemaV1\n} {\n  // Validate required parameters\n  if (!config.storageKey) {\n    throw new StorageKeyRequiredError()\n  }\n\n  // Default to window.localStorage if no storage is provided\n  // Fall back to in-memory storage if localStorage is not available (e.g., server-side rendering)\n  const storage =\n    config.storage ||\n    (typeof window !== `undefined` ? window.localStorage : null) ||\n    createInMemoryStorage()\n\n  // Default to window for storage events if not provided\n  // Fall back to no-op storage event API if window is not available (e.g., server-side rendering)\n  const storageEventApi =\n    config.storageEventApi ||\n    (typeof window !== `undefined` ? window : null) ||\n    createNoOpStorageEventApi()\n\n  // Track the last known state to detect changes\n  const lastKnownData = new Map<string | number, StoredItem<any>>()\n\n  // Create the sync configuration\n  const sync = createLocalStorageSync<any>(\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<any>>\n  ): void => {\n    try {\n      // Convert Map to object format for storage\n      const objectData: Record<string, StoredItem<any>> = {}\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 (params: InsertMutationFnParams<any>) => {\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<any>(config.storageKey, storage)\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<any> = {\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 (params: UpdateMutationFnParams<any>) => {\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<any>(config.storageKey, storage)\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<any> = {\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 (params: DeleteMutationFnParams<any>) => {\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<any>(config.storageKey, storage)\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  /**\n   * Accepts mutations from a transaction that belong to this collection and persists them to storage\n   */\n  const acceptMutations = (transaction: {\n    mutations: Array<PendingMutation<Record<string, unknown>>>\n  }) => {\n    // Filter mutations that belong to this collection\n    // Use collection ID for filtering if collection reference isn't available yet\n    const collectionMutations = transaction.mutations.filter((m) => {\n      // Try to match by collection reference first\n      if (sync.collection && m.collection === sync.collection) {\n        return true\n      }\n      // Fall back to matching by collection ID\n      return m.collection.id === collectionId\n    })\n\n    if (collectionMutations.length === 0) {\n      return\n    }\n\n    // Validate all mutations can be serialized before modifying storage\n    for (const mutation of collectionMutations) {\n      switch (mutation.type) {\n        case `insert`:\n        case `update`:\n          validateJsonSerializable(mutation.modified, mutation.type)\n          break\n        case `delete`:\n          validateJsonSerializable(mutation.original, mutation.type)\n          break\n      }\n    }\n\n    // Load current data from storage\n    const currentData = loadFromStorage<Record<string, unknown>>(\n      config.storageKey,\n      storage\n    )\n\n    // Apply each mutation\n    for (const mutation of collectionMutations) {\n      // Use the engine's pre-computed key to avoid key derivation issues\n      const key = mutation.key\n\n      switch (mutation.type) {\n        case `insert`:\n        case `update`: {\n          const storedItem: StoredItem<Record<string, unknown>> = {\n            versionKey: generateUuid(),\n            data: mutation.modified,\n          }\n          currentData.set(key, storedItem)\n          break\n        }\n        case `delete`: {\n          currentData.delete(key)\n          break\n        }\n      }\n    }\n\n    // Save to storage\n    saveToStorage(currentData)\n\n    // Confirm the mutations in the collection to move them from optimistic to synced state\n    // This writes them through the sync interface to make them \"synced\" instead of \"optimistic\"\n    sync.confirmOperationsSync(collectionMutations)\n  }\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      acceptMutations,\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 InvalidStorageDataFormatError(storageKey, key)\n        }\n      })\n    } else {\n      throw new InvalidStorageObjectFormatError(storageKey)\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> & {\n  manualTrigger?: () => void\n  collection: any\n  confirmOperationsSync: (mutations: Array<any>) => void\n} {\n  let syncParams: Parameters<SyncConfig<T>[`sync`]>[0] | null = null\n  let collection: any = 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> & {\n    manualTrigger?: () => void\n    collection: any\n  } = {\n    sync: (params: Parameters<SyncConfig<T>[`sync`]>[0]) => {\n      const { begin, write, commit, markReady } = params\n\n      // Store sync params and collection for later use\n      syncParams = params\n      collection = params.collection\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      // Mark collection as ready after initial load\n      markReady()\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    // Collection instance reference\n    collection,\n  }\n\n  /**\n   * Confirms mutations by writing them through the sync interface\n   * This moves mutations from optimistic to synced state\n   * @param mutations - Array of mutation objects to confirm\n   */\n  const confirmOperationsSync = (mutations: Array<any>) => {\n    if (!syncParams) {\n      // Sync not initialized yet, mutations will be handled on next sync\n      return\n    }\n\n    const { begin, write, commit } = syncParams\n\n    // Write the mutations through sync to confirm them\n    begin()\n    mutations.forEach((mutation: any) => {\n      write({\n        type: mutation.type,\n        value:\n          mutation.type === `delete` ? mutation.original : mutation.modified,\n      })\n    })\n    commit()\n  }\n\n  return {\n    ...syncConfig,\n    confirmOperationsSync,\n  }\n}\n"],"names":[],"mappings":";AAuHA,SAAS,yBAAyB,OAAY,WAAyB;AACrE,MAAI;AACF,SAAK,UAAU,KAAK;AAAA,EACtB,SAAS,OAAO;AACd,UAAM,IAAI;AAAA,MACR;AAAA,MACA,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAAA,IAAA;AAAA,EAEzD;AACF;AAMA,SAAS,eAAuB;AAC9B,SAAO,OAAO,WAAA;AAChB;AAOA,SAAS,wBAAoC;AAC3C,QAAM,8BAAc,IAAA;AAEpB,SAAO;AAAA,IACL,QAAQ,KAA4B;AAClC,aAAO,QAAQ,IAAI,GAAG,KAAK;AAAA,IAC7B;AAAA,IACA,QAAQ,KAAa,OAAqB;AACxC,cAAQ,IAAI,KAAK,KAAK;AAAA,IACxB;AAAA,IACA,WAAW,KAAmB;AAC5B,cAAQ,OAAO,GAAG;AAAA,IACpB;AAAA,EAAA;AAEJ;AAQA,SAAS,4BAA6C;AACpD,SAAO;AAAA,IACL,kBAAkB,MAAM;AAAA,IAExB;AAAA,IACA,qBAAqB,MAAM;AAAA,IAE3B;AAAA,EAAA;AAEJ;AAoHO,SAAS,8BACd,QAKA;AAEA,MAAI,CAAC,OAAO,YAAY;AACtB,UAAM,IAAI,wBAAA;AAAA,EACZ;AAIA,QAAM,UACJ,OAAO,YACN,OAAO,WAAW,cAAc,OAAO,eAAe,SACvD,sBAAA;AAIF,QAAM,kBACJ,OAAO,oBACN,OAAO,WAAW,cAAc,SAAS,SAC1C,0BAAA;AAGF,QAAM,oCAAoB,IAAA;AAG1B,QAAM,OAAO;AAAA,IACX,OAAO;AAAA,IACP;AAAA,IACA;AAAA,IACA,OAAO;AAAA,IACP;AAAA,EAAA;AAOF,QAAM,mBAAmB,MAAM;AAC7B,QAAI,KAAK,eAAe;AACtB,WAAK,cAAA;AAAA,IACP;AAAA,EACF;AAMA,QAAM,gBAAgB,CACpB,YACS;AACT,QAAI;AAEF,YAAM,aAA8C,CAAA;AACpD,cAAQ,QAAQ,CAAC,YAAY,QAAQ;AACnC,mBAAW,OAAO,GAAG,CAAC,IAAI;AAAA,MAC5B,CAAC;AACD,YAAM,aAAa,KAAK,UAAU,UAAU;AAC5C,cAAQ,QAAQ,OAAO,YAAY,UAAU;AAAA,IAC/C,SAAS,OAAO;AACd,cAAQ;AAAA,QACN,8DAA8D,OAAO,UAAU;AAAA,QAC/E;AAAA,MAAA;AAEF,YAAM;AAAA,IACR;AAAA,EACF;AAKA,QAAM,eAA+B,MAAY;AAC/C,YAAQ,WAAW,OAAO,UAAU;AAAA,EACtC;AAMA,QAAM,iBAAmC,MAAc;AACrD,UAAM,OAAO,QAAQ,QAAQ,OAAO,UAAU;AAC9C,WAAO,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO;AAAA,EACxC;AAMA,QAAM,kBAAkB,OAAO,WAAwC;AAErE,WAAO,YAAY,UAAU,QAAQ,CAAC,aAAa;AACjD,+BAAyB,SAAS,UAAU,QAAQ;AAAA,IACtD,CAAC;AAGD,QAAI,gBAAqB,CAAA;AACzB,QAAI,OAAO,UAAU;AACnB,sBAAiB,MAAM,OAAO,SAAS,MAAM,KAAM,CAAA;AAAA,IACrD;AAIA,UAAM,cAAc,gBAAqB,OAAO,YAAY,OAAO;AAGnE,WAAO,YAAY,UAAU,QAAQ,CAAC,aAAa;AACjD,YAAM,MAAM,OAAO,OAAO,SAAS,QAAQ;AAC3C,YAAM,aAA8B;AAAA,QAClC,YAAY,aAAA;AAAA,QACZ,MAAM,SAAS;AAAA,MAAA;AAEjB,kBAAY,IAAI,KAAK,UAAU;AAAA,IACjC,CAAC;AAGD,kBAAc,WAAW;AAGzB,qBAAA;AAEA,WAAO;AAAA,EACT;AAEA,QAAM,kBAAkB,OAAO,WAAwC;AAErE,WAAO,YAAY,UAAU,QAAQ,CAAC,aAAa;AACjD,+BAAyB,SAAS,UAAU,QAAQ;AAAA,IACtD,CAAC;AAGD,QAAI,gBAAqB,CAAA;AACzB,QAAI,OAAO,UAAU;AACnB,sBAAiB,MAAM,OAAO,SAAS,MAAM,KAAM,CAAA;AAAA,IACrD;AAIA,UAAM,cAAc,gBAAqB,OAAO,YAAY,OAAO;AAGnE,WAAO,YAAY,UAAU,QAAQ,CAAC,aAAa;AACjD,YAAM,MAAM,OAAO,OAAO,SAAS,QAAQ;AAC3C,YAAM,aAA8B;AAAA,QAClC,YAAY,aAAA;AAAA,QACZ,MAAM,SAAS;AAAA,MAAA;AAEjB,kBAAY,IAAI,KAAK,UAAU;AAAA,IACjC,CAAC;AAGD,kBAAc,WAAW;AAGzB,qBAAA;AAEA,WAAO;AAAA,EACT;AAEA,QAAM,kBAAkB,OAAO,WAAwC;AAErE,QAAI,gBAAqB,CAAA;AACzB,QAAI,OAAO,UAAU;AACnB,sBAAiB,MAAM,OAAO,SAAS,MAAM,KAAM,CAAA;AAAA,IACrD;AAIA,UAAM,cAAc,gBAAqB,OAAO,YAAY,OAAO;AAGnE,WAAO,YAAY,UAAU,QAAQ,CAAC,aAAa;AAEjD,YAAM,MAAM,OAAO,OAAO,SAAS,QAAQ;AAC3C,kBAAY,OAAO,GAAG;AAAA,IACxB,CAAC;AAGD,kBAAc,WAAW;AAGzB,qBAAA;AAEA,WAAO;AAAA,EACT;AAGA,QAAM;AAAA,IACJ,YAAY;AAAA,IACZ,SAAS;AAAA,IACT,iBAAiB;AAAA,IACjB,UAAU;AAAA,IACV,UAAU;AAAA,IACV,UAAU;AAAA,IACV;AAAA,IACA,GAAG;AAAA,EAAA,IACD;AAGJ,QAAM,eAAe,MAAM,oBAAoB,OAAO,UAAU;AAKhE,QAAM,kBAAkB,CAAC,gBAEnB;AAGJ,UAAM,sBAAsB,YAAY,UAAU,OAAO,CAAC,MAAM;AAE9D,UAAI,KAAK,cAAc,EAAE,eAAe,KAAK,YAAY;AACvD,eAAO;AAAA,MACT;AAEA,aAAO,EAAE,WAAW,OAAO;AAAA,IAC7B,CAAC;AAED,QAAI,oBAAoB,WAAW,GAAG;AACpC;AAAA,IACF;AAGA,eAAW,YAAY,qBAAqB;AAC1C,cAAQ,SAAS,MAAA;AAAA,QACf,KAAK;AAAA,QACL,KAAK;AACH,mCAAyB,SAAS,UAAU,SAAS,IAAI;AACzD;AAAA,QACF,KAAK;AACH,mCAAyB,SAAS,UAAU,SAAS,IAAI;AACzD;AAAA,MAAA;AAAA,IAEN;AAGA,UAAM,cAAc;AAAA,MAClB,OAAO;AAAA,MACP;AAAA,IAAA;AAIF,eAAW,YAAY,qBAAqB;AAE1C,YAAM,MAAM,SAAS;AAErB,cAAQ,SAAS,MAAA;AAAA,QACf,KAAK;AAAA,QACL,KAAK,UAAU;AACb,gBAAM,aAAkD;AAAA,YACtD,YAAY,aAAA;AAAA,YACZ,MAAM,SAAS;AAAA,UAAA;AAEjB,sBAAY,IAAI,KAAK,UAAU;AAC/B;AAAA,QACF;AAAA,QACA,KAAK,UAAU;AACb,sBAAY,OAAO,GAAG;AACtB;AAAA,QACF;AAAA,MAAA;AAAA,IAEJ;AAGA,kBAAc,WAAW;AAIzB,SAAK,sBAAsB,mBAAmB;AAAA,EAChD;AAEA,SAAO;AAAA,IACL,GAAG;AAAA,IACH,IAAI;AAAA,IACJ;AAAA,IACA,UAAU;AAAA,IACV,UAAU;AAAA,IACV,UAAU;AAAA,IACV,OAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA;AAAA,IAAA;AAAA,EACF;AAEJ;AAQA,SAAS,gBACP,YACA,SACqC;AACrC,MAAI;AACF,UAAM,UAAU,QAAQ,QAAQ,UAAU;AAC1C,QAAI,CAAC,SAAS;AACZ,iCAAW,IAAA;AAAA,IACb;AAEA,UAAM,SAAS,KAAK,MAAM,OAAO;AACjC,UAAM,8BAAc,IAAA;AAGpB,QACE,OAAO,WAAW,YAClB,WAAW,QACX,CAAC,MAAM,QAAQ,MAAM,GACrB;AACA,aAAO,QAAQ,MAAM,EAAE,QAAQ,CAAC,CAAC,KAAK,KAAK,MAAM;AAE/C,YACE,SACA,OAAO,UAAU,YACjB,gBAAgB,SAChB,UAAU,OACV;AACA,gBAAM,aAAa;AACnB,kBAAQ,IAAI,KAAK,UAAU;AAAA,QAC7B,OAAO;AACL,gBAAM,IAAI,8BAA8B,YAAY,GAAG;AAAA,QACzD;AAAA,MACF,CAAC;AAAA,IACH,OAAO;AACL,YAAM,IAAI,gCAAgC,UAAU;AAAA,IACtD;AAEA,WAAO;AAAA,EACT,SAAS,OAAO;AACd,YAAQ;AAAA,MACN,iEAAiE,UAAU;AAAA,MAC3E;AAAA,IAAA;AAEF,+BAAW,IAAA;AAAA,EACb;AACF;AAYA,SAAS,uBACP,YACA,SACA,iBACA,SACA,eAKA;AACA,MAAI,aAA0D;AAC9D,MAAI,aAAkB;AAQtB,QAAM,cAAc,CAClB,SACA,YAKI;AACJ,UAAM,UAID,CAAA;AAGL,YAAQ,QAAQ,CAAC,eAAe,QAAQ;AACtC,YAAM,gBAAgB,QAAQ,IAAI,GAAG;AACrC,UAAI,CAAC,eAAe;AAClB,gBAAQ,KAAK,EAAE,MAAM,UAAU,KAAK,OAAO,cAAc,MAAM;AAAA,MACjE,WAAW,cAAc,eAAe,cAAc,YAAY;AAChE,gBAAQ,KAAK,EAAE,MAAM,UAAU,KAAK,OAAO,cAAc,MAAM;AAAA,MACjE;AAAA,IACF,CAAC;AAGD,YAAQ,QAAQ,CAAC,eAAe,QAAQ;AACtC,UAAI,CAAC,QAAQ,IAAI,GAAG,GAAG;AACrB,gBAAQ,KAAK,EAAE,MAAM,UAAU,KAAK,OAAO,cAAc,MAAM;AAAA,MACjE;AAAA,IACF,CAAC;AAED,WAAO;AAAA,EACT;AAMA,QAAM,wBAAwB,MAAM;AAClC,QAAI,CAAC,WAAY;AAEjB,UAAM,EAAE,OAAO,OAAO,OAAA,IAAW;AAGjC,UAAM,UAAU,gBAAmB,YAAY,OAAO;AAGtD,UAAM,UAAU,YAAY,eAAe,OAAO;AAElD,QAAI,QAAQ,SAAS,GAAG;AACtB,YAAA;AACA,cAAQ,QAAQ,CAAC,EAAE,MAAM,YAAY;AACnC,YAAI,OAAO;AACT,mCAAyB,OAAO,IAAI;AACpC,gBAAM,EAAE,MAAM,OAAO;AAAA,QACvB;AAAA,MACF,CAAC;AACD,aAAA;AAGA,oBAAc,MAAA;AACd,cAAQ,QAAQ,CAAC,YAAY,QAAQ;AACnC,sBAAc,IAAI,KAAK,UAAU;AAAA,MACnC,CAAC;AAAA,IACH;AAAA,EACF;AAEA,QAAM,aAGF;AAAA,IACF,MAAM,CAAC,WAAiD;AACtD,YAAM,EAAE,OAAO,OAAO,QAAQ,cAAc;AAG5C,mBAAa;AACb,mBAAa,OAAO;AAGpB,YAAM,cAAc,gBAAmB,YAAY,OAAO;AAC1D,UAAI,YAAY,OAAO,GAAG;AACxB,cAAA;AACA,oBAAY,QAAQ,CAAC,eAAe;AAClC,mCAAyB,WAAW,MAAM,MAAM;AAChD,gBAAM,EAAE,MAAM,UAAU,OAAO,WAAW,MAAM;AAAA,QAClD,CAAC;AACD,eAAA;AAAA,MACF;AAGA,oBAAc,MAAA;AACd,kBAAY,QAAQ,CAAC,YAAY,QAAQ;AACvC,sBAAc,IAAI,KAAK,UAAU;AAAA,MACnC,CAAC;AAGD,gBAAA;AAGA,YAAM,qBAAqB,CAAC,UAAwB;AAElD,YAAI,MAAM,QAAQ,cAAc,MAAM,gBAAgB,SAAS;AAC7D;AAAA,QACF;AAEA,8BAAA;AAAA,MACF;AAGA,sBAAgB,iBAAiB,WAAW,kBAAkB;AAAA,IAGhE;AAAA;AAAA;AAAA;AAAA;AAAA,IAMA,iBAAiB,OAAO;AAAA,MACtB;AAAA,MACA,aACE,aAAa,OAAO,WAAW,cAAc,OAAO,eAAe,QAC/D,iBACA;AAAA,IAAA;AAAA;AAAA,IAIR,eAAe;AAAA;AAAA,IAGf;AAAA,EAAA;AAQF,QAAM,wBAAwB,CAAC,cAA0B;AACvD,QAAI,CAAC,YAAY;AAEf;AAAA,IACF;AAEA,UAAM,EAAE,OAAO,OAAO,OAAA,IAAW;AAGjC,UAAA;AACA,cAAU,QAAQ,CAAC,aAAkB;AACnC,YAAM;AAAA,QACJ,MAAM,SAAS;AAAA,QACf,OACE,SAAS,SAAS,WAAW,SAAS,WAAW,SAAS;AAAA,MAAA,CAC7D;AAAA,IACH,CAAC;AACD,WAAA;AAAA,EACF;AAEA,SAAO;AAAA,IACL,GAAG;AAAA,IACH;AAAA,EAAA;AAEJ;"}

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@tanstack/db",
   "description": "A reactive client store for building super fast apps on sync",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "dependencies": {
     "@standard-schema/spec": "^1.0.0",
-    "@tanstack/db-ivm": "0.1.11"
+    "@tanstack/db-ivm": "0.1.12"
   },
   "devDependencies": {
     "@vitest/coverage-istanbul": "^3.2.4",
-    "arktype": "^2.1.22",
+    "arktype": "^2.1.23",
     "temporal-polyfill": "^0.3.0"
   },
   "exports": {

package/src/collection/change-events.ts

@@ -3,15 +3,20 @@ import {
   toExpression,
 } from "../query/builder/ref-proxy"
 import { compileSingleRowExpression } from "../query/compiler/evaluators.js"
-import { optimizeExpressionWithIndexes } from "../utils/index-optimization.js"
+import {
+  findIndexForField,
+  optimizeExpressionWithIndexes,
+} from "../utils/index-optimization.js"
+import { ensureIndexForField } from "../indexes/auto-index.js"
+import { makeComparator } from "../utils/comparison.js"
 import type {
   ChangeMessage,
   CurrentStateAsChangesOptions,
   SubscribeChangesOptions,
 } from "../types"
-import type { Collection } from "./index.js"
+import type { Collection, CollectionImpl } from "./index.js"
 import type { SingleRowRefProxy } from "../query/builder/ref-proxy"
-import type { BasicExpression } from "../query/ir.js"
+import type { BasicExpression, OrderBy } from "../query/ir.js"
 
 /**
  * Interface for a collection-like object that provides the necessary methods
@@ -28,7 +33,7 @@ export interface CollectionLike<
 /**
  * Returns the current state of the collection as an array of changes
  * @param collection - The collection to get changes from
- * @param options - Options including optional where filter
+ * @param options - Options including optional where filter, orderBy, and limit
  * @returns An array of changes
  * @example
  * // Get all items as changes
@@ -41,7 +46,19 @@ export interface CollectionLike<
  *
  * // Get only items using a pre-compiled expression
  * const activeChanges = currentStateAsChanges(collection, {
- *   whereExpression: eq(row.status, 'active')
+ *   where: eq(row.status, 'active')
+ * })
+ *
+ * // Get items ordered by name with limit
+ * const topUsers = currentStateAsChanges(collection, {
+ *   orderBy: [{ expression: row.name, compareOptions: { direction: 'asc' } }],
+ *   limit: 10
+ * })
+ *
+ * // Get active users ordered by score (highest score first)
+ * const topActiveUsers = currentStateAsChanges(collection, {
+ *   where: eq(row.status, 'active'),
+ *   orderBy: [{ expression: row.score, compareOptions: { direction: 'desc' } }],
  * })
  */
 export function currentStateAsChanges<
@@ -69,9 +86,48 @@ export function currentStateAsChanges<
     return result
   }
 
-  // TODO: handle orderBy and limit options
-  //       by calling optimizeOrderedLimit
+  // Validate that limit without orderBy doesn't happen
+  if (options.limit !== undefined && !options.orderBy) {
+    throw new Error(`limit cannot be used without orderBy`)
+  }
+
+  // First check if orderBy is present (optionally with limit)
+  if (options.orderBy) {
+    // Create where filter function if present
+    const whereFilter = options.where
+      ? createFilterFunctionFromExpression(options.where)
+      : undefined
+
+    // Get ordered keys using index optimization when possible
+    const orderedKeys = getOrderedKeys(
+      collection,
+      options.orderBy,
+      options.limit,
+      whereFilter,
+      options.optimizedOnly
+    )
+
+    if (orderedKeys === undefined) {
+      // `getOrderedKeys` returned undefined because we asked for `optimizedOnly` and there was no index to use
+      return
+    }
+
+    // Convert keys to change messages
+    const result: Array<ChangeMessage<T>> = []
+    for (const key of orderedKeys) {
+      const value = collection.get(key)
+      if (value !== undefined) {
+        result.push({
+          type: `insert`,
+          key,
+          value,
+        })
+      }
+    }
+    return result
+  }
 
+  // If no orderBy OR orderBy optimization failed, use where clause optimization
   if (!options.where) {
     // No filtering, return all items
     return collectFilteredResults()
@@ -246,3 +302,121 @@ export function createFilteredCallback<T extends object>(
     }
   }
 }
+
+/**
+ * Gets ordered keys from a collection using index optimization when possible
+ * @param collection - The collection to get keys from
+ * @param orderBy - The order by clause
+ * @param limit - Optional limit on number of keys to return
+ * @param whereFilter - Optional filter function to apply while traversing
+ * @returns Array of keys in sorted order
+ */
+function getOrderedKeys<T extends object, TKey extends string | number>(
+  collection: CollectionLike<T, TKey>,
+  orderBy: OrderBy,
+  limit?: number,
+  whereFilter?: (item: T) => boolean,
+  optimizedOnly?: boolean
+): Array<TKey> | undefined {
+  // For single-column orderBy on a ref expression, try index optimization
+  if (orderBy.length === 1) {
+    const clause = orderBy[0]!
+    const orderByExpression = clause.expression
+
+    if (orderByExpression.type === `ref`) {
+      const propRef = orderByExpression
+      const fieldPath = propRef.path
+
+      // Ensure index exists for this field
+      ensureIndexForField(
+        fieldPath[0]!,
+        fieldPath,
+        collection as CollectionImpl<T, TKey>,
+        clause.compareOptions
+      )
+
+      // Find the index
+      const index = findIndexForField(
+        collection.indexes,
+        fieldPath,
+        clause.compareOptions
+      )
+
+      if (index && index.supports(`gt`)) {
+        // Use index optimization
+        const filterFn = (key: TKey): boolean => {
+          const value = collection.get(key)
+          if (value === undefined) {
+            return false
+          }
+          return whereFilter?.(value) ?? true
+        }
+
+        // Take the keys that match the filter and limit
+        // if no limit is provided `index.keyCount` is used,
+        // i.e. we will take all keys that match the filter
+        return index.take(limit ?? index.keyCount, undefined, filterFn)
+      }
+    }
+  }
+
+  if (optimizedOnly) {
+    return
+  }
+
+  // Fallback: collect all items and sort in memory
+  const allItems: Array<{ key: TKey; value: T }> = []
+  for (const [key, value] of collection.entries()) {
+    if (whereFilter?.(value) ?? true) {
+      allItems.push({ key, value })
+    }
+  }
+
+  // Sort using makeComparator
+  const compare = (a: { key: TKey; value: T }, b: { key: TKey; value: T }) => {
+    for (const clause of orderBy) {
+      const compareFn = makeComparator(clause.compareOptions)
+
+      // Extract values for comparison
+      const aValue = extractValueFromItem(a.value, clause.expression)
+      const bValue = extractValueFromItem(b.value, clause.expression)
+
+      const result = compareFn(aValue, bValue)
+      if (result !== 0) {
+        return result
+      }
+    }
+    return 0
+  }
+
+  allItems.sort(compare)
+  const sortedKeys = allItems.map((item) => item.key)
+
+  // Apply limit if provided
+  if (limit !== undefined) {
+    return sortedKeys.slice(0, limit)
+  }
+
+  // if no limit is provided, we will return all keys
+  return sortedKeys
+}
+
+/**
+ * Helper function to extract a value from an item based on an expression
+ */
+function extractValueFromItem(item: any, expression: BasicExpression): any {
+  if (expression.type === `ref`) {
+    const propRef = expression
+    let value = item
+    for (const pathPart of propRef.path) {
+      value = value?.[pathPart]
+    }
+    return value
+  } else if (expression.type === `val`) {
+    return expression.value
+  } else {
+    // It must be a function
+    const evaluator = compileSingleRowExpression(expression)
+    return evaluator(item as Record<string, unknown>)
+  }
+}

package/src/collection/state.ts

@@ -700,6 +700,7 @@ export class CollectionStateManager<
         if (transaction.state === `completed`) {
           for (const mutation of transaction.mutations) {
             if (
+              mutation.optimistic &&
               this.isThisCollection(mutation.collection) &&
               changedKeys.has(mutation.key)
             ) {

package/src/errors.ts

@@ -521,22 +521,6 @@ export class StorageKeyRequiredError extends LocalStorageCollectionError {
   }
 }
 
-export class NoStorageAvailableError extends LocalStorageCollectionError {
-  constructor() {
-    super(
-      `[LocalStorageCollection] No storage available. Please provide a storage option or ensure window.localStorage is available.`
-    )
-  }
-}
-
-export class NoStorageEventApiError extends LocalStorageCollectionError {
-  constructor() {
-    super(
-      `[LocalStorageCollection] No storage event API available. Please provide a storageEventApi option or ensure window is available.`
-    )
-  }
-}
-
 export class InvalidStorageDataFormatError extends LocalStorageCollectionError {
   constructor(storageKey: string, key: string) {
     super(

package/src/local-storage.ts

@@ -1,8 +1,6 @@
 import {
   InvalidStorageDataFormatError,
   InvalidStorageObjectFormatError,
-  NoStorageAvailableError,
-  NoStorageEventApiError,
   SerializationError,
   StorageKeyRequiredError,
 } from "./errors"
@@ -138,12 +136,58 @@ function generateUuid(): string {
   return crypto.randomUUID()
 }
 
+/**
+ * Creates an in-memory storage implementation that mimics the StorageApi interface
+ * Used as a fallback when localStorage is not available (e.g., server-side rendering)
+ * @returns An object implementing the StorageApi interface using an in-memory Map
+ */
+function createInMemoryStorage(): StorageApi {
+  const storage = new Map<string, string>()
+
+  return {
+    getItem(key: string): string | null {
+      return storage.get(key) ?? null
+    },
+    setItem(key: string, value: string): void {
+      storage.set(key, value)
+    },
+    removeItem(key: string): void {
+      storage.delete(key)
+    },
+  }
+}
+
+/**
+ * Creates a no-op storage event API for environments without window (e.g., server-side)
+ * This provides the required interface but doesn't actually listen to any events
+ * since cross-tab synchronization is not possible in server environments
+ * @returns An object implementing the StorageEventApi interface with no-op methods
+ */
+function createNoOpStorageEventApi(): StorageEventApi {
+  return {
+    addEventListener: () => {
+      // No-op: cannot listen to storage events without window
+    },
+    removeEventListener: () => {
+      // No-op: cannot remove listeners without window
+    },
+  }
+}
+
 /**
  * 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.
  *
+ * **Fallback Behavior:**
+ *
+ * When localStorage is not available (e.g., in server-side rendering environments),
+ * this function automatically falls back to an in-memory storage implementation.
+ * This prevents errors during module initialization and allows the collection to
+ * work in any environment, though data will not persist across page reloads or
+ * be shared across tabs when using the in-memory fallback.
+ *
  * **Using with Manual Transactions:**
  *
  * For manual transactions, you must call `utils.acceptMutations()` in your transaction's `mutationFn`
@@ -257,21 +301,18 @@ export function localStorageCollectionOptions(
   }
 
   // Default to window.localStorage if no storage is provided
+  // Fall back to in-memory storage if localStorage is not available (e.g., server-side rendering)
   const storage =
     config.storage ||
-    (typeof window !== `undefined` ? window.localStorage : null)
-
-  if (!storage) {
-    throw new NoStorageAvailableError()
-  }
+    (typeof window !== `undefined` ? window.localStorage : null) ||
+    createInMemoryStorage()
 
   // Default to window for storage events if not provided
+  // Fall back to no-op storage event API if window is not available (e.g., server-side rendering)
   const storageEventApi =
-    config.storageEventApi || (typeof window !== `undefined` ? window : null)
-
-  if (!storageEventApi) {
-    throw new NoStorageEventApiError()
-  }
+    config.storageEventApi ||
+    (typeof window !== `undefined` ? window : null) ||
+    createNoOpStorageEventApi()
 
   // Track the last known state to detect changes
   const lastKnownData = new Map<string | number, StoredItem<any>>()