@tanstack/db 0.4.20 → 0.5.0

package/dist/esm/collection/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/collection/index.ts"],"sourcesContent":["import {\n  CollectionRequiresConfigError,\n  CollectionRequiresSyncConfigError,\n} from \"../errors\"\nimport { currentStateAsChanges } from \"./change-events\"\n\nimport { CollectionStateManager } from \"./state\"\nimport { CollectionChangesManager } from \"./changes\"\nimport { CollectionLifecycleManager } from \"./lifecycle.js\"\nimport { CollectionSyncManager } from \"./sync\"\nimport { CollectionIndexesManager } from \"./indexes\"\nimport { CollectionMutationsManager } from \"./mutations\"\nimport { CollectionEventsManager } from \"./events.js\"\nimport type { CollectionSubscription } from \"./subscription\"\nimport type { AllCollectionEvents, CollectionEventHandler } from \"./events.js\"\nimport type { BaseIndex, IndexResolver } from \"../indexes/base-index.js\"\nimport type { IndexOptions } from \"../indexes/index-options.js\"\nimport type {\n  ChangeMessage,\n  CollectionConfig,\n  CollectionStatus,\n  CurrentStateAsChangesOptions,\n  Fn,\n  InferSchemaInput,\n  InferSchemaOutput,\n  InsertConfig,\n  NonSingleResult,\n  OperationConfig,\n  SingleResult,\n  SubscribeChangesOptions,\n  Transaction as TransactionType,\n  UtilsRecord,\n  WritableDeep,\n} from \"../types\"\nimport type { SingleRowRefProxy } from \"../query/builder/ref-proxy\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\nimport type { BTreeIndex } from \"../indexes/btree-index.js\"\nimport type { IndexProxy } from \"../indexes/lazy-index.js\"\n\n/**\n * Enhanced Collection interface that includes both data type T and utilities TUtils\n * @template T - The type of items in the collection\n * @template TKey - The type of the key for the collection\n * @template TUtils - The utilities record type\n * @template TInsertInput - The type for insert operations (can be different from T for schemas with defaults)\n */\nexport interface Collection<\n  T extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n  TUtils extends UtilsRecord = UtilsRecord,\n  TSchema extends StandardSchemaV1 = StandardSchemaV1,\n  TInsertInput extends object = T,\n> extends CollectionImpl<T, TKey, TUtils, TSchema, TInsertInput> {\n  readonly utils: TUtils\n  readonly singleResult?: true\n}\n\n/**\n * Creates a new Collection instance with the given configuration\n *\n * @template T - The schema type if a schema is provided, otherwise the type of items in the collection\n * @template TKey - The type of the key for the collection\n * @template TUtils - The utilities record type\n * @param options - Collection options with optional utilities\n * @returns A new Collection with utilities exposed both at top level and under .utils\n *\n * @example\n * // Pattern 1: With operation handlers (direct collection calls)\n * const todos = createCollection({\n *   id: \"todos\",\n *   getKey: (todo) => todo.id,\n *   schema,\n *   onInsert: async ({ transaction, collection }) => {\n *     // Send to API\n *     await api.createTodo(transaction.mutations[0].modified)\n *   },\n *   onUpdate: async ({ transaction, collection }) => {\n *     await api.updateTodo(transaction.mutations[0].modified)\n *   },\n *   onDelete: async ({ transaction, collection }) => {\n *     await api.deleteTodo(transaction.mutations[0].key)\n *   },\n *   sync: { sync: () => {} }\n * })\n *\n * // Direct usage (handlers manage transactions)\n * const tx = todos.insert({ id: \"1\", text: \"Buy milk\", completed: false })\n * await tx.isPersisted.promise\n *\n * @example\n * // Pattern 2: Manual transaction management\n * const todos = createCollection({\n *   getKey: (todo) => todo.id,\n *   schema: todoSchema,\n *   sync: { sync: () => {} }\n * })\n *\n * // Explicit transaction usage\n * const tx = createTransaction({\n *   mutationFn: async ({ transaction }) => {\n *     // Handle all mutations in transaction\n *     await api.saveChanges(transaction.mutations)\n *   }\n * })\n *\n * tx.mutate(() => {\n *   todos.insert({ id: \"1\", text: \"Buy milk\" })\n *   todos.update(\"2\", draft => { draft.completed = true })\n * })\n *\n * await tx.isPersisted.promise\n *\n * @example\n * // Using schema for type inference (preferred as it also gives you client side validation)\n * const todoSchema = z.object({\n *   id: z.string(),\n *   title: z.string(),\n *   completed: z.boolean()\n * })\n *\n * const todos = createCollection({\n *   schema: todoSchema,\n *   getKey: (todo) => todo.id,\n *   sync: { sync: () => {} }\n * })\n *\n */\n\n// Overload for when schema is provided\nexport function createCollection<\n  T extends StandardSchemaV1,\n  TKey extends string | number = string | number,\n  TUtils extends UtilsRecord = UtilsRecord,\n>(\n  options: CollectionConfig<InferSchemaOutput<T>, TKey, T> & {\n    schema: T\n    utils?: TUtils\n  } & NonSingleResult\n): Collection<InferSchemaOutput<T>, TKey, TUtils, T, InferSchemaInput<T>> &\n  NonSingleResult\n\n// Overload for when schema is provided and singleResult is true\nexport function createCollection<\n  T extends StandardSchemaV1,\n  TKey extends string | number = string | number,\n  TUtils extends UtilsRecord = UtilsRecord,\n>(\n  options: CollectionConfig<InferSchemaOutput<T>, TKey, T> & {\n    schema: T\n    utils?: TUtils\n  } & SingleResult\n): Collection<InferSchemaOutput<T>, TKey, TUtils, T, InferSchemaInput<T>> &\n  SingleResult\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 createCollection<\n  T extends object,\n  TKey extends string | number = string | number,\n  TUtils extends UtilsRecord = UtilsRecord,\n>(\n  options: CollectionConfig<T, TKey, never> & {\n    schema?: never // prohibit schema if an explicit type is provided\n    utils?: TUtils\n  } & NonSingleResult\n): Collection<T, TKey, TUtils, never, T> & NonSingleResult\n\n// Overload for when no schema is provided and singleResult is true\n// the type T needs to be passed explicitly unless it can be inferred from the getKey function in the config\nexport function createCollection<\n  T extends object,\n  TKey extends string | number = string | number,\n  TUtils extends UtilsRecord = UtilsRecord,\n>(\n  options: CollectionConfig<T, TKey, never> & {\n    schema?: never // prohibit schema if an explicit type is provided\n    utils?: TUtils\n  } & SingleResult\n): Collection<T, TKey, TUtils, never, T> & SingleResult\n\n// Implementation\nexport function createCollection(\n  options: CollectionConfig<any, string | number, any> & {\n    schema?: StandardSchemaV1\n    utils?: UtilsRecord\n  }\n): Collection<any, string | number, UtilsRecord, any, any> {\n  const collection = new CollectionImpl<any, string | number, any, any, any>(\n    options\n  )\n\n  // Attach utils to collection\n  if (options.utils) {\n    collection.utils = options.utils\n  } else {\n    collection.utils = {}\n  }\n\n  return collection\n}\n\nexport class CollectionImpl<\n  TOutput extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n  TUtils extends UtilsRecord = {},\n  TSchema extends StandardSchemaV1 = StandardSchemaV1,\n  TInput extends object = TOutput,\n> {\n  public id: string\n  public config: CollectionConfig<TOutput, TKey, TSchema>\n\n  // Utilities namespace\n  // This is populated by createCollection\n  public utils: Record<string, Fn> = {}\n\n  // Managers\n  private _events: CollectionEventsManager\n  private _changes: CollectionChangesManager<TOutput, TKey, TSchema, TInput>\n  public _lifecycle: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>\n  public _sync: CollectionSyncManager<TOutput, TKey, TSchema, TInput>\n  private _indexes: CollectionIndexesManager<TOutput, TKey, TSchema, TInput>\n  private _mutations: CollectionMutationsManager<\n    TOutput,\n    TKey,\n    TUtils,\n    TSchema,\n    TInput\n  >\n  // The core state of the collection is \"public\" so that is accessible in tests\n  // and for debugging\n  public _state: CollectionStateManager<TOutput, TKey, TSchema, TInput>\n\n  /**\n   * Creates a new Collection instance\n   *\n   * @param config - Configuration object for the collection\n   * @throws Error if sync config is missing\n   */\n  constructor(config: CollectionConfig<TOutput, TKey, TSchema>) {\n    // eslint-disable-next-line\n    if (!config) {\n      throw new CollectionRequiresConfigError()\n    }\n\n    // eslint-disable-next-line\n    if (!config.sync) {\n      throw new CollectionRequiresSyncConfigError()\n    }\n\n    if (config.id) {\n      this.id = config.id\n    } else {\n      this.id = crypto.randomUUID()\n    }\n\n    // Set default values for optional config properties\n    this.config = {\n      ...config,\n      autoIndex: config.autoIndex ?? `eager`,\n    }\n\n    this._changes = new CollectionChangesManager()\n    this._events = new CollectionEventsManager()\n    this._indexes = new CollectionIndexesManager()\n    this._lifecycle = new CollectionLifecycleManager(config, this.id)\n    this._mutations = new CollectionMutationsManager(config, this.id)\n    this._state = new CollectionStateManager(config)\n    this._sync = new CollectionSyncManager(config, this.id)\n\n    this._changes.setDeps({\n      collection: this, // Required for passing to CollectionSubscription\n      lifecycle: this._lifecycle,\n      sync: this._sync,\n      events: this._events,\n    })\n    this._events.setDeps({\n      collection: this, // Required for adding to emitted events\n    })\n    this._indexes.setDeps({\n      state: this._state,\n      lifecycle: this._lifecycle,\n    })\n    this._lifecycle.setDeps({\n      changes: this._changes,\n      events: this._events,\n      indexes: this._indexes,\n      state: this._state,\n      sync: this._sync,\n    })\n    this._mutations.setDeps({\n      collection: this, // Required for passing to config.onInsert/onUpdate/onDelete and annotating mutations\n      lifecycle: this._lifecycle,\n      state: this._state,\n    })\n    this._state.setDeps({\n      collection: this, // Required for filtering events to only include this collection\n      lifecycle: this._lifecycle,\n      changes: this._changes,\n      indexes: this._indexes,\n    })\n    this._sync.setDeps({\n      collection: this, // Required for passing to config.sync callback\n      state: this._state,\n      lifecycle: this._lifecycle,\n      events: this._events,\n    })\n\n    // Only start sync immediately if explicitly enabled\n    if (config.startSync === true) {\n      this._sync.startSync()\n    }\n  }\n\n  /**\n   * Gets the current status of the collection\n   */\n  public get status(): CollectionStatus {\n    return this._lifecycle.status\n  }\n\n  /**\n   * Get the number of subscribers to the collection\n   */\n  public get subscriberCount(): number {\n    return this._changes.activeSubscribersCount\n  }\n\n  /**\n   * Register a callback to be executed when the collection first becomes ready\n   * Useful for preloading collections\n   * @param callback Function to call when the collection first becomes ready\n   * @example\n   * collection.onFirstReady(() => {\n   *   console.log('Collection is ready for the first time')\n   *   // Safe to access collection.state now\n   * })\n   */\n  public onFirstReady(callback: () => void): void {\n    return this._lifecycle.onFirstReady(callback)\n  }\n\n  /**\n   * Check if the collection is ready for use\n   * Returns true if the collection has been marked as ready by its sync implementation\n   * @returns true if the collection is ready, false otherwise\n   * @example\n   * if (collection.isReady()) {\n   *   console.log('Collection is ready, data is available')\n   *   // Safe to access collection.state\n   * } else {\n   *   console.log('Collection is still loading')\n   * }\n   */\n  public isReady(): boolean {\n    return this._lifecycle.status === `ready`\n  }\n\n  /**\n   * Check if the collection is currently loading more data\n   * @returns true if the collection has pending load more operations, false otherwise\n   */\n  public get isLoadingSubset(): boolean {\n    return this._sync.isLoadingSubset\n  }\n\n  /**\n   * Start sync immediately - internal method for compiled queries\n   * This bypasses lazy loading for special cases like live query results\n   */\n  public startSyncImmediate(): void {\n    this._sync.startSync()\n  }\n\n  /**\n   * Preload the collection data by starting sync if not already started\n   * Multiple concurrent calls will share the same promise\n   */\n  public preload(): Promise<void> {\n    return this._sync.preload()\n  }\n\n  /**\n   * Get the current value for a key (virtual derived state)\n   */\n  public get(key: TKey): TOutput | undefined {\n    return this._state.get(key)\n  }\n\n  /**\n   * Check if a key exists in the collection (virtual derived state)\n   */\n  public has(key: TKey): boolean {\n    return this._state.has(key)\n  }\n\n  /**\n   * Get the current size of the collection (cached)\n   */\n  public get size(): number {\n    return this._state.size\n  }\n\n  /**\n   * Get all keys (virtual derived state)\n   */\n  public *keys(): IterableIterator<TKey> {\n    yield* this._state.keys()\n  }\n\n  /**\n   * Get all values (virtual derived state)\n   */\n  public *values(): IterableIterator<TOutput> {\n    yield* this._state.values()\n  }\n\n  /**\n   * Get all entries (virtual derived state)\n   */\n  public *entries(): IterableIterator<[TKey, TOutput]> {\n    yield* this._state.entries()\n  }\n\n  /**\n   * Get all entries (virtual derived state)\n   */\n  public *[Symbol.iterator](): IterableIterator<[TKey, TOutput]> {\n    yield* this._state[Symbol.iterator]()\n  }\n\n  /**\n   * Execute a callback for each entry in the collection\n   */\n  public forEach(\n    callbackfn: (value: TOutput, key: TKey, index: number) => void\n  ): void {\n    return this._state.forEach(callbackfn)\n  }\n\n  /**\n   * Create a new array with the results of calling a function for each entry in the collection\n   */\n  public map<U>(\n    callbackfn: (value: TOutput, key: TKey, index: number) => U\n  ): Array<U> {\n    return this._state.map(callbackfn)\n  }\n\n  public getKeyFromItem(item: TOutput): TKey {\n    return this.config.getKey(item)\n  }\n\n  /**\n   * Creates an index on a collection for faster queries.\n   * Indexes significantly improve query performance by allowing constant time lookups\n   * and logarithmic time range queries instead of full scans.\n   *\n   * @template TResolver - The type of the index resolver (constructor or async loader)\n   * @param indexCallback - Function that extracts the indexed value from each item\n   * @param config - Configuration including index type and type-specific options\n   * @returns An index proxy that provides access to the index when ready\n   *\n   * @example\n   * // Create a default B+ tree index\n   * const ageIndex = collection.createIndex((row) => row.age)\n   *\n   * // Create a ordered index with custom options\n   * const ageIndex = collection.createIndex((row) => row.age, {\n   *   indexType: BTreeIndex,\n   *   options: {\n   *     compareFn: customComparator,\n   *     compareOptions: { direction: 'asc', nulls: 'first', stringSort: 'lexical' }\n   *   },\n   *   name: 'age_btree'\n   * })\n   *\n   * // Create an async-loaded index\n   * const textIndex = collection.createIndex((row) => row.content, {\n   *   indexType: async () => {\n   *     const { FullTextIndex } = await import('./indexes/fulltext.js')\n   *     return FullTextIndex\n   *   },\n   *   options: { language: 'en' }\n   * })\n   */\n  public createIndex<TResolver extends IndexResolver<TKey> = typeof BTreeIndex>(\n    indexCallback: (row: SingleRowRefProxy<TOutput>) => any,\n    config: IndexOptions<TResolver> = {}\n  ): IndexProxy<TKey> {\n    return this._indexes.createIndex(indexCallback, config)\n  }\n\n  /**\n   * Get resolved indexes for query optimization\n   */\n  get indexes(): Map<number, BaseIndex<TKey>> {\n    return this._indexes.indexes\n  }\n\n  /**\n   * Validates the data against the schema\n   */\n  public validateData(\n    data: unknown,\n    type: `insert` | `update`,\n    key?: TKey\n  ): TOutput | never {\n    return this._mutations.validateData(data, type, key)\n  }\n\n  /**\n   * Inserts one or more items into the collection\n   * @param items - Single item or array of items to insert\n   * @param config - Optional configuration including metadata\n   * @returns A Transaction object representing the insert operation(s)\n   * @throws {SchemaValidationError} If the data fails schema validation\n   * @example\n   * // Insert a single todo (requires onInsert handler)\n   * const tx = collection.insert({ id: \"1\", text: \"Buy milk\", completed: false })\n   * await tx.isPersisted.promise\n   *\n   * @example\n   * // Insert multiple todos at once\n   * const tx = collection.insert([\n   *   { id: \"1\", text: \"Buy milk\", completed: false },\n   *   { id: \"2\", text: \"Walk dog\", completed: true }\n   * ])\n   * await tx.isPersisted.promise\n   *\n   * @example\n   * // Insert with metadata\n   * const tx = collection.insert({ id: \"1\", text: \"Buy groceries\" },\n   *   { metadata: { source: \"mobile-app\" } }\n   * )\n   * await tx.isPersisted.promise\n   *\n   * @example\n   * // Handle errors\n   * try {\n   *   const tx = collection.insert({ id: \"1\", text: \"New item\" })\n   *   await tx.isPersisted.promise\n   *   console.log('Insert successful')\n   * } catch (error) {\n   *   console.log('Insert failed:', error)\n   * }\n   */\n  insert = (data: TInput | Array<TInput>, config?: InsertConfig) => {\n    return this._mutations.insert(data, config)\n  }\n\n  /**\n   * Updates one or more items in the collection using a callback function\n   * @param keys - Single key or array of keys to update\n   * @param configOrCallback - Either update configuration or update callback\n   * @param maybeCallback - Update callback if config was provided\n   * @returns A Transaction object representing the update operation(s)\n   * @throws {SchemaValidationError} If the updated data fails schema validation\n   * @example\n   * // Update single item by key\n   * const tx = collection.update(\"todo-1\", (draft) => {\n   *   draft.completed = true\n   * })\n   * await tx.isPersisted.promise\n   *\n   * @example\n   * // Update multiple items\n   * const tx = collection.update([\"todo-1\", \"todo-2\"], (drafts) => {\n   *   drafts.forEach(draft => { draft.completed = true })\n   * })\n   * await tx.isPersisted.promise\n   *\n   * @example\n   * // Update with metadata\n   * const tx = collection.update(\"todo-1\",\n   *   { metadata: { reason: \"user update\" } },\n   *   (draft) => { draft.text = \"Updated text\" }\n   * )\n   * await tx.isPersisted.promise\n   *\n   * @example\n   * // Handle errors\n   * try {\n   *   const tx = collection.update(\"item-1\", draft => { draft.value = \"new\" })\n   *   await tx.isPersisted.promise\n   *   console.log('Update successful')\n   * } catch (error) {\n   *   console.log('Update failed:', error)\n   * }\n   */\n\n  // Overload 1: Update multiple items with a callback\n  update(\n    key: Array<TKey | unknown>,\n    callback: (drafts: Array<WritableDeep<TInput>>) => void\n  ): TransactionType\n\n  // Overload 2: Update multiple items with config and a callback\n  update(\n    keys: Array<TKey | unknown>,\n    config: OperationConfig,\n    callback: (drafts: Array<WritableDeep<TInput>>) => void\n  ): TransactionType\n\n  // Overload 3: Update a single item with a callback\n  update(\n    id: TKey | unknown,\n    callback: (draft: WritableDeep<TInput>) => void\n  ): TransactionType\n\n  // Overload 4: Update a single item with config and a callback\n  update(\n    id: TKey | unknown,\n    config: OperationConfig,\n    callback: (draft: WritableDeep<TInput>) => void\n  ): TransactionType\n\n  update(\n    keys: (TKey | unknown) | Array<TKey | unknown>,\n    configOrCallback:\n      | ((draft: WritableDeep<TInput>) => void)\n      | ((drafts: Array<WritableDeep<TInput>>) => void)\n      | OperationConfig,\n    maybeCallback?:\n      | ((draft: WritableDeep<TInput>) => void)\n      | ((drafts: Array<WritableDeep<TInput>>) => void)\n  ) {\n    return this._mutations.update(keys, configOrCallback, maybeCallback)\n  }\n\n  /**\n   * Deletes one or more items from the collection\n   * @param keys - Single key or array of keys to delete\n   * @param config - Optional configuration including metadata\n   * @returns A Transaction object representing the delete operation(s)\n   * @example\n   * // Delete a single item\n   * const tx = collection.delete(\"todo-1\")\n   * await tx.isPersisted.promise\n   *\n   * @example\n   * // Delete multiple items\n   * const tx = collection.delete([\"todo-1\", \"todo-2\"])\n   * await tx.isPersisted.promise\n   *\n   * @example\n   * // Delete with metadata\n   * const tx = collection.delete(\"todo-1\", { metadata: { reason: \"completed\" } })\n   * await tx.isPersisted.promise\n   *\n   * @example\n   * // Handle errors\n   * try {\n   *   const tx = collection.delete(\"item-1\")\n   *   await tx.isPersisted.promise\n   *   console.log('Delete successful')\n   * } catch (error) {\n   *   console.log('Delete failed:', error)\n   * }\n   */\n  delete = (\n    keys: Array<TKey> | TKey,\n    config?: OperationConfig\n  ): TransactionType<any> => {\n    return this._mutations.delete(keys, config)\n  }\n\n  /**\n   * Gets the current state of the collection as a Map\n   * @returns Map containing all items in the collection, with keys as identifiers\n   * @example\n   * const itemsMap = collection.state\n   * console.log(`Collection has ${itemsMap.size} items`)\n   *\n   * for (const [key, item] of itemsMap) {\n   *   console.log(`${key}: ${item.title}`)\n   * }\n   *\n   * // Check if specific item exists\n   * if (itemsMap.has(\"todo-1\")) {\n   *   console.log(\"Todo 1 exists:\", itemsMap.get(\"todo-1\"))\n   * }\n   */\n  get state() {\n    const result = new Map<TKey, TOutput>()\n    for (const [key, value] of this.entries()) {\n      result.set(key, value)\n    }\n    return result\n  }\n\n  /**\n   * Gets the current state of the collection as a Map, but only resolves when data is available\n   * Waits for the first sync commit to complete before resolving\n   *\n   * @returns Promise that resolves to a Map containing all items in the collection\n   */\n  stateWhenReady(): Promise<Map<TKey, TOutput>> {\n    // If we already have data or collection is ready, resolve immediately\n    if (this.size > 0 || this.isReady()) {\n      return Promise.resolve(this.state)\n    }\n\n    // Use preload to ensure the collection starts loading, then return the state\n    return this.preload().then(() => this.state)\n  }\n\n  /**\n   * Gets the current state of the collection as an Array\n   *\n   * @returns An Array containing all items in the collection\n   */\n  get toArray() {\n    return Array.from(this.values())\n  }\n\n  /**\n   * Gets the current state of the collection as an Array, but only resolves when data is available\n   * Waits for the first sync commit to complete before resolving\n   *\n   * @returns Promise that resolves to an Array containing all items in the collection\n   */\n  toArrayWhenReady(): Promise<Array<TOutput>> {\n    // If we already have data or collection is ready, resolve immediately\n    if (this.size > 0 || this.isReady()) {\n      return Promise.resolve(this.toArray)\n    }\n\n    // Use preload to ensure the collection starts loading, then return the array\n    return this.preload().then(() => this.toArray)\n  }\n\n  /**\n   * Returns the current state of the collection as an array of changes\n   * @param options - Options including optional where filter\n   * @returns An array of changes\n   * @example\n   * // Get all items as changes\n   * const allChanges = collection.currentStateAsChanges()\n   *\n   * // Get only items matching a condition\n   * const activeChanges = collection.currentStateAsChanges({\n   *   where: (row) => row.status === 'active'\n   * })\n   *\n   * // Get only items using a pre-compiled expression\n   * const activeChanges = collection.currentStateAsChanges({\n   *   whereExpression: eq(row.status, 'active')\n   * })\n   */\n  public currentStateAsChanges(\n    options: CurrentStateAsChangesOptions = {}\n  ): Array<ChangeMessage<TOutput>> | void {\n    return currentStateAsChanges(this, options)\n  }\n\n  /**\n   * Subscribe to changes in the collection\n   * @param callback - Function called when items change\n   * @param options - Subscription options including includeInitialState and where filter\n   * @returns Unsubscribe function - Call this to stop listening for changes\n   * @example\n   * // Basic subscription\n   * const subscription = collection.subscribeChanges((changes) => {\n   *   changes.forEach(change => {\n   *     console.log(`${change.type}: ${change.key}`, change.value)\n   *   })\n   * })\n   *\n   * // Later: subscription.unsubscribe()\n   *\n   * @example\n   * // Include current state immediately\n   * const subscription = collection.subscribeChanges((changes) => {\n   *   updateUI(changes)\n   * }, { includeInitialState: true })\n   *\n   * @example\n   * // Subscribe only to changes matching a condition\n   * const subscription = collection.subscribeChanges((changes) => {\n   *   updateUI(changes)\n   * }, {\n   *   includeInitialState: true,\n   *   where: (row) => row.status === 'active'\n   * })\n   *\n   * @example\n   * // Subscribe using a pre-compiled expression\n   * const subscription = collection.subscribeChanges((changes) => {\n   *   updateUI(changes)\n   * }, {\n   *   includeInitialState: true,\n   *   whereExpression: eq(row.status, 'active')\n   * })\n   */\n  public subscribeChanges(\n    callback: (changes: Array<ChangeMessage<TOutput>>) => void,\n    options: SubscribeChangesOptions = {}\n  ): CollectionSubscription {\n    return this._changes.subscribeChanges(callback, options)\n  }\n\n  /**\n   * Subscribe to a collection event\n   */\n  public on<T extends keyof AllCollectionEvents>(\n    event: T,\n    callback: CollectionEventHandler<T>\n  ) {\n    return this._events.on(event, callback)\n  }\n\n  /**\n   * Subscribe to a collection event once\n   */\n  public once<T extends keyof AllCollectionEvents>(\n    event: T,\n    callback: CollectionEventHandler<T>\n  ) {\n    return this._events.once(event, callback)\n  }\n\n  /**\n   * Unsubscribe from a collection event\n   */\n  public off<T extends keyof AllCollectionEvents>(\n    event: T,\n    callback: CollectionEventHandler<T>\n  ) {\n    this._events.off(event, callback)\n  }\n\n  /**\n   * Wait for a collection event\n   */\n  public waitFor<T extends keyof AllCollectionEvents>(\n    event: T,\n    timeout?: number\n  ) {\n    return this._events.waitFor(event, timeout)\n  }\n\n  /**\n   * Clean up the collection by stopping sync and clearing data\n   * This can be called manually or automatically by garbage collection\n   */\n  public async cleanup(): Promise<void> {\n    this._lifecycle.cleanup()\n    return Promise.resolve()\n  }\n}\n"],"names":["config"],"mappings":"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"}
+{"version":3,"file":"index.js","sources":["../../../src/collection/index.ts"],"sourcesContent":["import {\n  CollectionRequiresConfigError,\n  CollectionRequiresSyncConfigError,\n} from \"../errors\"\nimport { currentStateAsChanges } from \"./change-events\"\n\nimport { CollectionStateManager } from \"./state\"\nimport { CollectionChangesManager } from \"./changes\"\nimport { CollectionLifecycleManager } from \"./lifecycle.js\"\nimport { CollectionSyncManager } from \"./sync\"\nimport { CollectionIndexesManager } from \"./indexes\"\nimport { CollectionMutationsManager } from \"./mutations\"\nimport { CollectionEventsManager } from \"./events.js\"\nimport type { CollectionSubscription } from \"./subscription\"\nimport type { AllCollectionEvents, CollectionEventHandler } from \"./events.js\"\nimport type { BaseIndex, IndexResolver } from \"../indexes/base-index.js\"\nimport type { IndexOptions } from \"../indexes/index-options.js\"\nimport type {\n  ChangeMessage,\n  CollectionConfig,\n  CollectionStatus,\n  CurrentStateAsChangesOptions,\n  Fn,\n  InferSchemaInput,\n  InferSchemaOutput,\n  InsertConfig,\n  NonSingleResult,\n  OperationConfig,\n  SingleResult,\n  StringCollationConfig,\n  SubscribeChangesOptions,\n  Transaction as TransactionType,\n  UtilsRecord,\n  WritableDeep,\n} from \"../types\"\nimport type { SingleRowRefProxy } from \"../query/builder/ref-proxy\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\nimport type { BTreeIndex } from \"../indexes/btree-index.js\"\nimport type { IndexProxy } from \"../indexes/lazy-index.js\"\n\n/**\n * Enhanced Collection interface that includes both data type T and utilities TUtils\n * @template T - The type of items in the collection\n * @template TKey - The type of the key for the collection\n * @template TUtils - The utilities record type\n * @template TInsertInput - The type for insert operations (can be different from T for schemas with defaults)\n */\nexport interface Collection<\n  T extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n  TUtils extends UtilsRecord = UtilsRecord,\n  TSchema extends StandardSchemaV1 = StandardSchemaV1,\n  TInsertInput extends object = T,\n> extends CollectionImpl<T, TKey, TUtils, TSchema, TInsertInput> {\n  readonly utils: TUtils\n  readonly singleResult?: true\n}\n\n/**\n * Creates a new Collection instance with the given configuration\n *\n * @template T - The schema type if a schema is provided, otherwise the type of items in the collection\n * @template TKey - The type of the key for the collection\n * @template TUtils - The utilities record type\n * @param options - Collection options with optional utilities\n * @returns A new Collection with utilities exposed both at top level and under .utils\n *\n * @example\n * // Pattern 1: With operation handlers (direct collection calls)\n * const todos = createCollection({\n *   id: \"todos\",\n *   getKey: (todo) => todo.id,\n *   schema,\n *   onInsert: async ({ transaction, collection }) => {\n *     // Send to API\n *     await api.createTodo(transaction.mutations[0].modified)\n *   },\n *   onUpdate: async ({ transaction, collection }) => {\n *     await api.updateTodo(transaction.mutations[0].modified)\n *   },\n *   onDelete: async ({ transaction, collection }) => {\n *     await api.deleteTodo(transaction.mutations[0].key)\n *   },\n *   sync: { sync: () => {} }\n * })\n *\n * // Direct usage (handlers manage transactions)\n * const tx = todos.insert({ id: \"1\", text: \"Buy milk\", completed: false })\n * await tx.isPersisted.promise\n *\n * @example\n * // Pattern 2: Manual transaction management\n * const todos = createCollection({\n *   getKey: (todo) => todo.id,\n *   schema: todoSchema,\n *   sync: { sync: () => {} }\n * })\n *\n * // Explicit transaction usage\n * const tx = createTransaction({\n *   mutationFn: async ({ transaction }) => {\n *     // Handle all mutations in transaction\n *     await api.saveChanges(transaction.mutations)\n *   }\n * })\n *\n * tx.mutate(() => {\n *   todos.insert({ id: \"1\", text: \"Buy milk\" })\n *   todos.update(\"2\", draft => { draft.completed = true })\n * })\n *\n * await tx.isPersisted.promise\n *\n * @example\n * // Using schema for type inference (preferred as it also gives you client side validation)\n * const todoSchema = z.object({\n *   id: z.string(),\n *   title: z.string(),\n *   completed: z.boolean()\n * })\n *\n * const todos = createCollection({\n *   schema: todoSchema,\n *   getKey: (todo) => todo.id,\n *   sync: { sync: () => {} }\n * })\n *\n */\n\n// Overload for when schema is provided\nexport function createCollection<\n  T extends StandardSchemaV1,\n  TKey extends string | number = string | number,\n  TUtils extends UtilsRecord = UtilsRecord,\n>(\n  options: CollectionConfig<InferSchemaOutput<T>, TKey, T, TUtils> & {\n    schema: T\n    utils?: TUtils\n  } & NonSingleResult\n): Collection<InferSchemaOutput<T>, TKey, TUtils, T, InferSchemaInput<T>> &\n  NonSingleResult\n\n// Overload for when schema is provided and singleResult is true\nexport function createCollection<\n  T extends StandardSchemaV1,\n  TKey extends string | number = string | number,\n  TUtils extends UtilsRecord = UtilsRecord,\n>(\n  options: CollectionConfig<InferSchemaOutput<T>, TKey, T, TUtils> & {\n    schema: T\n    utils?: TUtils\n  } & SingleResult\n): Collection<InferSchemaOutput<T>, TKey, TUtils, T, InferSchemaInput<T>> &\n  SingleResult\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 createCollection<\n  T extends object,\n  TKey extends string | number = string | number,\n  TUtils extends UtilsRecord = UtilsRecord,\n>(\n  options: CollectionConfig<T, TKey, never, TUtils> & {\n    schema?: never // prohibit schema if an explicit type is provided\n    utils?: TUtils\n  } & NonSingleResult\n): Collection<T, TKey, TUtils, never, T> & NonSingleResult\n\n// Overload for when no schema is provided and singleResult is true\n// the type T needs to be passed explicitly unless it can be inferred from the getKey function in the config\nexport function createCollection<\n  T extends object,\n  TKey extends string | number = string | number,\n  TUtils extends UtilsRecord = UtilsRecord,\n>(\n  options: CollectionConfig<T, TKey, never, TUtils> & {\n    schema?: never // prohibit schema if an explicit type is provided\n    utils?: TUtils\n  } & SingleResult\n): Collection<T, TKey, TUtils, never, T> & SingleResult\n\n// Implementation\nexport function createCollection(\n  options: CollectionConfig<any, string | number, any> & {\n    schema?: StandardSchemaV1\n    utils?: UtilsRecord\n  }\n): Collection<any, string | number, UtilsRecord, any, any> {\n  const collection = new CollectionImpl<any, string | number, any, any, any>(\n    options\n  )\n\n  // Attach utils to collection\n  if (options.utils) {\n    collection.utils = options.utils\n  } else {\n    collection.utils = {}\n  }\n\n  return collection\n}\n\nexport class CollectionImpl<\n  TOutput extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n  TUtils extends UtilsRecord = {},\n  TSchema extends StandardSchemaV1 = StandardSchemaV1,\n  TInput extends object = TOutput,\n> {\n  public id: string\n  public config: CollectionConfig<TOutput, TKey, TSchema>\n\n  // Utilities namespace\n  // This is populated by createCollection\n  public utils: Record<string, Fn> = {}\n\n  // Managers\n  private _events: CollectionEventsManager\n  private _changes: CollectionChangesManager<TOutput, TKey, TSchema, TInput>\n  public _lifecycle: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>\n  public _sync: CollectionSyncManager<TOutput, TKey, TSchema, TInput>\n  private _indexes: CollectionIndexesManager<TOutput, TKey, TSchema, TInput>\n  private _mutations: CollectionMutationsManager<\n    TOutput,\n    TKey,\n    TUtils,\n    TSchema,\n    TInput\n  >\n  // The core state of the collection is \"public\" so that is accessible in tests\n  // and for debugging\n  public _state: CollectionStateManager<TOutput, TKey, TSchema, TInput>\n\n  private comparisonOpts: StringCollationConfig\n\n  /**\n   * Creates a new Collection instance\n   *\n   * @param config - Configuration object for the collection\n   * @throws Error if sync config is missing\n   */\n  constructor(config: CollectionConfig<TOutput, TKey, TSchema>) {\n    // eslint-disable-next-line\n    if (!config) {\n      throw new CollectionRequiresConfigError()\n    }\n\n    // eslint-disable-next-line\n    if (!config.sync) {\n      throw new CollectionRequiresSyncConfigError()\n    }\n\n    if (config.id) {\n      this.id = config.id\n    } else {\n      this.id = crypto.randomUUID()\n    }\n\n    // Set default values for optional config properties\n    this.config = {\n      ...config,\n      autoIndex: config.autoIndex ?? `eager`,\n    }\n\n    this._changes = new CollectionChangesManager()\n    this._events = new CollectionEventsManager()\n    this._indexes = new CollectionIndexesManager()\n    this._lifecycle = new CollectionLifecycleManager(config, this.id)\n    this._mutations = new CollectionMutationsManager(config, this.id)\n    this._state = new CollectionStateManager(config)\n    this._sync = new CollectionSyncManager(config, this.id)\n\n    this.comparisonOpts = buildCompareOptionsFromConfig(config)\n\n    this._changes.setDeps({\n      collection: this, // Required for passing to CollectionSubscription\n      lifecycle: this._lifecycle,\n      sync: this._sync,\n      events: this._events,\n    })\n    this._events.setDeps({\n      collection: this, // Required for adding to emitted events\n    })\n    this._indexes.setDeps({\n      state: this._state,\n      lifecycle: this._lifecycle,\n    })\n    this._lifecycle.setDeps({\n      changes: this._changes,\n      events: this._events,\n      indexes: this._indexes,\n      state: this._state,\n      sync: this._sync,\n    })\n    this._mutations.setDeps({\n      collection: this, // Required for passing to config.onInsert/onUpdate/onDelete and annotating mutations\n      lifecycle: this._lifecycle,\n      state: this._state,\n    })\n    this._state.setDeps({\n      collection: this, // Required for filtering events to only include this collection\n      lifecycle: this._lifecycle,\n      changes: this._changes,\n      indexes: this._indexes,\n    })\n    this._sync.setDeps({\n      collection: this, // Required for passing to config.sync callback\n      state: this._state,\n      lifecycle: this._lifecycle,\n      events: this._events,\n    })\n\n    // Only start sync immediately if explicitly enabled\n    if (config.startSync === true) {\n      this._sync.startSync()\n    }\n  }\n\n  /**\n   * Gets the current status of the collection\n   */\n  public get status(): CollectionStatus {\n    return this._lifecycle.status\n  }\n\n  /**\n   * Get the number of subscribers to the collection\n   */\n  public get subscriberCount(): number {\n    return this._changes.activeSubscribersCount\n  }\n\n  /**\n   * Register a callback to be executed when the collection first becomes ready\n   * Useful for preloading collections\n   * @param callback Function to call when the collection first becomes ready\n   * @example\n   * collection.onFirstReady(() => {\n   *   console.log('Collection is ready for the first time')\n   *   // Safe to access collection.state now\n   * })\n   */\n  public onFirstReady(callback: () => void): void {\n    return this._lifecycle.onFirstReady(callback)\n  }\n\n  /**\n   * Check if the collection is ready for use\n   * Returns true if the collection has been marked as ready by its sync implementation\n   * @returns true if the collection is ready, false otherwise\n   * @example\n   * if (collection.isReady()) {\n   *   console.log('Collection is ready, data is available')\n   *   // Safe to access collection.state\n   * } else {\n   *   console.log('Collection is still loading')\n   * }\n   */\n  public isReady(): boolean {\n    return this._lifecycle.status === `ready`\n  }\n\n  /**\n   * Check if the collection is currently loading more data\n   * @returns true if the collection has pending load more operations, false otherwise\n   */\n  public get isLoadingSubset(): boolean {\n    return this._sync.isLoadingSubset\n  }\n\n  /**\n   * Start sync immediately - internal method for compiled queries\n   * This bypasses lazy loading for special cases like live query results\n   */\n  public startSyncImmediate(): void {\n    this._sync.startSync()\n  }\n\n  /**\n   * Preload the collection data by starting sync if not already started\n   * Multiple concurrent calls will share the same promise\n   */\n  public preload(): Promise<void> {\n    return this._sync.preload()\n  }\n\n  /**\n   * Get the current value for a key (virtual derived state)\n   */\n  public get(key: TKey): TOutput | undefined {\n    return this._state.get(key)\n  }\n\n  /**\n   * Check if a key exists in the collection (virtual derived state)\n   */\n  public has(key: TKey): boolean {\n    return this._state.has(key)\n  }\n\n  /**\n   * Get the current size of the collection (cached)\n   */\n  public get size(): number {\n    return this._state.size\n  }\n\n  /**\n   * Get all keys (virtual derived state)\n   */\n  public *keys(): IterableIterator<TKey> {\n    yield* this._state.keys()\n  }\n\n  /**\n   * Get all values (virtual derived state)\n   */\n  public *values(): IterableIterator<TOutput> {\n    yield* this._state.values()\n  }\n\n  /**\n   * Get all entries (virtual derived state)\n   */\n  public *entries(): IterableIterator<[TKey, TOutput]> {\n    yield* this._state.entries()\n  }\n\n  /**\n   * Get all entries (virtual derived state)\n   */\n  public *[Symbol.iterator](): IterableIterator<[TKey, TOutput]> {\n    yield* this._state[Symbol.iterator]()\n  }\n\n  /**\n   * Execute a callback for each entry in the collection\n   */\n  public forEach(\n    callbackfn: (value: TOutput, key: TKey, index: number) => void\n  ): void {\n    return this._state.forEach(callbackfn)\n  }\n\n  /**\n   * Create a new array with the results of calling a function for each entry in the collection\n   */\n  public map<U>(\n    callbackfn: (value: TOutput, key: TKey, index: number) => U\n  ): Array<U> {\n    return this._state.map(callbackfn)\n  }\n\n  public getKeyFromItem(item: TOutput): TKey {\n    return this.config.getKey(item)\n  }\n\n  /**\n   * Creates an index on a collection for faster queries.\n   * Indexes significantly improve query performance by allowing constant time lookups\n   * and logarithmic time range queries instead of full scans.\n   *\n   * @template TResolver - The type of the index resolver (constructor or async loader)\n   * @param indexCallback - Function that extracts the indexed value from each item\n   * @param config - Configuration including index type and type-specific options\n   * @returns An index proxy that provides access to the index when ready\n   *\n   * @example\n   * // Create a default B+ tree index\n   * const ageIndex = collection.createIndex((row) => row.age)\n   *\n   * // Create a ordered index with custom options\n   * const ageIndex = collection.createIndex((row) => row.age, {\n   *   indexType: BTreeIndex,\n   *   options: {\n   *     compareFn: customComparator,\n   *     compareOptions: { direction: 'asc', nulls: 'first', stringSort: 'lexical' }\n   *   },\n   *   name: 'age_btree'\n   * })\n   *\n   * // Create an async-loaded index\n   * const textIndex = collection.createIndex((row) => row.content, {\n   *   indexType: async () => {\n   *     const { FullTextIndex } = await import('./indexes/fulltext.js')\n   *     return FullTextIndex\n   *   },\n   *   options: { language: 'en' }\n   * })\n   */\n  public createIndex<TResolver extends IndexResolver<TKey> = typeof BTreeIndex>(\n    indexCallback: (row: SingleRowRefProxy<TOutput>) => any,\n    config: IndexOptions<TResolver> = {}\n  ): IndexProxy<TKey> {\n    return this._indexes.createIndex(indexCallback, config)\n  }\n\n  /**\n   * Get resolved indexes for query optimization\n   */\n  get indexes(): Map<number, BaseIndex<TKey>> {\n    return this._indexes.indexes\n  }\n\n  /**\n   * Validates the data against the schema\n   */\n  public validateData(\n    data: unknown,\n    type: `insert` | `update`,\n    key?: TKey\n  ): TOutput | never {\n    return this._mutations.validateData(data, type, key)\n  }\n\n  get compareOptions(): StringCollationConfig {\n    // return a copy such that no one can mutate the internal comparison object\n    return { ...this.comparisonOpts }\n  }\n\n  /**\n   * Inserts one or more items into the collection\n   * @param items - Single item or array of items to insert\n   * @param config - Optional configuration including metadata\n   * @returns A Transaction object representing the insert operation(s)\n   * @throws {SchemaValidationError} If the data fails schema validation\n   * @example\n   * // Insert a single todo (requires onInsert handler)\n   * const tx = collection.insert({ id: \"1\", text: \"Buy milk\", completed: false })\n   * await tx.isPersisted.promise\n   *\n   * @example\n   * // Insert multiple todos at once\n   * const tx = collection.insert([\n   *   { id: \"1\", text: \"Buy milk\", completed: false },\n   *   { id: \"2\", text: \"Walk dog\", completed: true }\n   * ])\n   * await tx.isPersisted.promise\n   *\n   * @example\n   * // Insert with metadata\n   * const tx = collection.insert({ id: \"1\", text: \"Buy groceries\" },\n   *   { metadata: { source: \"mobile-app\" } }\n   * )\n   * await tx.isPersisted.promise\n   *\n   * @example\n   * // Handle errors\n   * try {\n   *   const tx = collection.insert({ id: \"1\", text: \"New item\" })\n   *   await tx.isPersisted.promise\n   *   console.log('Insert successful')\n   * } catch (error) {\n   *   console.log('Insert failed:', error)\n   * }\n   */\n  insert = (data: TInput | Array<TInput>, config?: InsertConfig) => {\n    return this._mutations.insert(data, config)\n  }\n\n  /**\n   * Updates one or more items in the collection using a callback function\n   * @param keys - Single key or array of keys to update\n   * @param configOrCallback - Either update configuration or update callback\n   * @param maybeCallback - Update callback if config was provided\n   * @returns A Transaction object representing the update operation(s)\n   * @throws {SchemaValidationError} If the updated data fails schema validation\n   * @example\n   * // Update single item by key\n   * const tx = collection.update(\"todo-1\", (draft) => {\n   *   draft.completed = true\n   * })\n   * await tx.isPersisted.promise\n   *\n   * @example\n   * // Update multiple items\n   * const tx = collection.update([\"todo-1\", \"todo-2\"], (drafts) => {\n   *   drafts.forEach(draft => { draft.completed = true })\n   * })\n   * await tx.isPersisted.promise\n   *\n   * @example\n   * // Update with metadata\n   * const tx = collection.update(\"todo-1\",\n   *   { metadata: { reason: \"user update\" } },\n   *   (draft) => { draft.text = \"Updated text\" }\n   * )\n   * await tx.isPersisted.promise\n   *\n   * @example\n   * // Handle errors\n   * try {\n   *   const tx = collection.update(\"item-1\", draft => { draft.value = \"new\" })\n   *   await tx.isPersisted.promise\n   *   console.log('Update successful')\n   * } catch (error) {\n   *   console.log('Update failed:', error)\n   * }\n   */\n\n  // Overload 1: Update multiple items with a callback\n  update(\n    key: Array<TKey | unknown>,\n    callback: (drafts: Array<WritableDeep<TInput>>) => void\n  ): TransactionType\n\n  // Overload 2: Update multiple items with config and a callback\n  update(\n    keys: Array<TKey | unknown>,\n    config: OperationConfig,\n    callback: (drafts: Array<WritableDeep<TInput>>) => void\n  ): TransactionType\n\n  // Overload 3: Update a single item with a callback\n  update(\n    id: TKey | unknown,\n    callback: (draft: WritableDeep<TInput>) => void\n  ): TransactionType\n\n  // Overload 4: Update a single item with config and a callback\n  update(\n    id: TKey | unknown,\n    config: OperationConfig,\n    callback: (draft: WritableDeep<TInput>) => void\n  ): TransactionType\n\n  update(\n    keys: (TKey | unknown) | Array<TKey | unknown>,\n    configOrCallback:\n      | ((draft: WritableDeep<TInput>) => void)\n      | ((drafts: Array<WritableDeep<TInput>>) => void)\n      | OperationConfig,\n    maybeCallback?:\n      | ((draft: WritableDeep<TInput>) => void)\n      | ((drafts: Array<WritableDeep<TInput>>) => void)\n  ) {\n    return this._mutations.update(keys, configOrCallback, maybeCallback)\n  }\n\n  /**\n   * Deletes one or more items from the collection\n   * @param keys - Single key or array of keys to delete\n   * @param config - Optional configuration including metadata\n   * @returns A Transaction object representing the delete operation(s)\n   * @example\n   * // Delete a single item\n   * const tx = collection.delete(\"todo-1\")\n   * await tx.isPersisted.promise\n   *\n   * @example\n   * // Delete multiple items\n   * const tx = collection.delete([\"todo-1\", \"todo-2\"])\n   * await tx.isPersisted.promise\n   *\n   * @example\n   * // Delete with metadata\n   * const tx = collection.delete(\"todo-1\", { metadata: { reason: \"completed\" } })\n   * await tx.isPersisted.promise\n   *\n   * @example\n   * // Handle errors\n   * try {\n   *   const tx = collection.delete(\"item-1\")\n   *   await tx.isPersisted.promise\n   *   console.log('Delete successful')\n   * } catch (error) {\n   *   console.log('Delete failed:', error)\n   * }\n   */\n  delete = (\n    keys: Array<TKey> | TKey,\n    config?: OperationConfig\n  ): TransactionType<any> => {\n    return this._mutations.delete(keys, config)\n  }\n\n  /**\n   * Gets the current state of the collection as a Map\n   * @returns Map containing all items in the collection, with keys as identifiers\n   * @example\n   * const itemsMap = collection.state\n   * console.log(`Collection has ${itemsMap.size} items`)\n   *\n   * for (const [key, item] of itemsMap) {\n   *   console.log(`${key}: ${item.title}`)\n   * }\n   *\n   * // Check if specific item exists\n   * if (itemsMap.has(\"todo-1\")) {\n   *   console.log(\"Todo 1 exists:\", itemsMap.get(\"todo-1\"))\n   * }\n   */\n  get state() {\n    const result = new Map<TKey, TOutput>()\n    for (const [key, value] of this.entries()) {\n      result.set(key, value)\n    }\n    return result\n  }\n\n  /**\n   * Gets the current state of the collection as a Map, but only resolves when data is available\n   * Waits for the first sync commit to complete before resolving\n   *\n   * @returns Promise that resolves to a Map containing all items in the collection\n   */\n  stateWhenReady(): Promise<Map<TKey, TOutput>> {\n    // If we already have data or collection is ready, resolve immediately\n    if (this.size > 0 || this.isReady()) {\n      return Promise.resolve(this.state)\n    }\n\n    // Use preload to ensure the collection starts loading, then return the state\n    return this.preload().then(() => this.state)\n  }\n\n  /**\n   * Gets the current state of the collection as an Array\n   *\n   * @returns An Array containing all items in the collection\n   */\n  get toArray() {\n    return Array.from(this.values())\n  }\n\n  /**\n   * Gets the current state of the collection as an Array, but only resolves when data is available\n   * Waits for the first sync commit to complete before resolving\n   *\n   * @returns Promise that resolves to an Array containing all items in the collection\n   */\n  toArrayWhenReady(): Promise<Array<TOutput>> {\n    // If we already have data or collection is ready, resolve immediately\n    if (this.size > 0 || this.isReady()) {\n      return Promise.resolve(this.toArray)\n    }\n\n    // Use preload to ensure the collection starts loading, then return the array\n    return this.preload().then(() => this.toArray)\n  }\n\n  /**\n   * Returns the current state of the collection as an array of changes\n   * @param options - Options including optional where filter\n   * @returns An array of changes\n   * @example\n   * // Get all items as changes\n   * const allChanges = collection.currentStateAsChanges()\n   *\n   * // Get only items matching a condition\n   * const activeChanges = collection.currentStateAsChanges({\n   *   where: (row) => row.status === 'active'\n   * })\n   *\n   * // Get only items using a pre-compiled expression\n   * const activeChanges = collection.currentStateAsChanges({\n   *   whereExpression: eq(row.status, 'active')\n   * })\n   */\n  public currentStateAsChanges(\n    options: CurrentStateAsChangesOptions = {}\n  ): Array<ChangeMessage<TOutput>> | void {\n    return currentStateAsChanges(this, options)\n  }\n\n  /**\n   * Subscribe to changes in the collection\n   * @param callback - Function called when items change\n   * @param options - Subscription options including includeInitialState and where filter\n   * @returns Unsubscribe function - Call this to stop listening for changes\n   * @example\n   * // Basic subscription\n   * const subscription = collection.subscribeChanges((changes) => {\n   *   changes.forEach(change => {\n   *     console.log(`${change.type}: ${change.key}`, change.value)\n   *   })\n   * })\n   *\n   * // Later: subscription.unsubscribe()\n   *\n   * @example\n   * // Include current state immediately\n   * const subscription = collection.subscribeChanges((changes) => {\n   *   updateUI(changes)\n   * }, { includeInitialState: true })\n   *\n   * @example\n   * // Subscribe only to changes matching a condition\n   * const subscription = collection.subscribeChanges((changes) => {\n   *   updateUI(changes)\n   * }, {\n   *   includeInitialState: true,\n   *   where: (row) => row.status === 'active'\n   * })\n   *\n   * @example\n   * // Subscribe using a pre-compiled expression\n   * const subscription = collection.subscribeChanges((changes) => {\n   *   updateUI(changes)\n   * }, {\n   *   includeInitialState: true,\n   *   whereExpression: eq(row.status, 'active')\n   * })\n   */\n  public subscribeChanges(\n    callback: (changes: Array<ChangeMessage<TOutput>>) => void,\n    options: SubscribeChangesOptions = {}\n  ): CollectionSubscription {\n    return this._changes.subscribeChanges(callback, options)\n  }\n\n  /**\n   * Subscribe to a collection event\n   */\n  public on<T extends keyof AllCollectionEvents>(\n    event: T,\n    callback: CollectionEventHandler<T>\n  ) {\n    return this._events.on(event, callback)\n  }\n\n  /**\n   * Subscribe to a collection event once\n   */\n  public once<T extends keyof AllCollectionEvents>(\n    event: T,\n    callback: CollectionEventHandler<T>\n  ) {\n    return this._events.once(event, callback)\n  }\n\n  /**\n   * Unsubscribe from a collection event\n   */\n  public off<T extends keyof AllCollectionEvents>(\n    event: T,\n    callback: CollectionEventHandler<T>\n  ) {\n    this._events.off(event, callback)\n  }\n\n  /**\n   * Wait for a collection event\n   */\n  public waitFor<T extends keyof AllCollectionEvents>(\n    event: T,\n    timeout?: number\n  ) {\n    return this._events.waitFor(event, timeout)\n  }\n\n  /**\n   * Clean up the collection by stopping sync and clearing data\n   * This can be called manually or automatically by garbage collection\n   */\n  public async cleanup(): Promise<void> {\n    this._lifecycle.cleanup()\n    return Promise.resolve()\n  }\n}\n\nfunction buildCompareOptionsFromConfig(\n  config: CollectionConfig<any, any, any>\n): StringCollationConfig {\n  if (config.defaultStringCollation) {\n    const options = config.defaultStringCollation\n    return {\n      stringSort: options.stringSort ?? `locale`,\n      locale: options.stringSort === `locale` ? options.locale : undefined,\n      localeOptions:\n        options.stringSort === `locale` ? options.localeOptions : undefined,\n    }\n  } else {\n    return {\n      stringSort: `locale`,\n    }\n  }\n}\n"],"names":["config"],"mappings":"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"}

