@tanstack/db 0.4.9 → 0.4.11

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  OnLoadMoreOptions,\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 = {},\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 = {},\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 = {},\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 = {},\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 = {},\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  // Copy utils to both top level and .utils namespace\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  private _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    })\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   * 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   * Requests the sync layer to load more data.\n   * @param options Options to control what data is being loaded\n   * @returns If data loading is asynchronous, this method returns a promise that resolves when the data is loaded.\n   *          If data loading is synchronous, the data is loaded when the method returns.\n   */\n  public syncMore(options: OnLoadMoreOptions): void | Promise<void> {\n    if (this._sync.syncOnLoadMoreFn) {\n      return this._sync.syncOnLoadMoreFn(options)\n    }\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  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  // Copy utils to both top level and .utils namespace\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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"}

package/dist/esm/collection/subscription.d.ts

@@ -1,6 +1,7 @@
+import { EventEmitter } from '../event-emitter.js';
 import { BasicExpression, OrderBy } from '../query/ir.js';
 import { IndexInterface } from '../indexes/base-index.js';
-import { ChangeMessage } from '../types.js';
+import { ChangeMessage, Subscription, SubscriptionEvents, SubscriptionStatus, SubscriptionUnsubscribedEvent } from '../types.js';
 import { CollectionImpl } from './index.js';
 type RequestSnapshotOptions = {
     where?: BasicExpression<boolean>;
@@ -12,12 +13,13 @@ type RequestLimitedSnapshotOptions = {
     minValue?: any;
 };
 type CollectionSubscriptionOptions = {
+    includeInitialState?: boolean;
     /** Pre-compiled expression for filtering changes */
     whereExpression?: BasicExpression<boolean>;
     /** Callback to call when the subscription is unsubscribed */
-    onUnsubscribe?: () => void;
+    onUnsubscribe?: (event: SubscriptionUnsubscribedEvent) => void;
 };
-export declare class CollectionSubscription {
+export declare class CollectionSubscription extends EventEmitter<SubscriptionEvents> implements Subscription {
     private collection;
     private callback;
     private options;
@@ -26,8 +28,19 @@ export declare class CollectionSubscription {
     private sentKeys;
     private filteredCallback;
     private orderByIndex;
+    private _status;
+    private pendingLoadSubsetPromises;
+    get status(): SubscriptionStatus;
     constructor(collection: CollectionImpl<any, any, any, any, any>, callback: (changes: Array<ChangeMessage<any, any>>) => void, options: CollectionSubscriptionOptions);
     setOrderByIndex(index: IndexInterface<any>): void;
+    /**
+     * Set subscription status and emit events if changed
+     */
+    private setStatus;
+    /**
+     * Track a loadSubset promise and manage loading status
+     */
+    private trackLoadSubsetPromise;
     hasLoadedInitialState(): boolean;
     hasSentAtLeastOneSnapshot(): boolean;
     emitEvents(changes: Array<ChangeMessage<any, any>>): void;

package/dist/esm/collection/subscription.js

@@ -1,15 +1,22 @@
 import { ensureIndexForExpression } from "../indexes/auto-index.js";
 import { and, gt, lt } from "../query/builder/functions.js";
 import { Value } from "../query/ir.js";
+import { EventEmitter } from "../event-emitter.js";
 import { createFilteredCallback, createFilterFunctionFromExpression } from "./change-events.js";
-class CollectionSubscription {
+class CollectionSubscription extends EventEmitter {
   constructor(collection, callback, options) {
+    super();
     this.collection = collection;
     this.callback = callback;
     this.options = options;
     this.loadedInitialState = false;
     this.snapshotSent = false;
     this.sentKeys = /* @__PURE__ */ new Set();
+    this._status = `ready`;
+    this.pendingLoadSubsetPromises = /* @__PURE__ */ new Set();
+    if (options.onUnsubscribe) {
+      this.on(`unsubscribed`, (event) => options.onUnsubscribe(event));
+    }
     if (options.whereExpression) {
       ensureIndexForExpression(options.whereExpression, this.collection);
     }
@@ -20,9 +27,50 @@ class CollectionSubscription {
     this.callback = callbackWithSentKeysTracking;
     this.filteredCallback = options.whereExpression ? createFilteredCallback(this.callback, options) : this.callback;
   }
+  get status() {
+    return this._status;
+  }
   setOrderByIndex(index) {
     this.orderByIndex = index;
   }
+  /**
+   * Set subscription status and emit events if changed
+   */
+  setStatus(newStatus) {
+    if (this._status === newStatus) {
+      return;
+    }
+    const previousStatus = this._status;
+    this._status = newStatus;
+    this.emitInner(`status:change`, {
+      type: `status:change`,
+      subscription: this,
+      previousStatus,
+      status: newStatus
+    });
+    const eventKey = `status:${newStatus}`;
+    this.emitInner(eventKey, {
+      type: eventKey,
+      subscription: this,
+      previousStatus,
+      status: newStatus
+    });
+  }
+  /**
+   * Track a loadSubset promise and manage loading status
+   */
+  trackLoadSubsetPromise(syncResult) {
+    if (syncResult instanceof Promise) {
+      this.pendingLoadSubsetPromises.add(syncResult);
+      this.setStatus(`loadingSubset`);
+      syncResult.finally(() => {
+        this.pendingLoadSubsetPromises.delete(syncResult);
+        if (this.pendingLoadSubsetPromises.size === 0) {
+          this.setStatus(`ready`);
+        }
+      });
+    }
+  }
   hasLoadedInitialState() {
     return this.loadedInitialState;
   }
@@ -62,9 +110,11 @@ class CollectionSubscription {
     } else {
       this.loadedInitialState = true;
     }
-    this.collection.syncMore({
-      where: stateOpts.where
+    const syncResult = this.collection._sync.loadSubset({
+      where: stateOpts.where,
+      subscription: this
     });
+    this.trackLoadSubsetPromise(syncResult);
     const snapshot = this.collection.currentStateAsChanges(stateOpts);
     if (snapshot === void 0) {
       return false;
@@ -131,11 +181,13 @@ class CollectionSubscription {
       const valueFilter = operator(expression, new Value(minValue));
       whereWithValueFilter = where ? and(where, valueFilter) : valueFilter;
     }
-    this.collection.syncMore({
+    const syncResult = this.collection._sync.loadSubset({
       where: whereWithValueFilter,
       limit,
-      orderBy
+      orderBy,
+      subscription: this
     });
+    this.trackLoadSubsetPromise(syncResult);
   }
   /**
    * Filters and flips changes for keys that have not been sent yet.
@@ -170,7 +222,11 @@ class CollectionSubscription {
     }
   }
   unsubscribe() {
-    this.options.onUnsubscribe?.();
+    this.emitInner(`unsubscribed`, {
+      type: `unsubscribed`,
+      subscription: this
+    });
+    this.clearListeners();
   }
 }
 export {

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

@@ -1 +1 @@
-{"version":3,"file":"subscription.js","sources":["../../../src/collection/subscription.ts"],"sourcesContent":["import { ensureIndexForExpression } from \"../indexes/auto-index.js\"\nimport { and, gt, lt } from \"../query/builder/functions.js\"\nimport { Value } from \"../query/ir.js\"\nimport {\n  createFilterFunctionFromExpression,\n  createFilteredCallback,\n} from \"./change-events.js\"\nimport type { BasicExpression, OrderBy } from \"../query/ir.js\"\nimport type { IndexInterface } from \"../indexes/base-index.js\"\nimport type { ChangeMessage } from \"../types.js\"\nimport type { CollectionImpl } from \"./index.js\"\n\ntype RequestSnapshotOptions = {\n  where?: BasicExpression<boolean>\n  optimizedOnly?: boolean\n}\n\ntype RequestLimitedSnapshotOptions = {\n  orderBy: OrderBy\n  limit: number\n  minValue?: any\n}\n\ntype CollectionSubscriptionOptions = {\n  /** Pre-compiled expression for filtering changes */\n  whereExpression?: BasicExpression<boolean>\n  /** Callback to call when the subscription is unsubscribed */\n  onUnsubscribe?: () => void\n}\n\nexport class CollectionSubscription {\n  private loadedInitialState = false\n\n  // Flag to indicate that we have sent at least 1 snapshot.\n  // While `snapshotSent` is false we filter out all changes from subscription to the collection.\n  private snapshotSent = false\n\n  // Keep track of the keys we've sent (needed for join and orderBy optimizations)\n  private sentKeys = new Set<string | number>()\n\n  private filteredCallback: (changes: Array<ChangeMessage<any, any>>) => void\n\n  private orderByIndex: IndexInterface<string | number> | undefined\n\n  constructor(\n    private collection: CollectionImpl<any, any, any, any, any>,\n    private callback: (changes: Array<ChangeMessage<any, any>>) => void,\n    private options: CollectionSubscriptionOptions\n  ) {\n    // Auto-index for where expressions if enabled\n    if (options.whereExpression) {\n      ensureIndexForExpression(options.whereExpression, this.collection)\n    }\n\n    const callbackWithSentKeysTracking = (\n      changes: Array<ChangeMessage<any, any>>\n    ) => {\n      callback(changes)\n      this.trackSentKeys(changes)\n    }\n\n    this.callback = callbackWithSentKeysTracking\n\n    // Create a filtered callback if where clause is provided\n    this.filteredCallback = options.whereExpression\n      ? createFilteredCallback(this.callback, options)\n      : this.callback\n  }\n\n  setOrderByIndex(index: IndexInterface<any>) {\n    this.orderByIndex = index\n  }\n\n  hasLoadedInitialState() {\n    return this.loadedInitialState\n  }\n\n  hasSentAtLeastOneSnapshot() {\n    return this.snapshotSent\n  }\n\n  emitEvents(changes: Array<ChangeMessage<any, any>>) {\n    const newChanges = this.filterAndFlipChanges(changes)\n    this.filteredCallback(newChanges)\n  }\n\n  /**\n   * Sends the snapshot to the callback.\n   * Returns a boolean indicating if it succeeded.\n   * It can only fail if there is no index to fulfill the request\n   * and the optimizedOnly option is set to true,\n   * or, the entire state was already loaded.\n   */\n  requestSnapshot(opts?: RequestSnapshotOptions): boolean {\n    if (this.loadedInitialState) {\n      // Subscription was deoptimized so we already sent the entire initial state\n      return false\n    }\n\n    const stateOpts: RequestSnapshotOptions = {\n      where: this.options.whereExpression,\n      optimizedOnly: opts?.optimizedOnly ?? false,\n    }\n\n    if (opts) {\n      if (`where` in opts) {\n        const snapshotWhereExp = opts.where\n        if (stateOpts.where) {\n          // Combine the two where expressions\n          const subWhereExp = stateOpts.where\n          const combinedWhereExp = and(subWhereExp, snapshotWhereExp)\n          stateOpts.where = combinedWhereExp\n        } else {\n          stateOpts.where = snapshotWhereExp\n        }\n      }\n    } else {\n      // No options provided so it's loading the entire initial state\n      this.loadedInitialState = true\n    }\n\n    // Request the sync layer to load more data\n    // don't await it, we will load the data into the collection when it comes in\n    this.collection.syncMore({\n      where: stateOpts.where,\n    })\n\n    // Also load data immediately from the collection\n    const snapshot = this.collection.currentStateAsChanges(stateOpts)\n\n    if (snapshot === undefined) {\n      // Couldn't load from indexes\n      return false\n    }\n\n    // Only send changes that have not been sent yet\n    const filteredSnapshot = snapshot.filter(\n      (change) => !this.sentKeys.has(change.key)\n    )\n\n    this.snapshotSent = true\n    this.callback(filteredSnapshot)\n    return true\n  }\n\n  /**\n   * Sends a snapshot that is limited to the first `limit` rows that fulfill the `where` clause and are bigger than `minValue`.\n   * Requires a range index to be set with `setOrderByIndex` prior to calling this method.\n   * It uses that range index to load the items in the order of the index.\n   * Note: it does not send keys that have already been sent before.\n   */\n  requestLimitedSnapshot({\n    orderBy,\n    limit,\n    minValue,\n  }: RequestLimitedSnapshotOptions) {\n    if (!limit) throw new Error(`limit is required`)\n\n    if (!this.orderByIndex) {\n      throw new Error(\n        `Ordered snapshot was requested but no index was found. You have to call setOrderByIndex before requesting an ordered snapshot.`\n      )\n    }\n\n    const index = this.orderByIndex\n    const where = this.options.whereExpression\n    const whereFilterFn = where\n      ? createFilterFunctionFromExpression(where)\n      : undefined\n\n    const filterFn = (key: string | number): boolean => {\n      if (this.sentKeys.has(key)) {\n        return false\n      }\n\n      const value = this.collection.get(key)\n      if (value === undefined) {\n        return false\n      }\n\n      return whereFilterFn?.(value) ?? true\n    }\n\n    let biggestObservedValue = minValue\n    const changes: Array<ChangeMessage<any, string | number>> = []\n    let keys: Array<string | number> = index.take(limit, minValue, filterFn)\n\n    const valuesNeeded = () => Math.max(limit - changes.length, 0)\n    const collectionExhausted = () => keys.length === 0\n\n    while (valuesNeeded() > 0 && !collectionExhausted()) {\n      for (const key of keys) {\n        const value = this.collection.get(key)!\n        changes.push({\n          type: `insert`,\n          key,\n          value,\n        })\n        biggestObservedValue = value\n      }\n\n      keys = index.take(valuesNeeded(), biggestObservedValue, filterFn)\n    }\n\n    this.callback(changes)\n\n    let whereWithValueFilter = where\n    if (typeof minValue !== `undefined`) {\n      // Only request data that we haven't seen yet (i.e. is bigger than the minValue)\n      const { expression, compareOptions } = orderBy[0]!\n      const operator = compareOptions.direction === `asc` ? gt : lt\n      const valueFilter = operator(expression, new Value(minValue))\n      whereWithValueFilter = where ? and(where, valueFilter) : valueFilter\n    }\n\n    // Request the sync layer to load more data\n    // don't await it, we will load the data into the collection when it comes in\n    this.collection.syncMore({\n      where: whereWithValueFilter,\n      limit,\n      orderBy,\n    })\n  }\n\n  /**\n   * Filters and flips changes for keys that have not been sent yet.\n   * Deletes are filtered out for keys that have not been sent yet.\n   * Updates are flipped into inserts for keys that have not been sent yet.\n   */\n  private filterAndFlipChanges(changes: Array<ChangeMessage<any, any>>) {\n    if (this.loadedInitialState) {\n      // We loaded the entire initial state\n      // so no need to filter or flip changes\n      return changes\n    }\n\n    const newChanges = []\n    for (const change of changes) {\n      let newChange = change\n      if (!this.sentKeys.has(change.key)) {\n        if (change.type === `update`) {\n          newChange = { ...change, type: `insert`, previousValue: undefined }\n        } else if (change.type === `delete`) {\n          // filter out deletes for keys that have not been sent\n          continue\n        }\n        this.sentKeys.add(change.key)\n      }\n      newChanges.push(newChange)\n    }\n    return newChanges\n  }\n\n  private trackSentKeys(changes: Array<ChangeMessage<any, string | number>>) {\n    if (this.loadedInitialState) {\n      // No need to track sent keys if we loaded the entire state.\n      // Since we sent everything, all keys must have been observed.\n      return\n    }\n\n    for (const change of changes) {\n      this.sentKeys.add(change.key)\n    }\n  }\n\n  unsubscribe() {\n    this.options.onUnsubscribe?.()\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"subscription.js","sources":["../../../src/collection/subscription.ts"],"sourcesContent":["import { ensureIndexForExpression } from \"../indexes/auto-index.js\"\nimport { and, gt, lt } from \"../query/builder/functions.js\"\nimport { Value } from \"../query/ir.js\"\nimport { EventEmitter } from \"../event-emitter.js\"\nimport {\n  createFilterFunctionFromExpression,\n  createFilteredCallback,\n} from \"./change-events.js\"\nimport type { BasicExpression, OrderBy } from \"../query/ir.js\"\nimport type { IndexInterface } from \"../indexes/base-index.js\"\nimport type {\n  ChangeMessage,\n  Subscription,\n  SubscriptionEvents,\n  SubscriptionStatus,\n  SubscriptionUnsubscribedEvent,\n} from \"../types.js\"\nimport type { CollectionImpl } from \"./index.js\"\n\ntype RequestSnapshotOptions = {\n  where?: BasicExpression<boolean>\n  optimizedOnly?: boolean\n}\n\ntype RequestLimitedSnapshotOptions = {\n  orderBy: OrderBy\n  limit: number\n  minValue?: any\n}\n\ntype CollectionSubscriptionOptions = {\n  includeInitialState?: boolean\n  /** Pre-compiled expression for filtering changes */\n  whereExpression?: BasicExpression<boolean>\n  /** Callback to call when the subscription is unsubscribed */\n  onUnsubscribe?: (event: SubscriptionUnsubscribedEvent) => void\n}\n\nexport class CollectionSubscription\n  extends EventEmitter<SubscriptionEvents>\n  implements Subscription\n{\n  private loadedInitialState = false\n\n  // Flag to indicate that we have sent at least 1 snapshot.\n  // While `snapshotSent` is false we filter out all changes from subscription to the collection.\n  private snapshotSent = false\n\n  // Keep track of the keys we've sent (needed for join and orderBy optimizations)\n  private sentKeys = new Set<string | number>()\n\n  private filteredCallback: (changes: Array<ChangeMessage<any, any>>) => void\n\n  private orderByIndex: IndexInterface<string | number> | undefined\n\n  // Status tracking\n  private _status: SubscriptionStatus = `ready`\n  private pendingLoadSubsetPromises: Set<Promise<void>> = new Set()\n\n  public get status(): SubscriptionStatus {\n    return this._status\n  }\n\n  constructor(\n    private collection: CollectionImpl<any, any, any, any, any>,\n    private callback: (changes: Array<ChangeMessage<any, any>>) => void,\n    private options: CollectionSubscriptionOptions\n  ) {\n    super()\n    if (options.onUnsubscribe) {\n      this.on(`unsubscribed`, (event) => options.onUnsubscribe!(event))\n    }\n\n    // Auto-index for where expressions if enabled\n    if (options.whereExpression) {\n      ensureIndexForExpression(options.whereExpression, this.collection)\n    }\n\n    const callbackWithSentKeysTracking = (\n      changes: Array<ChangeMessage<any, any>>\n    ) => {\n      callback(changes)\n      this.trackSentKeys(changes)\n    }\n\n    this.callback = callbackWithSentKeysTracking\n\n    // Create a filtered callback if where clause is provided\n    this.filteredCallback = options.whereExpression\n      ? createFilteredCallback(this.callback, options)\n      : this.callback\n  }\n\n  setOrderByIndex(index: IndexInterface<any>) {\n    this.orderByIndex = index\n  }\n\n  /**\n   * Set subscription status and emit events if changed\n   */\n  private setStatus(newStatus: SubscriptionStatus) {\n    if (this._status === newStatus) {\n      return // No change\n    }\n\n    const previousStatus = this._status\n    this._status = newStatus\n\n    // Emit status:change event\n    this.emitInner(`status:change`, {\n      type: `status:change`,\n      subscription: this,\n      previousStatus,\n      status: newStatus,\n    })\n\n    // Emit specific status event\n    const eventKey: `status:${SubscriptionStatus}` = `status:${newStatus}`\n    this.emitInner(eventKey, {\n      type: eventKey,\n      subscription: this,\n      previousStatus,\n      status: newStatus,\n    } as SubscriptionEvents[typeof eventKey])\n  }\n\n  /**\n   * Track a loadSubset promise and manage loading status\n   */\n  private trackLoadSubsetPromise(syncResult: Promise<void> | true) {\n    // Track the promise if it's actually a promise (async work)\n    if (syncResult instanceof Promise) {\n      this.pendingLoadSubsetPromises.add(syncResult)\n      this.setStatus(`loadingSubset`)\n\n      syncResult.finally(() => {\n        this.pendingLoadSubsetPromises.delete(syncResult)\n        if (this.pendingLoadSubsetPromises.size === 0) {\n          this.setStatus(`ready`)\n        }\n      })\n    }\n  }\n\n  hasLoadedInitialState() {\n    return this.loadedInitialState\n  }\n\n  hasSentAtLeastOneSnapshot() {\n    return this.snapshotSent\n  }\n\n  emitEvents(changes: Array<ChangeMessage<any, any>>) {\n    const newChanges = this.filterAndFlipChanges(changes)\n    this.filteredCallback(newChanges)\n  }\n\n  /**\n   * Sends the snapshot to the callback.\n   * Returns a boolean indicating if it succeeded.\n   * It can only fail if there is no index to fulfill the request\n   * and the optimizedOnly option is set to true,\n   * or, the entire state was already loaded.\n   */\n  requestSnapshot(opts?: RequestSnapshotOptions): boolean {\n    if (this.loadedInitialState) {\n      // Subscription was deoptimized so we already sent the entire initial state\n      return false\n    }\n\n    const stateOpts: RequestSnapshotOptions = {\n      where: this.options.whereExpression,\n      optimizedOnly: opts?.optimizedOnly ?? false,\n    }\n\n    if (opts) {\n      if (`where` in opts) {\n        const snapshotWhereExp = opts.where\n        if (stateOpts.where) {\n          // Combine the two where expressions\n          const subWhereExp = stateOpts.where\n          const combinedWhereExp = and(subWhereExp, snapshotWhereExp)\n          stateOpts.where = combinedWhereExp\n        } else {\n          stateOpts.where = snapshotWhereExp\n        }\n      }\n    } else {\n      // No options provided so it's loading the entire initial state\n      this.loadedInitialState = true\n    }\n\n    // Request the sync layer to load more data\n    // don't await it, we will load the data into the collection when it comes in\n    const syncResult = this.collection._sync.loadSubset({\n      where: stateOpts.where,\n      subscription: this,\n    })\n\n    this.trackLoadSubsetPromise(syncResult)\n\n    // Also load data immediately from the collection\n    const snapshot = this.collection.currentStateAsChanges(stateOpts)\n\n    if (snapshot === undefined) {\n      // Couldn't load from indexes\n      return false\n    }\n\n    // Only send changes that have not been sent yet\n    const filteredSnapshot = snapshot.filter(\n      (change) => !this.sentKeys.has(change.key)\n    )\n\n    this.snapshotSent = true\n    this.callback(filteredSnapshot)\n    return true\n  }\n\n  /**\n   * Sends a snapshot that is limited to the first `limit` rows that fulfill the `where` clause and are bigger than `minValue`.\n   * Requires a range index to be set with `setOrderByIndex` prior to calling this method.\n   * It uses that range index to load the items in the order of the index.\n   * Note: it does not send keys that have already been sent before.\n   */\n  requestLimitedSnapshot({\n    orderBy,\n    limit,\n    minValue,\n  }: RequestLimitedSnapshotOptions) {\n    if (!limit) throw new Error(`limit is required`)\n\n    if (!this.orderByIndex) {\n      throw new Error(\n        `Ordered snapshot was requested but no index was found. You have to call setOrderByIndex before requesting an ordered snapshot.`\n      )\n    }\n\n    const index = this.orderByIndex\n    const where = this.options.whereExpression\n    const whereFilterFn = where\n      ? createFilterFunctionFromExpression(where)\n      : undefined\n\n    const filterFn = (key: string | number): boolean => {\n      if (this.sentKeys.has(key)) {\n        return false\n      }\n\n      const value = this.collection.get(key)\n      if (value === undefined) {\n        return false\n      }\n\n      return whereFilterFn?.(value) ?? true\n    }\n\n    let biggestObservedValue = minValue\n    const changes: Array<ChangeMessage<any, string | number>> = []\n    let keys: Array<string | number> = index.take(limit, minValue, filterFn)\n\n    const valuesNeeded = () => Math.max(limit - changes.length, 0)\n    const collectionExhausted = () => keys.length === 0\n\n    while (valuesNeeded() > 0 && !collectionExhausted()) {\n      for (const key of keys) {\n        const value = this.collection.get(key)!\n        changes.push({\n          type: `insert`,\n          key,\n          value,\n        })\n        biggestObservedValue = value\n      }\n\n      keys = index.take(valuesNeeded(), biggestObservedValue, filterFn)\n    }\n\n    this.callback(changes)\n\n    let whereWithValueFilter = where\n    if (typeof minValue !== `undefined`) {\n      // Only request data that we haven't seen yet (i.e. is bigger than the minValue)\n      const { expression, compareOptions } = orderBy[0]!\n      const operator = compareOptions.direction === `asc` ? gt : lt\n      const valueFilter = operator(expression, new Value(minValue))\n      whereWithValueFilter = where ? and(where, valueFilter) : valueFilter\n    }\n\n    // Request the sync layer to load more data\n    // don't await it, we will load the data into the collection when it comes in\n    const syncResult = this.collection._sync.loadSubset({\n      where: whereWithValueFilter,\n      limit,\n      orderBy,\n      subscription: this,\n    })\n\n    this.trackLoadSubsetPromise(syncResult)\n  }\n\n  /**\n   * Filters and flips changes for keys that have not been sent yet.\n   * Deletes are filtered out for keys that have not been sent yet.\n   * Updates are flipped into inserts for keys that have not been sent yet.\n   */\n  private filterAndFlipChanges(changes: Array<ChangeMessage<any, any>>) {\n    if (this.loadedInitialState) {\n      // We loaded the entire initial state\n      // so no need to filter or flip changes\n      return changes\n    }\n\n    const newChanges = []\n    for (const change of changes) {\n      let newChange = change\n      if (!this.sentKeys.has(change.key)) {\n        if (change.type === `update`) {\n          newChange = { ...change, type: `insert`, previousValue: undefined }\n        } else if (change.type === `delete`) {\n          // filter out deletes for keys that have not been sent\n          continue\n        }\n        this.sentKeys.add(change.key)\n      }\n      newChanges.push(newChange)\n    }\n    return newChanges\n  }\n\n  private trackSentKeys(changes: Array<ChangeMessage<any, string | number>>) {\n    if (this.loadedInitialState) {\n      // No need to track sent keys if we loaded the entire state.\n      // Since we sent everything, all keys must have been observed.\n      return\n    }\n\n    for (const change of changes) {\n      this.sentKeys.add(change.key)\n    }\n  }\n\n  unsubscribe() {\n    this.emitInner(`unsubscribed`, {\n      type: `unsubscribed`,\n      subscription: this,\n    })\n    // Clear all event listeners to prevent memory leaks\n    this.clearListeners()\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/collection/sync.d.ts

@@ -1,17 +1,21 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { CollectionConfig, OnLoadMoreOptions } from '../types.js';
+import { CollectionConfig, LoadSubsetOptions } from '../types.js';
 import { CollectionImpl } from './index.js';
 import { CollectionStateManager } from './state.js';
 import { CollectionLifecycleManager } from './lifecycle.js';
+import { CollectionEventsManager } from './events.js';
 export declare class CollectionSyncManager<TOutput extends object = Record<string, unknown>, TKey extends string | number = string | number, TSchema extends StandardSchemaV1 = StandardSchemaV1, TInput extends object = TOutput> {
     private collection;
     private state;
     private lifecycle;
+    private _events;
     private config;
     private id;
+    private syncMode;
     preloadPromise: Promise<void> | null;
     syncCleanupFn: (() => void) | null;
-    syncOnLoadMoreFn: ((options: OnLoadMoreOptions) => void | Promise<void>) | null;
+    syncLoadSubsetFn: ((options: LoadSubsetOptions) => true | Promise<void>) | null;
+    private pendingLoadSubsetPromises;
     /**
      * Creates a new CollectionSyncManager instance
      */
@@ -20,6 +24,7 @@ export declare class CollectionSyncManager<TOutput extends object = Record<strin
         collection: CollectionImpl<TOutput, TKey, any, TSchema, TInput>;
         state: CollectionStateManager<TOutput, TKey, TSchema, TInput>;
         lifecycle: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>;
+        events: CollectionEventsManager;
     }): void;
     /**
      * Start the sync process for this collection
@@ -31,12 +36,21 @@ export declare class CollectionSyncManager<TOutput extends object = Record<strin
      * Multiple concurrent calls will share the same promise
      */
     preload(): Promise<void>;
+    /**
+     * Gets whether the collection is currently loading more data
+     */
+    get isLoadingSubset(): boolean;
+    /**
+     * Tracks a load promise for isLoadingSubset state.
+     * @internal This is for internal coordination (e.g., live-query glue code), not for general use.
+     */
+    trackLoadPromise(promise: Promise<void>): void;
     /**
      * Requests the sync layer to load more data.
      * @param options Options to control what data is being loaded
      * @returns If data loading is asynchronous, this method returns a promise that resolves when the data is loaded.
-     *          If data loading is synchronous, the data is loaded when the method returns.
+     *          Returns true if no sync function is configured, if syncMode is 'eager', or if there is no work to do.
      */
-    syncMore(options: OnLoadMoreOptions): void | Promise<void>;
+    loadSubset(options: LoadSubsetOptions): Promise<void> | true;
     cleanup(): void;
 }

package/dist/esm/collection/sync.js

@@ -1,4 +1,4 @@
-import { NoPendingSyncTransactionWriteError, SyncTransactionAlreadyCommittedWriteError, NoPendingSyncTransactionCommitError, SyncTransactionAlreadyCommittedError, DuplicateKeySyncError, CollectionIsInErrorStateError, SyncCleanupError } from "../errors.js";
+import { NoPendingSyncTransactionWriteError, SyncTransactionAlreadyCommittedWriteError, NoPendingSyncTransactionCommitError, SyncTransactionAlreadyCommittedError, DuplicateKeySyncError, CollectionConfigurationError, CollectionIsInErrorStateError, SyncCleanupError } from "../errors.js";
 import { deepEquals } from "../utils.js";
 class CollectionSyncManager {
   /**
@@ -7,14 +7,17 @@ class CollectionSyncManager {
   constructor(config, id) {
     this.preloadPromise = null;
     this.syncCleanupFn = null;
-    this.syncOnLoadMoreFn = null;
+    this.syncLoadSubsetFn = null;
+    this.pendingLoadSubsetPromises = /* @__PURE__ */ new Set();
     this.config = config;
     this.id = id;
+    this.syncMode = config.syncMode ?? `eager`;
   }
   setDeps(deps) {
     this.collection = deps.collection;
     this.state = deps.state;
     this.lifecycle = deps.lifecycle;
+    this._events = deps.events;
   }
   /**
    * Start the sync process for this collection
@@ -102,7 +105,12 @@ class CollectionSyncManager {
         })
       );
       this.syncCleanupFn = syncRes?.cleanup ?? null;
-      this.syncOnLoadMoreFn = syncRes?.onLoadMore ?? null;
+      this.syncLoadSubsetFn = syncRes?.loadSubset ?? null;
+      if (this.syncMode === `on-demand` && !this.syncLoadSubsetFn) {
+        throw new CollectionConfigurationError(
+          `Collection "${this.id}" is configured with syncMode "on-demand" but the sync function did not return a loadSubset handler. Either provide a loadSubset handler or use syncMode "eager".`
+        );
+      }
     } catch (error) {
       this.lifecycle.setStatus(`error`);
       throw error;
@@ -139,16 +147,60 @@ class CollectionSyncManager {
     });
     return this.preloadPromise;
   }
+  /**
+   * Gets whether the collection is currently loading more data
+   */
+  get isLoadingSubset() {
+    return this.pendingLoadSubsetPromises.size > 0;
+  }
+  /**
+   * Tracks a load promise for isLoadingSubset state.
+   * @internal This is for internal coordination (e.g., live-query glue code), not for general use.
+   */
+  trackLoadPromise(promise) {
+    const loadingStarting = !this.isLoadingSubset;
+    this.pendingLoadSubsetPromises.add(promise);
+    if (loadingStarting) {
+      this._events.emit(`loadingSubset:change`, {
+        type: `loadingSubset:change`,
+        collection: this.collection,
+        isLoadingSubset: true,
+        previousIsLoadingSubset: false,
+        loadingSubsetTransition: `start`
+      });
+    }
+    promise.finally(() => {
+      const loadingEnding = this.pendingLoadSubsetPromises.size === 1 && this.pendingLoadSubsetPromises.has(promise);
+      this.pendingLoadSubsetPromises.delete(promise);
+      if (loadingEnding) {
+        this._events.emit(`loadingSubset:change`, {
+          type: `loadingSubset:change`,
+          collection: this.collection,
+          isLoadingSubset: false,
+          previousIsLoadingSubset: true,
+          loadingSubsetTransition: `end`
+        });
+      }
+    });
+  }
   /**
    * Requests the sync layer to load more data.
    * @param options Options to control what data is being loaded
    * @returns If data loading is asynchronous, this method returns a promise that resolves when the data is loaded.
-   *          If data loading is synchronous, the data is loaded when the method returns.
+   *          Returns true if no sync function is configured, if syncMode is 'eager', or if there is no work to do.
    */
-  syncMore(options) {
-    if (this.syncOnLoadMoreFn) {
-      return this.syncOnLoadMoreFn(options);
+  loadSubset(options) {
+    if (this.syncMode === `eager`) {
+      return true;
+    }
+    if (this.syncLoadSubsetFn) {
+      const result = this.syncLoadSubsetFn(options);
+      if (result instanceof Promise) {
+        this.trackLoadPromise(result);
+        return result;
+      }
     }
+    return true;
   }
   cleanup() {
     try {

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

@@ -1 +1 @@
-{"version":3,"file":"sync.js","sources":["../../../src/collection/sync.ts"],"sourcesContent":["import {\n  CollectionIsInErrorStateError,\n  DuplicateKeySyncError,\n  NoPendingSyncTransactionCommitError,\n  NoPendingSyncTransactionWriteError,\n  SyncCleanupError,\n  SyncTransactionAlreadyCommittedError,\n  SyncTransactionAlreadyCommittedWriteError,\n} from \"../errors\"\nimport { deepEquals } from \"../utils\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\nimport type {\n  ChangeMessage,\n  CleanupFn,\n  CollectionConfig,\n  OnLoadMoreOptions,\n  SyncConfigRes,\n} from \"../types\"\nimport type { CollectionImpl } from \"./index.js\"\nimport type { CollectionStateManager } from \"./state\"\nimport type { CollectionLifecycleManager } from \"./lifecycle\"\n\nexport class CollectionSyncManager<\n  TOutput extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n  TSchema extends StandardSchemaV1 = StandardSchemaV1,\n  TInput extends object = TOutput,\n> {\n  private collection!: CollectionImpl<TOutput, TKey, any, TSchema, TInput>\n  private state!: CollectionStateManager<TOutput, TKey, TSchema, TInput>\n  private lifecycle!: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>\n  private config!: CollectionConfig<TOutput, TKey, TSchema>\n  private id: string\n\n  public preloadPromise: Promise<void> | null = null\n  public syncCleanupFn: (() => void) | null = null\n  public syncOnLoadMoreFn:\n    | ((options: OnLoadMoreOptions) => void | Promise<void>)\n    | null = null\n\n  /**\n   * Creates a new CollectionSyncManager instance\n   */\n  constructor(config: CollectionConfig<TOutput, TKey, TSchema>, id: string) {\n    this.config = config\n    this.id = id\n  }\n\n  setDeps(deps: {\n    collection: CollectionImpl<TOutput, TKey, any, TSchema, TInput>\n    state: CollectionStateManager<TOutput, TKey, TSchema, TInput>\n    lifecycle: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>\n  }) {\n    this.collection = deps.collection\n    this.state = deps.state\n    this.lifecycle = deps.lifecycle\n  }\n\n  /**\n   * Start the sync process for this collection\n   * This is called when the collection is first accessed or preloaded\n   */\n  public startSync(): void {\n    if (\n      this.lifecycle.status !== `idle` &&\n      this.lifecycle.status !== `cleaned-up`\n    ) {\n      return // Already started or in progress\n    }\n\n    this.lifecycle.setStatus(`loading`)\n\n    try {\n      const syncRes = normalizeSyncFnResult(\n        this.config.sync.sync({\n          collection: this.collection,\n          begin: () => {\n            this.state.pendingSyncedTransactions.push({\n              committed: false,\n              operations: [],\n              deletedKeys: new Set(),\n            })\n          },\n          write: (messageWithoutKey: Omit<ChangeMessage<TOutput>, `key`>) => {\n            const pendingTransaction =\n              this.state.pendingSyncedTransactions[\n                this.state.pendingSyncedTransactions.length - 1\n              ]\n            if (!pendingTransaction) {\n              throw new NoPendingSyncTransactionWriteError()\n            }\n            if (pendingTransaction.committed) {\n              throw new SyncTransactionAlreadyCommittedWriteError()\n            }\n            const key = this.config.getKey(messageWithoutKey.value)\n\n            let messageType = messageWithoutKey.type\n\n            // Check if an item with this key already exists when inserting\n            if (messageWithoutKey.type === `insert`) {\n              const insertingIntoExistingSynced = this.state.syncedData.has(key)\n              const hasPendingDeleteForKey =\n                pendingTransaction.deletedKeys.has(key)\n              const isTruncateTransaction = pendingTransaction.truncate === true\n              // Allow insert after truncate in the same transaction even if it existed in syncedData\n              if (\n                insertingIntoExistingSynced &&\n                !hasPendingDeleteForKey &&\n                !isTruncateTransaction\n              ) {\n                const existingValue = this.state.syncedData.get(key)\n                if (\n                  existingValue !== undefined &&\n                  deepEquals(existingValue, messageWithoutKey.value)\n                ) {\n                  // The \"insert\" is an echo of a value we already have locally.\n                  // Treat it as an update so we preserve optimistic intent without\n                  // throwing a duplicate-key error during reconciliation.\n                  messageType = `update`\n                } else {\n                  throw new DuplicateKeySyncError(key, this.id)\n                }\n              }\n            }\n\n            const message: ChangeMessage<TOutput> = {\n              ...messageWithoutKey,\n              type: messageType,\n              key,\n            }\n            pendingTransaction.operations.push(message)\n\n            if (messageType === `delete`) {\n              pendingTransaction.deletedKeys.add(key)\n            }\n          },\n          commit: () => {\n            const pendingTransaction =\n              this.state.pendingSyncedTransactions[\n                this.state.pendingSyncedTransactions.length - 1\n              ]\n            if (!pendingTransaction) {\n              throw new NoPendingSyncTransactionCommitError()\n            }\n            if (pendingTransaction.committed) {\n              throw new SyncTransactionAlreadyCommittedError()\n            }\n\n            pendingTransaction.committed = true\n\n            this.state.commitPendingTransactions()\n          },\n          markReady: () => {\n            this.lifecycle.markReady()\n          },\n          truncate: () => {\n            const pendingTransaction =\n              this.state.pendingSyncedTransactions[\n                this.state.pendingSyncedTransactions.length - 1\n              ]\n            if (!pendingTransaction) {\n              throw new NoPendingSyncTransactionWriteError()\n            }\n            if (pendingTransaction.committed) {\n              throw new SyncTransactionAlreadyCommittedWriteError()\n            }\n\n            // Clear all operations from the current transaction\n            pendingTransaction.operations = []\n            pendingTransaction.deletedKeys.clear()\n\n            // Mark the transaction as a truncate operation. During commit, this triggers:\n            // - Delete events for all previously synced keys (excluding optimistic-deleted keys)\n            // - Clearing of syncedData/syncedMetadata\n            // - Subsequent synced ops applied on the fresh base\n            // - Finally, optimistic mutations re-applied on top (single batch)\n            pendingTransaction.truncate = true\n\n            // Capture optimistic state NOW to preserve it even if transactions complete\n            // before this truncate transaction is committed\n            pendingTransaction.optimisticSnapshot = {\n              upserts: new Map(this.state.optimisticUpserts),\n              deletes: new Set(this.state.optimisticDeletes),\n            }\n          },\n        })\n      )\n\n      // Store cleanup function if provided\n      this.syncCleanupFn = syncRes?.cleanup ?? null\n\n      // Store onLoadMore function if provided\n      this.syncOnLoadMoreFn = syncRes?.onLoadMore ?? null\n    } catch (error) {\n      this.lifecycle.setStatus(`error`)\n      throw error\n    }\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    if (this.preloadPromise) {\n      return this.preloadPromise\n    }\n\n    this.preloadPromise = new Promise<void>((resolve, reject) => {\n      if (this.lifecycle.status === `ready`) {\n        resolve()\n        return\n      }\n\n      if (this.lifecycle.status === `error`) {\n        reject(new CollectionIsInErrorStateError())\n        return\n      }\n\n      // Register callback BEFORE starting sync to avoid race condition\n      this.lifecycle.onFirstReady(() => {\n        resolve()\n      })\n\n      // Start sync if collection hasn't started yet or was cleaned up\n      if (\n        this.lifecycle.status === `idle` ||\n        this.lifecycle.status === `cleaned-up`\n      ) {\n        try {\n          this.startSync()\n        } catch (error) {\n          reject(error)\n          return\n        }\n      }\n    })\n\n    return this.preloadPromise\n  }\n\n  /**\n   * Requests the sync layer to load more data.\n   * @param options Options to control what data is being loaded\n   * @returns If data loading is asynchronous, this method returns a promise that resolves when the data is loaded.\n   *          If data loading is synchronous, the data is loaded when the method returns.\n   */\n  public syncMore(options: OnLoadMoreOptions): void | Promise<void> {\n    if (this.syncOnLoadMoreFn) {\n      return this.syncOnLoadMoreFn(options)\n    }\n  }\n\n  public cleanup(): void {\n    try {\n      if (this.syncCleanupFn) {\n        this.syncCleanupFn()\n        this.syncCleanupFn = null\n      }\n    } catch (error) {\n      // Re-throw in a microtask to surface the error after cleanup completes\n      queueMicrotask(() => {\n        if (error instanceof Error) {\n          // Preserve the original error and stack trace\n          const wrappedError = new SyncCleanupError(this.id, error)\n          wrappedError.cause = error\n          wrappedError.stack = error.stack\n          throw wrappedError\n        } else {\n          throw new SyncCleanupError(this.id, error as Error | string)\n        }\n      })\n    }\n    this.preloadPromise = null\n  }\n}\n\nfunction normalizeSyncFnResult(result: void | CleanupFn | SyncConfigRes) {\n  if (typeof result === `function`) {\n    return { cleanup: result }\n  }\n\n  if (typeof result === `object`) {\n    return result\n  }\n\n  return undefined\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"sync.js","sources":["../../../src/collection/sync.ts"],"sourcesContent":["import {\n  CollectionConfigurationError,\n  CollectionIsInErrorStateError,\n  DuplicateKeySyncError,\n  NoPendingSyncTransactionCommitError,\n  NoPendingSyncTransactionWriteError,\n  SyncCleanupError,\n  SyncTransactionAlreadyCommittedError,\n  SyncTransactionAlreadyCommittedWriteError,\n} from \"../errors\"\nimport { deepEquals } from \"../utils\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\nimport type {\n  ChangeMessage,\n  CleanupFn,\n  CollectionConfig,\n  LoadSubsetOptions,\n  SyncConfigRes,\n} from \"../types\"\nimport type { CollectionImpl } from \"./index.js\"\nimport type { CollectionStateManager } from \"./state\"\nimport type { CollectionLifecycleManager } from \"./lifecycle\"\nimport type { CollectionEventsManager } from \"./events.js\"\n\nexport class CollectionSyncManager<\n  TOutput extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n  TSchema extends StandardSchemaV1 = StandardSchemaV1,\n  TInput extends object = TOutput,\n> {\n  private collection!: CollectionImpl<TOutput, TKey, any, TSchema, TInput>\n  private state!: CollectionStateManager<TOutput, TKey, TSchema, TInput>\n  private lifecycle!: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>\n  private _events!: CollectionEventsManager\n  private config!: CollectionConfig<TOutput, TKey, TSchema>\n  private id: string\n  private syncMode: `eager` | `on-demand`\n\n  public preloadPromise: Promise<void> | null = null\n  public syncCleanupFn: (() => void) | null = null\n  public syncLoadSubsetFn:\n    | ((options: LoadSubsetOptions) => true | Promise<void>)\n    | null = null\n\n  private pendingLoadSubsetPromises: Set<Promise<void>> = new Set()\n\n  /**\n   * Creates a new CollectionSyncManager instance\n   */\n  constructor(config: CollectionConfig<TOutput, TKey, TSchema>, id: string) {\n    this.config = config\n    this.id = id\n    this.syncMode = config.syncMode ?? `eager`\n  }\n\n  setDeps(deps: {\n    collection: CollectionImpl<TOutput, TKey, any, TSchema, TInput>\n    state: CollectionStateManager<TOutput, TKey, TSchema, TInput>\n    lifecycle: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>\n    events: CollectionEventsManager\n  }) {\n    this.collection = deps.collection\n    this.state = deps.state\n    this.lifecycle = deps.lifecycle\n    this._events = deps.events\n  }\n\n  /**\n   * Start the sync process for this collection\n   * This is called when the collection is first accessed or preloaded\n   */\n  public startSync(): void {\n    if (\n      this.lifecycle.status !== `idle` &&\n      this.lifecycle.status !== `cleaned-up`\n    ) {\n      return // Already started or in progress\n    }\n\n    this.lifecycle.setStatus(`loading`)\n\n    try {\n      const syncRes = normalizeSyncFnResult(\n        this.config.sync.sync({\n          collection: this.collection,\n          begin: () => {\n            this.state.pendingSyncedTransactions.push({\n              committed: false,\n              operations: [],\n              deletedKeys: new Set(),\n            })\n          },\n          write: (messageWithoutKey: Omit<ChangeMessage<TOutput>, `key`>) => {\n            const pendingTransaction =\n              this.state.pendingSyncedTransactions[\n                this.state.pendingSyncedTransactions.length - 1\n              ]\n            if (!pendingTransaction) {\n              throw new NoPendingSyncTransactionWriteError()\n            }\n            if (pendingTransaction.committed) {\n              throw new SyncTransactionAlreadyCommittedWriteError()\n            }\n            const key = this.config.getKey(messageWithoutKey.value)\n\n            let messageType = messageWithoutKey.type\n\n            // Check if an item with this key already exists when inserting\n            if (messageWithoutKey.type === `insert`) {\n              const insertingIntoExistingSynced = this.state.syncedData.has(key)\n              const hasPendingDeleteForKey =\n                pendingTransaction.deletedKeys.has(key)\n              const isTruncateTransaction = pendingTransaction.truncate === true\n              // Allow insert after truncate in the same transaction even if it existed in syncedData\n              if (\n                insertingIntoExistingSynced &&\n                !hasPendingDeleteForKey &&\n                !isTruncateTransaction\n              ) {\n                const existingValue = this.state.syncedData.get(key)\n                if (\n                  existingValue !== undefined &&\n                  deepEquals(existingValue, messageWithoutKey.value)\n                ) {\n                  // The \"insert\" is an echo of a value we already have locally.\n                  // Treat it as an update so we preserve optimistic intent without\n                  // throwing a duplicate-key error during reconciliation.\n                  messageType = `update`\n                } else {\n                  throw new DuplicateKeySyncError(key, this.id)\n                }\n              }\n            }\n\n            const message: ChangeMessage<TOutput> = {\n              ...messageWithoutKey,\n              type: messageType,\n              key,\n            }\n            pendingTransaction.operations.push(message)\n\n            if (messageType === `delete`) {\n              pendingTransaction.deletedKeys.add(key)\n            }\n          },\n          commit: () => {\n            const pendingTransaction =\n              this.state.pendingSyncedTransactions[\n                this.state.pendingSyncedTransactions.length - 1\n              ]\n            if (!pendingTransaction) {\n              throw new NoPendingSyncTransactionCommitError()\n            }\n            if (pendingTransaction.committed) {\n              throw new SyncTransactionAlreadyCommittedError()\n            }\n\n            pendingTransaction.committed = true\n\n            this.state.commitPendingTransactions()\n          },\n          markReady: () => {\n            this.lifecycle.markReady()\n          },\n          truncate: () => {\n            const pendingTransaction =\n              this.state.pendingSyncedTransactions[\n                this.state.pendingSyncedTransactions.length - 1\n              ]\n            if (!pendingTransaction) {\n              throw new NoPendingSyncTransactionWriteError()\n            }\n            if (pendingTransaction.committed) {\n              throw new SyncTransactionAlreadyCommittedWriteError()\n            }\n\n            // Clear all operations from the current transaction\n            pendingTransaction.operations = []\n            pendingTransaction.deletedKeys.clear()\n\n            // Mark the transaction as a truncate operation. During commit, this triggers:\n            // - Delete events for all previously synced keys (excluding optimistic-deleted keys)\n            // - Clearing of syncedData/syncedMetadata\n            // - Subsequent synced ops applied on the fresh base\n            // - Finally, optimistic mutations re-applied on top (single batch)\n            pendingTransaction.truncate = true\n\n            // Capture optimistic state NOW to preserve it even if transactions complete\n            // before this truncate transaction is committed\n            pendingTransaction.optimisticSnapshot = {\n              upserts: new Map(this.state.optimisticUpserts),\n              deletes: new Set(this.state.optimisticDeletes),\n            }\n          },\n        })\n      )\n\n      // Store cleanup function if provided\n      this.syncCleanupFn = syncRes?.cleanup ?? null\n\n      // Store loadSubset function if provided\n      this.syncLoadSubsetFn = syncRes?.loadSubset ?? null\n\n      // Validate: on-demand mode requires a loadSubset function\n      if (this.syncMode === `on-demand` && !this.syncLoadSubsetFn) {\n        throw new CollectionConfigurationError(\n          `Collection \"${this.id}\" is configured with syncMode \"on-demand\" but the sync function did not return a loadSubset handler. ` +\n            `Either provide a loadSubset handler or use syncMode \"eager\".`\n        )\n      }\n    } catch (error) {\n      this.lifecycle.setStatus(`error`)\n      throw error\n    }\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    if (this.preloadPromise) {\n      return this.preloadPromise\n    }\n\n    this.preloadPromise = new Promise<void>((resolve, reject) => {\n      if (this.lifecycle.status === `ready`) {\n        resolve()\n        return\n      }\n\n      if (this.lifecycle.status === `error`) {\n        reject(new CollectionIsInErrorStateError())\n        return\n      }\n\n      // Register callback BEFORE starting sync to avoid race condition\n      this.lifecycle.onFirstReady(() => {\n        resolve()\n      })\n\n      // Start sync if collection hasn't started yet or was cleaned up\n      if (\n        this.lifecycle.status === `idle` ||\n        this.lifecycle.status === `cleaned-up`\n      ) {\n        try {\n          this.startSync()\n        } catch (error) {\n          reject(error)\n          return\n        }\n      }\n    })\n\n    return this.preloadPromise\n  }\n\n  /**\n   * Gets whether the collection is currently loading more data\n   */\n  public get isLoadingSubset(): boolean {\n    return this.pendingLoadSubsetPromises.size > 0\n  }\n\n  /**\n   * Tracks a load promise for isLoadingSubset state.\n   * @internal This is for internal coordination (e.g., live-query glue code), not for general use.\n   */\n  public trackLoadPromise(promise: Promise<void>): void {\n    const loadingStarting = !this.isLoadingSubset\n    this.pendingLoadSubsetPromises.add(promise)\n\n    if (loadingStarting) {\n      this._events.emit(`loadingSubset:change`, {\n        type: `loadingSubset:change`,\n        collection: this.collection,\n        isLoadingSubset: true,\n        previousIsLoadingSubset: false,\n        loadingSubsetTransition: `start`,\n      })\n    }\n\n    promise.finally(() => {\n      const loadingEnding =\n        this.pendingLoadSubsetPromises.size === 1 &&\n        this.pendingLoadSubsetPromises.has(promise)\n      this.pendingLoadSubsetPromises.delete(promise)\n\n      if (loadingEnding) {\n        this._events.emit(`loadingSubset:change`, {\n          type: `loadingSubset:change`,\n          collection: this.collection,\n          isLoadingSubset: false,\n          previousIsLoadingSubset: true,\n          loadingSubsetTransition: `end`,\n        })\n      }\n    })\n  }\n\n  /**\n   * Requests the sync layer to load more data.\n   * @param options Options to control what data is being loaded\n   * @returns If data loading is asynchronous, this method returns a promise that resolves when the data is loaded.\n   *          Returns true if no sync function is configured, if syncMode is 'eager', or if there is no work to do.\n   */\n  public loadSubset(options: LoadSubsetOptions): Promise<void> | true {\n    // Bypass loadSubset when syncMode is 'eager'\n    if (this.syncMode === `eager`) {\n      return true\n    }\n\n    if (this.syncLoadSubsetFn) {\n      const result = this.syncLoadSubsetFn(options)\n      // If the result is a promise, track it\n      if (result instanceof Promise) {\n        this.trackLoadPromise(result)\n        return result\n      }\n    }\n\n    return true\n  }\n\n  public cleanup(): void {\n    try {\n      if (this.syncCleanupFn) {\n        this.syncCleanupFn()\n        this.syncCleanupFn = null\n      }\n    } catch (error) {\n      // Re-throw in a microtask to surface the error after cleanup completes\n      queueMicrotask(() => {\n        if (error instanceof Error) {\n          // Preserve the original error and stack trace\n          const wrappedError = new SyncCleanupError(this.id, error)\n          wrappedError.cause = error\n          wrappedError.stack = error.stack\n          throw wrappedError\n        } else {\n          throw new SyncCleanupError(this.id, error as Error | string)\n        }\n      })\n    }\n    this.preloadPromise = null\n  }\n}\n\nfunction normalizeSyncFnResult(result: void | CleanupFn | SyncConfigRes) {\n  if (typeof result === `function`) {\n    return { cleanup: result }\n  }\n\n  if (typeof result === `object`) {\n    return result\n  }\n\n  return undefined\n}\n"],"names":[],"mappings":"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"}