package/dist/esm/index.d.ts

@@ -15,5 +15,7 @@ export * from './indexes/base-index.js';
 export * from './indexes/btree-index.js';
 export * from './indexes/lazy-index.js';
 export { type IndexOptions } from './indexes/index-options.js';
+export * from './query/expression-helpers.js';
 export type { Collection } from './collection/index.js';
 export { IR };
+export { operators, type OperatorName } from './query/builder/functions.js';

package/dist/esm/index.js

@@ -11,10 +11,13 @@ import { createPacedMutations } from "./paced-mutations.js";
 import { BaseIndex, IndexOperation } from "./indexes/base-index.js";
 import { BTreeIndex } from "./indexes/btree-index.js";
 import { IndexProxy, LazyIndexWrapper } from "./indexes/lazy-index.js";
+import { extractFieldPath, extractSimpleComparisons, extractValue, parseLoadSubsetOptions, parseOrderByExpression, parseWhereExpression, walkExpression } from "./query/expression-helpers.js";
+import { add, and, avg, coalesce, concat, count, eq, gt, gte, ilike, inArray, isNull, isUndefined, length, like, lower, lt, lte, max, min, not, operators, or, sum, upper } from "./query/builder/functions.js";
 import { BaseQueryBuilder, Query } from "./query/builder/index.js";
-import { add, and, avg, coalesce, concat, count, eq, gt, gte, ilike, inArray, isNull, isUndefined, length, like, lower, lt, lte, max, min, not, or, sum, upper } from "./query/builder/functions.js";
 import { compileQuery } from "./query/compiler/index.js";
 import { createLiveQueryCollection, liveQueryCollectionOptions } from "./query/live-query-collection.js";
+import { isLimitSubset, isOrderBySubset, isPredicateSubset, isWhereSubset, minusWherePredicates, unionWherePredicates } from "./query/predicate-utils.js";
+import { DeduplicatedLoadSubset } from "./query/subset-dedupe.js";
 import { debounceStrategy } from "./strategies/debounceStrategy.js";
 import { queueStrategy } from "./strategies/queueStrategy.js";
 import { throttleStrategy } from "./strategies/throttleStrategy.js";
@@ -34,6 +37,7 @@ export {
   CollectionRequiresConfigError,
   CollectionRequiresSyncConfigError,
   CollectionStateError,
+  DeduplicatedLoadSubset,
   DeleteKeyNotFoundError,
   DistinctRequiresSelectError,
   DuplicateAliasInSubqueryError,
@@ -127,13 +131,20 @@ export {
   createTransaction,
   debounceStrategy,
   eq,
+  extractFieldPath,
+  extractSimpleComparisons,
+  extractValue,
   getActiveTransaction,
   gt,
   gte,
   ilike,
   inArray,
+  isLimitSubset,
   isNull,
+  isOrderBySubset,
+  isPredicateSubset,
   isUndefined,
+  isWhereSubset,
   length,
   like,
   liveQueryCollectionOptions,
@@ -144,12 +155,19 @@ export {
   lte,
   max,
   min,
+  minusWherePredicates,
   not,
+  operators,
   or,
+  parseLoadSubsetOptions,
+  parseOrderByExpression,
+  parseWhereExpression,
   queueStrategy,
   sum,
   throttleStrategy,
+  unionWherePredicates,
   upper,
+  walkExpression,
   withArrayChangeTracking,
   withChangeTracking
 };

package/dist/esm/index.js.map

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

package/dist/esm/indexes/auto-index.js

@@ -6,12 +6,16 @@ function shouldAutoIndex(collection) {
   }
   return true;
 }
-function ensureIndexForField(fieldName, fieldPath, collection, compareOptions = DEFAULT_COMPARE_OPTIONS, compareFn) {
+function ensureIndexForField(fieldName, fieldPath, collection, compareOptions, compareFn) {
   if (!shouldAutoIndex(collection)) {
     return;
   }
+  const compareOpts = compareOptions ?? {
+    ...DEFAULT_COMPARE_OPTIONS,
+    ...collection.compareOptions
+  };
   const existingIndex = Array.from(collection.indexes.values()).find(
-    (index) => index.matchesField(fieldPath) && index.matchesCompareOptions(compareOptions)
+    (index) => index.matchesField(fieldPath) && index.matchesCompareOptions(compareOpts)
   );
   if (existingIndex) {
     return;
@@ -28,7 +32,7 @@ function ensureIndexForField(fieldName, fieldPath, collection, compareOptions =
       {
         name: `auto:${fieldPath.join(`.`)}`,
         indexType: BTreeIndex,
-        options: compareFn ? { compareFn, compareOptions } : {}
+        options: compareFn ? { compareFn, compareOptions: compareOpts } : {}
       }
     );
   } catch (error) {

package/dist/esm/indexes/auto-index.js.map

@@ -1 +1 @@
-{"version":3,"file":"auto-index.js","sources":["../../../src/indexes/auto-index.ts"],"sourcesContent":["import { DEFAULT_COMPARE_OPTIONS } from \"../utils\"\nimport { BTreeIndex } from \"./btree-index\"\nimport type { CompareOptions } from \"../query/builder/types\"\nimport type { BasicExpression } from \"../query/ir\"\nimport type { CollectionImpl } from \"../collection/index.js\"\n\nexport interface AutoIndexConfig {\n  autoIndex?: `off` | `eager`\n}\n\nfunction shouldAutoIndex(collection: CollectionImpl<any, any, any, any, any>) {\n  // Only proceed if auto-indexing is enabled\n  if (collection.config.autoIndex !== `eager`) {\n    return false\n  }\n\n  return true\n}\n\nexport function ensureIndexForField<\n  T extends Record<string, any>,\n  TKey extends string | number,\n>(\n  fieldName: string,\n  fieldPath: Array<string>,\n  collection: CollectionImpl<T, TKey, any, any, any>,\n  compareOptions: CompareOptions = DEFAULT_COMPARE_OPTIONS,\n  compareFn?: (a: any, b: any) => number\n) {\n  if (!shouldAutoIndex(collection)) {\n    return\n  }\n\n  // Check if we already have an index for this field\n  const existingIndex = Array.from(collection.indexes.values()).find(\n    (index) =>\n      index.matchesField(fieldPath) &&\n      index.matchesCompareOptions(compareOptions)\n  )\n\n  if (existingIndex) {\n    return // Index already exists\n  }\n\n  // Create a new index for this field using the collection's createIndex method\n  try {\n    // Use the proxy-based approach to create the proper accessor for nested paths\n    collection.createIndex(\n      (row) => {\n        // Navigate through the field path\n        let current: any = row\n        for (const part of fieldPath) {\n          current = current[part]\n        }\n        return current\n      },\n      {\n        name: `auto:${fieldPath.join(`.`)}`,\n        indexType: BTreeIndex,\n        options: compareFn ? { compareFn, compareOptions } : {},\n      }\n    )\n  } catch (error) {\n    console.warn(\n      `${collection.id ? `[${collection.id}] ` : ``}Failed to create auto-index for field path \"${fieldPath.join(`.`)}\":`,\n      error\n    )\n  }\n}\n\n/**\n * Analyzes a where expression and creates indexes for all simple operations on single fields\n */\nexport function ensureIndexForExpression<\n  T extends Record<string, any>,\n  TKey extends string | number,\n>(\n  expression: BasicExpression,\n  collection: CollectionImpl<T, TKey, any, any, any>\n): void {\n  if (!shouldAutoIndex(collection)) {\n    return\n  }\n\n  // Extract all indexable expressions and create indexes for them\n  const indexableExpressions = extractIndexableExpressions(expression)\n\n  for (const { fieldName, fieldPath } of indexableExpressions) {\n    ensureIndexForField(fieldName, fieldPath, collection)\n  }\n}\n\n/**\n * Extracts all indexable expressions from a where expression\n */\nfunction extractIndexableExpressions(\n  expression: BasicExpression\n): Array<{ fieldName: string; fieldPath: Array<string> }> {\n  const results: Array<{ fieldName: string; fieldPath: Array<string> }> = []\n\n  function extractFromExpression(expr: BasicExpression): void {\n    if (expr.type !== `func`) {\n      return\n    }\n\n    const func = expr as any\n\n    // Handle 'and' expressions by recursively processing all arguments\n    if (func.name === `and`) {\n      for (const arg of func.args) {\n        extractFromExpression(arg)\n      }\n      return\n    }\n\n    // Check if this is a supported operation\n    const supportedOperations = [`eq`, `gt`, `gte`, `lt`, `lte`, `in`]\n    if (!supportedOperations.includes(func.name)) {\n      return\n    }\n\n    // Check if the first argument is a property reference\n    if (func.args.length < 1 || func.args[0].type !== `ref`) {\n      return\n    }\n\n    const fieldRef = func.args[0]\n    const fieldPath = fieldRef.path\n\n    // Skip if the path is empty\n    if (fieldPath.length === 0) {\n      return\n    }\n\n    // For nested paths, use the full path joined with underscores as the field name\n    // For simple paths, use the first (and only) element\n    const fieldName = fieldPath.join(`_`)\n    results.push({ fieldName, fieldPath })\n  }\n\n  extractFromExpression(expression)\n  return results\n}\n"],"names":[],"mappings":";;AAUA,SAAS,gBAAgB,YAAqD;AAE5E,MAAI,WAAW,OAAO,cAAc,SAAS;AAC3C,WAAO;AAAA,EACT;AAEA,SAAO;AACT;AAEO,SAAS,oBAId,WACA,WACA,YACA,iBAAiC,yBACjC,WACA;AACA,MAAI,CAAC,gBAAgB,UAAU,GAAG;AAChC;AAAA,EACF;AAGA,QAAM,gBAAgB,MAAM,KAAK,WAAW,QAAQ,OAAA,CAAQ,EAAE;AAAA,IAC5D,CAAC,UACC,MAAM,aAAa,SAAS,KAC5B,MAAM,sBAAsB,cAAc;AAAA,EAAA;AAG9C,MAAI,eAAe;AACjB;AAAA,EACF;AAGA,MAAI;AAEF,eAAW;AAAA,MACT,CAAC,QAAQ;AAEP,YAAI,UAAe;AACnB,mBAAW,QAAQ,WAAW;AAC5B,oBAAU,QAAQ,IAAI;AAAA,QACxB;AACA,eAAO;AAAA,MACT;AAAA,MACA;AAAA,QACE,MAAM,QAAQ,UAAU,KAAK,GAAG,CAAC;AAAA,QACjC,WAAW;AAAA,QACX,SAAS,YAAY,EAAE,WAAW,eAAA,IAAmB,CAAA;AAAA,MAAC;AAAA,IACxD;AAAA,EAEJ,SAAS,OAAO;AACd,YAAQ;AAAA,MACN,GAAG,WAAW,KAAK,IAAI,WAAW,EAAE,OAAO,EAAE,+CAA+C,UAAU,KAAK,GAAG,CAAC;AAAA,MAC/G;AAAA,IAAA;AAAA,EAEJ;AACF;AAKO,SAAS,yBAId,YACA,YACM;AACN,MAAI,CAAC,gBAAgB,UAAU,GAAG;AAChC;AAAA,EACF;AAGA,QAAM,uBAAuB,4BAA4B,UAAU;AAEnE,aAAW,EAAE,WAAW,UAAA,KAAe,sBAAsB;AAC3D,wBAAoB,WAAW,WAAW,UAAU;AAAA,EACtD;AACF;AAKA,SAAS,4BACP,YACwD;AACxD,QAAM,UAAkE,CAAA;AAExE,WAAS,sBAAsB,MAA6B;AAC1D,QAAI,KAAK,SAAS,QAAQ;AACxB;AAAA,IACF;AAEA,UAAM,OAAO;AAGb,QAAI,KAAK,SAAS,OAAO;AACvB,iBAAW,OAAO,KAAK,MAAM;AAC3B,8BAAsB,GAAG;AAAA,MAC3B;AACA;AAAA,IACF;AAGA,UAAM,sBAAsB,CAAC,MAAM,MAAM,OAAO,MAAM,OAAO,IAAI;AACjE,QAAI,CAAC,oBAAoB,SAAS,KAAK,IAAI,GAAG;AAC5C;AAAA,IACF;AAGA,QAAI,KAAK,KAAK,SAAS,KAAK,KAAK,KAAK,CAAC,EAAE,SAAS,OAAO;AACvD;AAAA,IACF;AAEA,UAAM,WAAW,KAAK,KAAK,CAAC;AAC5B,UAAM,YAAY,SAAS;AAG3B,QAAI,UAAU,WAAW,GAAG;AAC1B;AAAA,IACF;AAIA,UAAM,YAAY,UAAU,KAAK,GAAG;AACpC,YAAQ,KAAK,EAAE,WAAW,UAAA,CAAW;AAAA,EACvC;AAEA,wBAAsB,UAAU;AAChC,SAAO;AACT;"}
+{"version":3,"file":"auto-index.js","sources":["../../../src/indexes/auto-index.ts"],"sourcesContent":["import { DEFAULT_COMPARE_OPTIONS } from \"../utils\"\nimport { BTreeIndex } from \"./btree-index\"\nimport type { CompareOptions } from \"../query/builder/types\"\nimport type { BasicExpression } from \"../query/ir\"\nimport type { CollectionImpl } from \"../collection/index.js\"\n\nexport interface AutoIndexConfig {\n  autoIndex?: `off` | `eager`\n}\n\nfunction shouldAutoIndex(collection: CollectionImpl<any, any, any, any, any>) {\n  // Only proceed if auto-indexing is enabled\n  if (collection.config.autoIndex !== `eager`) {\n    return false\n  }\n\n  return true\n}\n\nexport function ensureIndexForField<\n  T extends Record<string, any>,\n  TKey extends string | number,\n>(\n  fieldName: string,\n  fieldPath: Array<string>,\n  collection: CollectionImpl<T, TKey, any, any, any>,\n  compareOptions?: CompareOptions,\n  compareFn?: (a: any, b: any) => number\n) {\n  if (!shouldAutoIndex(collection)) {\n    return\n  }\n\n  const compareOpts = compareOptions ?? {\n    ...DEFAULT_COMPARE_OPTIONS,\n    ...collection.compareOptions,\n  }\n\n  // Check if we already have an index for this field\n  const existingIndex = Array.from(collection.indexes.values()).find(\n    (index) =>\n      index.matchesField(fieldPath) && index.matchesCompareOptions(compareOpts)\n  )\n\n  if (existingIndex) {\n    return // Index already exists\n  }\n\n  // Create a new index for this field using the collection's createIndex method\n  try {\n    // Use the proxy-based approach to create the proper accessor for nested paths\n    collection.createIndex(\n      (row) => {\n        // Navigate through the field path\n        let current: any = row\n        for (const part of fieldPath) {\n          current = current[part]\n        }\n        return current\n      },\n      {\n        name: `auto:${fieldPath.join(`.`)}`,\n        indexType: BTreeIndex,\n        options: compareFn ? { compareFn, compareOptions: compareOpts } : {},\n      }\n    )\n  } catch (error) {\n    console.warn(\n      `${collection.id ? `[${collection.id}] ` : ``}Failed to create auto-index for field path \"${fieldPath.join(`.`)}\":`,\n      error\n    )\n  }\n}\n\n/**\n * Analyzes a where expression and creates indexes for all simple operations on single fields\n */\nexport function ensureIndexForExpression<\n  T extends Record<string, any>,\n  TKey extends string | number,\n>(\n  expression: BasicExpression,\n  collection: CollectionImpl<T, TKey, any, any, any>\n): void {\n  if (!shouldAutoIndex(collection)) {\n    return\n  }\n\n  // Extract all indexable expressions and create indexes for them\n  const indexableExpressions = extractIndexableExpressions(expression)\n\n  for (const { fieldName, fieldPath } of indexableExpressions) {\n    ensureIndexForField(fieldName, fieldPath, collection)\n  }\n}\n\n/**\n * Extracts all indexable expressions from a where expression\n */\nfunction extractIndexableExpressions(\n  expression: BasicExpression\n): Array<{ fieldName: string; fieldPath: Array<string> }> {\n  const results: Array<{ fieldName: string; fieldPath: Array<string> }> = []\n\n  function extractFromExpression(expr: BasicExpression): void {\n    if (expr.type !== `func`) {\n      return\n    }\n\n    const func = expr as any\n\n    // Handle 'and' expressions by recursively processing all arguments\n    if (func.name === `and`) {\n      for (const arg of func.args) {\n        extractFromExpression(arg)\n      }\n      return\n    }\n\n    // Check if this is a supported operation\n    const supportedOperations = [`eq`, `gt`, `gte`, `lt`, `lte`, `in`]\n    if (!supportedOperations.includes(func.name)) {\n      return\n    }\n\n    // Check if the first argument is a property reference\n    if (func.args.length < 1 || func.args[0].type !== `ref`) {\n      return\n    }\n\n    const fieldRef = func.args[0]\n    const fieldPath = fieldRef.path\n\n    // Skip if the path is empty\n    if (fieldPath.length === 0) {\n      return\n    }\n\n    // For nested paths, use the full path joined with underscores as the field name\n    // For simple paths, use the first (and only) element\n    const fieldName = fieldPath.join(`_`)\n    results.push({ fieldName, fieldPath })\n  }\n\n  extractFromExpression(expression)\n  return results\n}\n"],"names":[],"mappings":";;AAUA,SAAS,gBAAgB,YAAqD;AAE5E,MAAI,WAAW,OAAO,cAAc,SAAS;AAC3C,WAAO;AAAA,EACT;AAEA,SAAO;AACT;AAEO,SAAS,oBAId,WACA,WACA,YACA,gBACA,WACA;AACA,MAAI,CAAC,gBAAgB,UAAU,GAAG;AAChC;AAAA,EACF;AAEA,QAAM,cAAc,kBAAkB;AAAA,IACpC,GAAG;AAAA,IACH,GAAG,WAAW;AAAA,EAAA;AAIhB,QAAM,gBAAgB,MAAM,KAAK,WAAW,QAAQ,OAAA,CAAQ,EAAE;AAAA,IAC5D,CAAC,UACC,MAAM,aAAa,SAAS,KAAK,MAAM,sBAAsB,WAAW;AAAA,EAAA;AAG5E,MAAI,eAAe;AACjB;AAAA,EACF;AAGA,MAAI;AAEF,eAAW;AAAA,MACT,CAAC,QAAQ;AAEP,YAAI,UAAe;AACnB,mBAAW,QAAQ,WAAW;AAC5B,oBAAU,QAAQ,IAAI;AAAA,QACxB;AACA,eAAO;AAAA,MACT;AAAA,MACA;AAAA,QACE,MAAM,QAAQ,UAAU,KAAK,GAAG,CAAC;AAAA,QACjC,WAAW;AAAA,QACX,SAAS,YAAY,EAAE,WAAW,gBAAgB,YAAA,IAAgB,CAAA;AAAA,MAAC;AAAA,IACrE;AAAA,EAEJ,SAAS,OAAO;AACd,YAAQ;AAAA,MACN,GAAG,WAAW,KAAK,IAAI,WAAW,EAAE,OAAO,EAAE,+CAA+C,UAAU,KAAK,GAAG,CAAC;AAAA,MAC/G;AAAA,IAAA;AAAA,EAEJ;AACF;AAKO,SAAS,yBAId,YACA,YACM;AACN,MAAI,CAAC,gBAAgB,UAAU,GAAG;AAChC;AAAA,EACF;AAGA,QAAM,uBAAuB,4BAA4B,UAAU;AAEnE,aAAW,EAAE,WAAW,UAAA,KAAe,sBAAsB;AAC3D,wBAAoB,WAAW,WAAW,UAAU;AAAA,EACtD;AACF;AAKA,SAAS,4BACP,YACwD;AACxD,QAAM,UAAkE,CAAA;AAExE,WAAS,sBAAsB,MAA6B;AAC1D,QAAI,KAAK,SAAS,QAAQ;AACxB;AAAA,IACF;AAEA,UAAM,OAAO;AAGb,QAAI,KAAK,SAAS,OAAO;AACvB,iBAAW,OAAO,KAAK,MAAM;AAC3B,8BAAsB,GAAG;AAAA,MAC3B;AACA;AAAA,IACF;AAGA,UAAM,sBAAsB,CAAC,MAAM,MAAM,OAAO,MAAM,OAAO,IAAI;AACjE,QAAI,CAAC,oBAAoB,SAAS,KAAK,IAAI,GAAG;AAC5C;AAAA,IACF;AAGA,QAAI,KAAK,KAAK,SAAS,KAAK,KAAK,KAAK,CAAC,EAAE,SAAS,OAAO;AACvD;AAAA,IACF;AAEA,UAAM,WAAW,KAAK,KAAK,CAAC;AAC5B,UAAM,YAAY,SAAS;AAG3B,QAAI,UAAU,WAAW,GAAG;AAC1B;AAAA,IACF;AAIA,UAAM,YAAY,UAAU,KAAK,GAAG;AACpC,YAAQ,KAAK,EAAE,WAAW,UAAA,CAAW;AAAA,EACvC;AAEA,wBAAsB,UAAU;AAChC,SAAO;AACT;"}

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

@@ -163,14 +163,14 @@ export interface LocalStorageCollectionUtils extends UtilsRecord {
  */
 export declare function localStorageCollectionOptions<T extends StandardSchemaV1, TKey extends string | number = string | number>(config: LocalStorageCollectionConfig<InferSchemaOutput<T>, T, TKey> & {
     schema: T;
-}): CollectionConfig<InferSchemaOutput<T>, TKey, T> & {
+}): CollectionConfig<InferSchemaOutput<T>, TKey, T, LocalStorageCollectionUtils> & {
     id: string;
     utils: LocalStorageCollectionUtils;
     schema: T;
 };
 export declare function localStorageCollectionOptions<T extends object, TKey extends string | number = string | number>(config: LocalStorageCollectionConfig<T, never, TKey> & {
     schema?: never;
-}): CollectionConfig<T, TKey> & {
+}): CollectionConfig<T, TKey, never, LocalStorageCollectionUtils> & {
     id: string;
     utils: LocalStorageCollectionUtils;
     schema?: never;

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  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\nexport interface Parser {\n  parse: (data: string) => unknown\n  stringify: (data: unknown) => string\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   * Parser to use for serializing and deserializing data to and from storage\n   * Defaults to JSON\n   */\n  parser?: Parser\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 parser - The parser to use for serialization\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(\n  parser: Parser,\n  value: any,\n  operation: string\n): void {\n  try {\n    parser.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  // Default to JSON parser if no parser is provided\n  const parser = config.parser || JSON\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    parser,\n    config.getKey,\n    lastKnownData\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 = parser.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(parser, 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    // Use lastKnownData (in-memory cache) instead of reading from storage\n    // Add new items with version keys\n    params.transaction.mutations.forEach((mutation) => {\n      // Use the engine's pre-computed key for consistency\n      const key = mutation.key\n      const storedItem: StoredItem<any> = {\n        versionKey: generateUuid(),\n        data: mutation.modified,\n      }\n      lastKnownData.set(key, storedItem)\n    })\n\n    // Save to storage\n    saveToStorage(lastKnownData)\n\n    // Confirm mutations through sync interface (moves from optimistic to synced state)\n    // without reloading from storage\n    sync.confirmOperationsSync(params.transaction.mutations)\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(parser, 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    // Use lastKnownData (in-memory cache) instead of reading from storage\n    // Update items with new version keys\n    params.transaction.mutations.forEach((mutation) => {\n      // Use the engine's pre-computed key for consistency\n      const key = mutation.key\n      const storedItem: StoredItem<any> = {\n        versionKey: generateUuid(),\n        data: mutation.modified,\n      }\n      lastKnownData.set(key, storedItem)\n    })\n\n    // Save to storage\n    saveToStorage(lastKnownData)\n\n    // Confirm mutations through sync interface (moves from optimistic to synced state)\n    // without reloading from storage\n    sync.confirmOperationsSync(params.transaction.mutations)\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    // Use lastKnownData (in-memory cache) instead of reading from storage\n    // Remove items\n    params.transaction.mutations.forEach((mutation) => {\n      // Use the engine's pre-computed key for consistency\n      const key = mutation.key\n      lastKnownData.delete(key)\n    })\n\n    // Save to storage\n    saveToStorage(lastKnownData)\n\n    // Confirm mutations through sync interface (moves from optimistic to synced state)\n    // without reloading from storage\n    sync.confirmOperationsSync(params.transaction.mutations)\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(parser, mutation.modified, mutation.type)\n          break\n        case `delete`:\n          validateJsonSerializable(parser, mutation.original, mutation.type)\n          break\n      }\n    }\n\n    // Use lastKnownData (in-memory cache) instead of reading from storage\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          lastKnownData.set(key, storedItem)\n          break\n        }\n        case `delete`: {\n          lastKnownData.delete(key)\n          break\n        }\n      }\n    }\n\n    // Save to storage\n    saveToStorage(lastKnownData)\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 parser - The parser to use for deserializing the data\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  parser: Parser\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 = parser.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  parser: Parser,\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, parser)\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(parser, 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, parser)\n      if (initialData.size > 0) {\n        begin()\n        initialData.forEach((storedItem) => {\n          validateJsonSerializable(parser, 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\nexport interface Parser {\n  parse: (data: string) => unknown\n  stringify: (data: unknown) => string\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   * Parser to use for serializing and deserializing data to and from storage\n   * Defaults to JSON\n   */\n  parser?: Parser\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 parser - The parser to use for serialization\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(\n  parser: Parser,\n  value: any,\n  operation: string\n): void {\n  try {\n    parser.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<\n  InferSchemaOutput<T>,\n  TKey,\n  T,\n  LocalStorageCollectionUtils\n> & {\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, never, LocalStorageCollectionUtils> & {\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<\n  CollectionConfig<any, string | number, any, LocalStorageCollectionUtils>,\n  `id`\n> & {\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  // Default to JSON parser if no parser is provided\n  const parser = config.parser || JSON\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    parser,\n    config.getKey,\n    lastKnownData\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 = parser.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(parser, 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    // Use lastKnownData (in-memory cache) instead of reading from storage\n    // Add new items with version keys\n    params.transaction.mutations.forEach((mutation) => {\n      // Use the engine's pre-computed key for consistency\n      const key = mutation.key\n      const storedItem: StoredItem<any> = {\n        versionKey: generateUuid(),\n        data: mutation.modified,\n      }\n      lastKnownData.set(key, storedItem)\n    })\n\n    // Save to storage\n    saveToStorage(lastKnownData)\n\n    // Confirm mutations through sync interface (moves from optimistic to synced state)\n    // without reloading from storage\n    sync.confirmOperationsSync(params.transaction.mutations)\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(parser, 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    // Use lastKnownData (in-memory cache) instead of reading from storage\n    // Update items with new version keys\n    params.transaction.mutations.forEach((mutation) => {\n      // Use the engine's pre-computed key for consistency\n      const key = mutation.key\n      const storedItem: StoredItem<any> = {\n        versionKey: generateUuid(),\n        data: mutation.modified,\n      }\n      lastKnownData.set(key, storedItem)\n    })\n\n    // Save to storage\n    saveToStorage(lastKnownData)\n\n    // Confirm mutations through sync interface (moves from optimistic to synced state)\n    // without reloading from storage\n    sync.confirmOperationsSync(params.transaction.mutations)\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    // Use lastKnownData (in-memory cache) instead of reading from storage\n    // Remove items\n    params.transaction.mutations.forEach((mutation) => {\n      // Use the engine's pre-computed key for consistency\n      const key = mutation.key\n      lastKnownData.delete(key)\n    })\n\n    // Save to storage\n    saveToStorage(lastKnownData)\n\n    // Confirm mutations through sync interface (moves from optimistic to synced state)\n    // without reloading from storage\n    sync.confirmOperationsSync(params.transaction.mutations)\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(parser, mutation.modified, mutation.type)\n          break\n        case `delete`:\n          validateJsonSerializable(parser, mutation.original, mutation.type)\n          break\n      }\n    }\n\n    // Use lastKnownData (in-memory cache) instead of reading from storage\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          lastKnownData.set(key, storedItem)\n          break\n        }\n        case `delete`: {\n          lastKnownData.delete(key)\n          break\n        }\n      }\n    }\n\n    // Save to storage\n    saveToStorage(lastKnownData)\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 parser - The parser to use for deserializing the data\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  parser: Parser\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 = parser.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  parser: Parser,\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, parser)\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(parser, 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, parser)\n      if (initialData.size > 0) {\n        begin()\n        initialData.forEach((storedItem) => {\n          validateJsonSerializable(parser, 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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"}

package/dist/esm/query/builder/functions.d.ts

@@ -54,4 +54,9 @@ export declare function max<T extends ExpressionLike>(arg: T): AggregateReturnTy
  * List of comparison function names that can be used with indexes
  */
 export declare const comparisonFunctions: readonly ["eq", "gt", "gte", "lt", "lte", "in", "like", "ilike"];
+/**
+ * All supported operator names in TanStack DB expressions
+ */
+export declare const operators: readonly ["eq", "gt", "gte", "lt", "lte", "in", "like", "ilike", "and", "or", "not", "isNull", "isUndefined", "upper", "lower", "length", "concat", "add", "coalesce", "count", "avg", "sum", "min", "max"];
+export type OperatorName = (typeof operators)[number];
 export {};

package/dist/esm/query/builder/functions.js

@@ -99,6 +99,39 @@ const comparisonFunctions = [
   `like`,
   `ilike`
 ];
+const operators = [
+  // Comparison operators
+  `eq`,
+  `gt`,
+  `gte`,
+  `lt`,
+  `lte`,
+  `in`,
+  `like`,
+  `ilike`,
+  // Logical operators
+  `and`,
+  `or`,
+  `not`,
+  // Null checking
+  `isNull`,
+  `isUndefined`,
+  // String functions
+  `upper`,
+  `lower`,
+  `length`,
+  `concat`,
+  // Numeric functions
+  `add`,
+  // Utility functions
+  `coalesce`,
+  // Aggregate functions
+  `count`,
+  `avg`,
+  `sum`,
+  `min`,
+  `max`
+];
 export {
   add,
   and,
@@ -122,6 +155,7 @@ export {
   max,
   min,
   not,
+  operators,
   or,
   sum,
   upper