@tanstack/db 0.0.16 → 0.0.18

package/dist/cjs/types.d.cts

@@ -140,26 +140,43 @@ export interface OperationConfig {
 export interface InsertConfig {
     metadata?: Record<string, unknown>;
 }
-export type UpdateMutationFnParams<T extends object = Record<string, unknown>> = {
+export type UpdateMutationFnParams<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = Record<string, Fn>> = {
     transaction: TransactionWithMutations<T, `update`>;
+    collection: Collection<T, TKey, TUtils>;
 };
-export type InsertMutationFnParams<T extends object = Record<string, unknown>> = {
+export type InsertMutationFnParams<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = Record<string, Fn>> = {
     transaction: TransactionWithMutations<T, `insert`>;
+    collection: Collection<T, TKey, TUtils>;
 };
-export type DeleteMutationFnParams<T extends object = Record<string, unknown>> = {
+export type DeleteMutationFnParams<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = Record<string, Fn>> = {
     transaction: TransactionWithMutations<T, `delete`>;
+    collection: Collection<T, TKey, TUtils>;
 };
-export type InsertMutationFn<T extends object = Record<string, unknown>> = (params: InsertMutationFnParams<T>) => Promise<any>;
-export type UpdateMutationFn<T extends object = Record<string, unknown>> = (params: UpdateMutationFnParams<T>) => Promise<any>;
-export type DeleteMutationFn<T extends object = Record<string, unknown>> = (params: DeleteMutationFnParams<T>) => Promise<any>;
+export type InsertMutationFn<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = Record<string, Fn>> = (params: InsertMutationFnParams<T, TKey, TUtils>) => Promise<any>;
+export type UpdateMutationFn<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = Record<string, Fn>> = (params: UpdateMutationFnParams<T, TKey, TUtils>) => Promise<any>;
+export type DeleteMutationFn<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = Record<string, Fn>> = (params: DeleteMutationFnParams<T, TKey, TUtils>) => Promise<any>;
 /**
  * Collection status values for lifecycle management
+ * @example
+ * // Check collection status
+ * if (collection.status === "loading") {
+ *   console.log("Collection is loading initial data")
+ * } else if (collection.status === "ready") {
+ *   console.log("Collection is ready for use")
+ * }
+ *
+ * @example
+ * // Status transitions
+ * // idle → loading → initialCommit → ready
+ * // Any status can transition to → error or cleaned-up
  */
 export type CollectionStatus = 
 /** Collection is created but sync hasn't started yet (when startSync config is false) */
 `idle`
 /** Sync has started but hasn't received the first commit yet */
  | `loading`
+/** Collection is in the process of committing its first transaction */
+ | `initialCommit`
 /** Collection has received at least one commit and is ready for use */
  | `ready`
 /** An error occurred during sync initialization */
@@ -203,22 +220,132 @@ export interface CollectionConfig<T extends object = Record<string, unknown>, TK
     compare?: (x: T, y: T) => number;
     /**
      * Optional asynchronous handler function called before an insert operation
-     * @param params Object containing transaction and mutation information
+     * @param params Object containing transaction and collection information
      * @returns Promise resolving to any value
+     * @example
+     * // Basic insert handler
+     * onInsert: async ({ transaction, collection }) => {
+     *   const newItem = transaction.mutations[0].modified
+     *   await api.createTodo(newItem)
+     * }
+     *
+     * @example
+     * // Insert handler with multiple items
+     * onInsert: async ({ transaction, collection }) => {
+     *   const items = transaction.mutations.map(m => m.modified)
+     *   await api.createTodos(items)
+     * }
+     *
+     * @example
+     * // Insert handler with error handling
+     * onInsert: async ({ transaction, collection }) => {
+     *   try {
+     *     const newItem = transaction.mutations[0].modified
+     *     const result = await api.createTodo(newItem)
+     *     return result
+     *   } catch (error) {
+     *     console.error('Insert failed:', error)
+     *     throw error // This will cause the transaction to fail
+     *   }
+     * }
+     *
+     * @example
+     * // Insert handler with metadata
+     * onInsert: async ({ transaction, collection }) => {
+     *   const mutation = transaction.mutations[0]
+     *   await api.createTodo(mutation.modified, {
+     *     source: mutation.metadata?.source,
+     *     timestamp: mutation.createdAt
+     *   })
+     * }
      */
-    onInsert?: InsertMutationFn<T>;
+    onInsert?: InsertMutationFn<T, TKey>;
     /**
      * Optional asynchronous handler function called before an update operation
-     * @param params Object containing transaction and mutation information
+     * @param params Object containing transaction and collection information
      * @returns Promise resolving to any value
+     * @example
+     * // Basic update handler
+     * onUpdate: async ({ transaction, collection }) => {
+     *   const updatedItem = transaction.mutations[0].modified
+     *   await api.updateTodo(updatedItem.id, updatedItem)
+     * }
+     *
+     * @example
+     * // Update handler with partial updates
+     * onUpdate: async ({ transaction, collection }) => {
+     *   const mutation = transaction.mutations[0]
+     *   const changes = mutation.changes // Only the changed fields
+     *   await api.updateTodo(mutation.original.id, changes)
+     * }
+     *
+     * @example
+     * // Update handler with multiple items
+     * onUpdate: async ({ transaction, collection }) => {
+     *   const updates = transaction.mutations.map(m => ({
+     *     id: m.key,
+     *     changes: m.changes
+     *   }))
+     *   await api.updateTodos(updates)
+     * }
+     *
+     * @example
+     * // Update handler with optimistic rollback
+     * onUpdate: async ({ transaction, collection }) => {
+     *   const mutation = transaction.mutations[0]
+     *   try {
+     *     await api.updateTodo(mutation.original.id, mutation.changes)
+     *   } catch (error) {
+     *     // Transaction will automatically rollback optimistic changes
+     *     console.error('Update failed, rolling back:', error)
+     *     throw error
+     *   }
+     * }
      */
-    onUpdate?: UpdateMutationFn<T>;
+    onUpdate?: UpdateMutationFn<T, TKey>;
     /**
      * Optional asynchronous handler function called before a delete operation
-     * @param params Object containing transaction and mutation information
+     * @param params Object containing transaction and collection information
      * @returns Promise resolving to any value
+     * @example
+     * // Basic delete handler
+     * onDelete: async ({ transaction, collection }) => {
+     *   const deletedKey = transaction.mutations[0].key
+     *   await api.deleteTodo(deletedKey)
+     * }
+     *
+     * @example
+     * // Delete handler with multiple items
+     * onDelete: async ({ transaction, collection }) => {
+     *   const keysToDelete = transaction.mutations.map(m => m.key)
+     *   await api.deleteTodos(keysToDelete)
+     * }
+     *
+     * @example
+     * // Delete handler with confirmation
+     * onDelete: async ({ transaction, collection }) => {
+     *   const mutation = transaction.mutations[0]
+     *   const shouldDelete = await confirmDeletion(mutation.original)
+     *   if (!shouldDelete) {
+     *     throw new Error('Delete cancelled by user')
+     *   }
+     *   await api.deleteTodo(mutation.original.id)
+     * }
+     *
+     * @example
+     * // Delete handler with optimistic rollback
+     * onDelete: async ({ transaction, collection }) => {
+     *   const mutation = transaction.mutations[0]
+     *   try {
+     *     await api.deleteTodo(mutation.original.id)
+     *   } catch (error) {
+     *     // Transaction will automatically rollback optimistic changes
+     *     console.error('Delete failed, rolling back:', error)
+     *     throw error
+     *   }
+     * }
      */
-    onDelete?: DeleteMutationFn<T>;
+    onDelete?: DeleteMutationFn<T, TKey>;
 }
 export type ChangesPayload<T extends object = Record<string, unknown>> = Array<ChangeMessage<T>>;
 /**
@@ -250,4 +377,35 @@ export type KeyedNamespacedRow = [unknown, NamespacedRow];
  * a `select` clause.
  */
 export type NamespacedAndKeyedStream = IStreamBuilder<KeyedNamespacedRow>;
+/**
+ * Function type for listening to collection changes
+ * @param changes - Array of change messages describing what happened
+ * @example
+ * // Basic change listener
+ * const listener: ChangeListener = (changes) => {
+ *   changes.forEach(change => {
+ *     console.log(`${change.type}: ${change.key}`, change.value)
+ *   })
+ * }
+ *
+ * collection.subscribeChanges(listener)
+ *
+ * @example
+ * // Handle different change types
+ * const listener: ChangeListener<Todo> = (changes) => {
+ *   for (const change of changes) {
+ *     switch (change.type) {
+ *       case 'insert':
+ *         addToUI(change.value)
+ *         break
+ *       case 'update':
+ *         updateInUI(change.key, change.value, change.previousValue)
+ *         break
+ *       case 'delete':
+ *         removeFromUI(change.key)
+ *         break
+ *     }
+ *   }
+ * }
+ */
 export type ChangeListener<T extends object = Record<string, unknown>, TKey extends string | number = string | number> = (changes: Array<ChangeMessage<T, TKey>>) => void;

package/dist/esm/SortedMap.js.map

@@ -1 +1 @@
-{"version":3,"file":"SortedMap.js","sources":["../../src/SortedMap.ts"],"sourcesContent":["/**\n * A Map implementation that keeps its entries sorted based on a comparator function\n * @template TKey - The type of keys in the map\n * @template TValue - The type of values in the map\n */\nexport class SortedMap<TKey, TValue> {\n  private map: Map<TKey, TValue>\n  private sortedKeys: Array<TKey>\n  private comparator: (a: TValue, b: TValue) => number\n\n  /**\n   * Creates a new SortedMap instance\n   *\n   * @param comparator - Optional function to compare values for sorting\n   */\n  constructor(comparator?: (a: TValue, b: TValue) => number) {\n    this.map = new Map<TKey, TValue>()\n    this.sortedKeys = []\n    this.comparator = comparator || this.defaultComparator\n  }\n\n  /**\n   * Default comparator function used when none is provided\n   *\n   * @param a - First value to compare\n   * @param b - Second value to compare\n   * @returns -1 if a < b, 1 if a > b, 0 if equal\n   */\n  private defaultComparator(a: TValue, b: TValue): number {\n    if (a < b) return -1\n    if (a > b) return 1\n    return 0\n  }\n\n  /**\n   * Finds the index where a key-value pair should be inserted to maintain sort order.\n   * Uses binary search to find the correct position based on the value.\n   * Hence, it is in O(log n) time.\n   *\n   * @param key - The key to find position for\n   * @param value - The value to compare against\n   * @returns The index where the key should be inserted\n   */\n  private indexOf(value: TValue): number {\n    let left = 0\n    let right = this.sortedKeys.length\n\n    while (left < right) {\n      const mid = Math.floor((left + right) / 2)\n      const midKey = this.sortedKeys[mid]!\n      const midValue = this.map.get(midKey)!\n      const comparison = this.comparator(value, midValue)\n\n      if (comparison < 0) {\n        right = mid\n      } else if (comparison > 0) {\n        left = mid + 1\n      } else {\n        return mid\n      }\n    }\n\n    return left\n  }\n\n  /**\n   * Sets a key-value pair in the map and maintains sort order\n   *\n   * @param key - The key to set\n   * @param value - The value to associate with the key\n   * @returns This SortedMap instance for chaining\n   */\n  set(key: TKey, value: TValue): this {\n    if (this.map.has(key)) {\n      // Need to remove the old key from the sorted keys array\n      const oldValue = this.map.get(key)!\n      const oldIndex = this.indexOf(oldValue)\n      this.sortedKeys.splice(oldIndex, 1)\n    }\n\n    // Insert the new key at the correct position\n    const index = this.indexOf(value)\n    this.sortedKeys.splice(index, 0, key)\n\n    this.map.set(key, value)\n\n    return this\n  }\n\n  /**\n   * Gets a value by its key\n   *\n   * @param key - The key to look up\n   * @returns The value associated with the key, or undefined if not found\n   */\n  get(key: TKey): TValue | undefined {\n    return this.map.get(key)\n  }\n\n  /**\n   * Removes a key-value pair from the map\n   *\n   * @param key - The key to remove\n   * @returns True if the key was found and removed, false otherwise\n   */\n  delete(key: TKey): boolean {\n    if (this.map.has(key)) {\n      const oldValue = this.map.get(key)\n      const index = this.indexOf(oldValue!)\n      this.sortedKeys.splice(index, 1)\n      return this.map.delete(key)\n    }\n\n    return false\n  }\n\n  /**\n   * Checks if a key exists in the map\n   *\n   * @param key - The key to check\n   * @returns True if the key exists, false otherwise\n   */\n  has(key: TKey): boolean {\n    return this.map.has(key)\n  }\n\n  /**\n   * Removes all key-value pairs from the map\n   */\n  clear(): void {\n    this.map.clear()\n    this.sortedKeys = []\n  }\n\n  /**\n   * Gets the number of key-value pairs in the map\n   */\n  get size(): number {\n    return this.map.size\n  }\n\n  /**\n   * Default iterator that returns entries in sorted order\n   *\n   * @returns An iterator for the map's entries\n   */\n  *[Symbol.iterator](): IterableIterator<[TKey, TValue]> {\n    for (const key of this.sortedKeys) {\n      yield [key, this.map.get(key)!] as [TKey, TValue]\n    }\n  }\n\n  /**\n   * Returns an iterator for the map's entries in sorted order\n   *\n   * @returns An iterator for the map's entries\n   */\n  entries(): IterableIterator<[TKey, TValue]> {\n    return this[Symbol.iterator]()\n  }\n\n  /**\n   * Returns an iterator for the map's keys in sorted order\n   *\n   * @returns An iterator for the map's keys\n   */\n  keys(): IterableIterator<TKey> {\n    return this.sortedKeys[Symbol.iterator]()\n  }\n\n  /**\n   * Returns an iterator for the map's values in sorted order\n   *\n   * @returns An iterator for the map's values\n   */\n  values(): IterableIterator<TValue> {\n    return function* (this: SortedMap<TKey, TValue>) {\n      for (const key of this.sortedKeys) {\n        yield this.map.get(key)!\n      }\n    }.call(this)\n  }\n\n  /**\n   * Executes a callback function for each key-value pair in the map in sorted order\n   *\n   * @param callbackfn - Function to execute for each entry\n   */\n  forEach(\n    callbackfn: (value: TValue, key: TKey, map: Map<TKey, TValue>) => void\n  ): void {\n    for (const key of this.sortedKeys) {\n      callbackfn(this.map.get(key)!, key, this.map)\n    }\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"SortedMap.js","sources":["../../src/SortedMap.ts"],"sourcesContent":["/**\n * A Map implementation that keeps its entries sorted based on a comparator function\n * @template TKey - The type of keys in the map\n * @template TValue - The type of values in the map\n */\nexport class SortedMap<TKey, TValue> {\n  private map: Map<TKey, TValue>\n  private sortedKeys: Array<TKey>\n  private comparator: (a: TValue, b: TValue) => number\n\n  /**\n   * Creates a new SortedMap instance\n   *\n   * @param comparator - Optional function to compare values for sorting\n   */\n  constructor(comparator?: (a: TValue, b: TValue) => number) {\n    this.map = new Map<TKey, TValue>()\n    this.sortedKeys = []\n    this.comparator = comparator || this.defaultComparator\n  }\n\n  /**\n   * Default comparator function used when none is provided\n   *\n   * @param a - First value to compare\n   * @param b - Second value to compare\n   * @returns -1 if a < b, 1 if a > b, 0 if equal\n   */\n  private defaultComparator(a: TValue, b: TValue): number {\n    if (a < b) return -1\n    if (a > b) return 1\n    return 0\n  }\n\n  /**\n   * Finds the index where a key-value pair should be inserted to maintain sort order.\n   * Uses binary search to find the correct position based on the value.\n   * Hence, it is in O(log n) time.\n   *\n   * @param key - The key to find position for\n   * @param value - The value to compare against\n   * @returns The index where the key should be inserted\n   */\n  private indexOf(value: TValue): number {\n    let left = 0\n    let right = this.sortedKeys.length\n\n    while (left < right) {\n      const mid = Math.floor((left + right) / 2)\n      const midKey = this.sortedKeys[mid]!\n      const midValue = this.map.get(midKey)!\n      const comparison = this.comparator(value, midValue)\n\n      if (comparison < 0) {\n        right = mid\n      } else if (comparison > 0) {\n        left = mid + 1\n      } else {\n        return mid\n      }\n    }\n\n    return left\n  }\n\n  /**\n   * Sets a key-value pair in the map and maintains sort order\n   *\n   * @param key - The key to set\n   * @param value - The value to associate with the key\n   * @returns This SortedMap instance for chaining\n   */\n  set(key: TKey, value: TValue): this {\n    if (this.map.has(key)) {\n      // Need to remove the old key from the sorted keys array\n      const oldValue = this.map.get(key)!\n      const oldIndex = this.indexOf(oldValue)\n      this.sortedKeys.splice(oldIndex, 1)\n    }\n\n    // Insert the new key at the correct position\n    const index = this.indexOf(value)\n    this.sortedKeys.splice(index, 0, key)\n\n    this.map.set(key, value)\n\n    return this\n  }\n\n  /**\n   * Gets a value by its key\n   *\n   * @param key - The key to look up\n   * @returns The value associated with the key, or undefined if not found\n   */\n  get(key: TKey): TValue | undefined {\n    return this.map.get(key)\n  }\n\n  /**\n   * Removes a key-value pair from the map\n   *\n   * @param key - The key to remove\n   * @returns True if the key was found and removed, false otherwise\n   */\n  delete(key: TKey): boolean {\n    if (this.map.has(key)) {\n      const oldValue = this.map.get(key)\n      const index = this.indexOf(oldValue!)\n      this.sortedKeys.splice(index, 1)\n      return this.map.delete(key)\n    }\n\n    return false\n  }\n\n  /**\n   * Checks if a key exists in the map\n   *\n   * @param key - The key to check\n   * @returns True if the key exists, false otherwise\n   */\n  has(key: TKey): boolean {\n    return this.map.has(key)\n  }\n\n  /**\n   * Removes all key-value pairs from the map\n   */\n  clear(): void {\n    this.map.clear()\n    this.sortedKeys = []\n  }\n\n  /**\n   * Gets the number of key-value pairs in the map\n   */\n  get size(): number {\n    return this.map.size\n  }\n\n  /**\n   * Default iterator that returns entries in sorted order\n   *\n   * @returns An iterator for the map's entries\n   */\n  *[Symbol.iterator](): IterableIterator<[TKey, TValue]> {\n    for (const key of this.sortedKeys) {\n      yield [key, this.map.get(key)!] as [TKey, TValue]\n    }\n  }\n\n  /**\n   * Returns an iterator for the map's entries in sorted order\n   *\n   * @returns An iterator for the map's entries\n   */\n  entries(): IterableIterator<[TKey, TValue]> {\n    return this[Symbol.iterator]()\n  }\n\n  /**\n   * Returns an iterator for the map's keys in sorted order\n   *\n   * @returns An iterator for the map's keys\n   */\n  keys(): IterableIterator<TKey> {\n    return this.sortedKeys[Symbol.iterator]()\n  }\n\n  /**\n   * Returns an iterator for the map's values in sorted order\n   *\n   * @returns An iterator for the map's values\n   */\n  values(): IterableIterator<TValue> {\n    return function* (this: SortedMap<TKey, TValue>) {\n      for (const key of this.sortedKeys) {\n        yield this.map.get(key)!\n      }\n    }.call(this)\n  }\n\n  /**\n   * Executes a callback function for each key-value pair in the map in sorted order\n   *\n   * @param callbackfn - Function to execute for each entry\n   */\n  forEach(\n    callbackfn: (value: TValue, key: TKey, map: Map<TKey, TValue>) => void\n  ): void {\n    for (const key of this.sortedKeys) {\n      callbackfn(this.map.get(key)!, key, this.map)\n    }\n  }\n}\n"],"names":[],"mappings":"AAKO,MAAM,UAAwB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUnC,YAAY,YAA+C;AACzD,SAAK,0BAAU,IAAA;AACf,SAAK,aAAa,CAAA;AAClB,SAAK,aAAa,cAAc,KAAK;AAAA,EACvC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASQ,kBAAkB,GAAW,GAAmB;AACtD,QAAI,IAAI,EAAG,QAAO;AAClB,QAAI,IAAI,EAAG,QAAO;AAClB,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWQ,QAAQ,OAAuB;AACrC,QAAI,OAAO;AACX,QAAI,QAAQ,KAAK,WAAW;AAE5B,WAAO,OAAO,OAAO;AACnB,YAAM,MAAM,KAAK,OAAO,OAAO,SAAS,CAAC;AACzC,YAAM,SAAS,KAAK,WAAW,GAAG;AAClC,YAAM,WAAW,KAAK,IAAI,IAAI,MAAM;AACpC,YAAM,aAAa,KAAK,WAAW,OAAO,QAAQ;AAElD,UAAI,aAAa,GAAG;AAClB,gBAAQ;AAAA,MACV,WAAW,aAAa,GAAG;AACzB,eAAO,MAAM;AAAA,MACf,OAAO;AACL,eAAO;AAAA,MACT;AAAA,IACF;AAEA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,IAAI,KAAW,OAAqB;AAClC,QAAI,KAAK,IAAI,IAAI,GAAG,GAAG;AAErB,YAAM,WAAW,KAAK,IAAI,IAAI,GAAG;AACjC,YAAM,WAAW,KAAK,QAAQ,QAAQ;AACtC,WAAK,WAAW,OAAO,UAAU,CAAC;AAAA,IACpC;AAGA,UAAM,QAAQ,KAAK,QAAQ,KAAK;AAChC,SAAK,WAAW,OAAO,OAAO,GAAG,GAAG;AAEpC,SAAK,IAAI,IAAI,KAAK,KAAK;AAEvB,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,IAAI,KAA+B;AACjC,WAAO,KAAK,IAAI,IAAI,GAAG;AAAA,EACzB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,OAAO,KAAoB;AACzB,QAAI,KAAK,IAAI,IAAI,GAAG,GAAG;AACrB,YAAM,WAAW,KAAK,IAAI,IAAI,GAAG;AACjC,YAAM,QAAQ,KAAK,QAAQ,QAAS;AACpC,WAAK,WAAW,OAAO,OAAO,CAAC;AAC/B,aAAO,KAAK,IAAI,OAAO,GAAG;AAAA,IAC5B;AAEA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,IAAI,KAAoB;AACtB,WAAO,KAAK,IAAI,IAAI,GAAG;AAAA,EACzB;AAAA;AAAA;AAAA;AAAA,EAKA,QAAc;AACZ,SAAK,IAAI,MAAA;AACT,SAAK,aAAa,CAAA;AAAA,EACpB;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,OAAe;AACjB,WAAO,KAAK,IAAI;AAAA,EAClB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,EAAE,OAAO,QAAQ,IAAsC;AACrD,eAAW,OAAO,KAAK,YAAY;AACjC,YAAM,CAAC,KAAK,KAAK,IAAI,IAAI,GAAG,CAAE;AAAA,IAChC;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,UAA4C;AAC1C,WAAO,KAAK,OAAO,QAAQ,EAAA;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,OAA+B;AAC7B,WAAO,KAAK,WAAW,OAAO,QAAQ,EAAA;AAAA,EACxC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,SAAmC;AACjC,YAAO,aAA0C;AAC/C,iBAAW,OAAO,KAAK,YAAY;AACjC,cAAM,KAAK,IAAI,IAAI,GAAG;AAAA,MACxB;AAAA,IACF,GAAE,KAAK,IAAI;AAAA,EACb;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,QACE,YACM;AACN,eAAW,OAAO,KAAK,YAAY;AACjC,iBAAW,KAAK,IAAI,IAAI,GAAG,GAAI,KAAK,KAAK,GAAG;AAAA,IAC9C;AAAA,EACF;AACF;"}

package/dist/esm/collection.d.ts

@@ -2,7 +2,7 @@ import { SortedMap } from './SortedMap.js';
 import { Transaction } from './transactions.js';
 import { ChangeListener, ChangeMessage, CollectionConfig, CollectionStatus, Fn, InsertConfig, OperationConfig, OptimisticChangeMessage, ResolveType, Transaction as TransactionType, UtilsRecord } from './types.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
-export declare const collectionsStore: Map<string, CollectionImpl<any, any>>;
+export declare const collectionsStore: Map<string, CollectionImpl<any, any, {}>>;
 interface PendingSyncedTransaction<T extends object = Record<string, unknown>> {
     committed: boolean;
     operations: Array<OptimisticChangeMessage<T>>;
@@ -28,12 +28,52 @@ export interface Collection<T extends object = Record<string, unknown>, TKey ext
  * @returns A new Collection with utilities exposed both at top level and under .utils
  *
  * @example
- * // Using explicit type
- * const todos = createCollection<Todo>({
+ * // Pattern 1: With operation handlers (direct collection calls)
+ * const todos = createCollection({
+ *   id: "todos",
+ *   getKey: (todo) => todo.id,
+ *   schema,
+ *   onInsert: async ({ transaction, collection }) => {
+ *     // Send to API
+ *     await api.createTodo(transaction.mutations[0].modified)
+ *   },
+ *   onUpdate: async ({ transaction, collection }) => {
+ *     await api.updateTodo(transaction.mutations[0].modified)
+ *   },
+ *   onDelete: async ({ transaction, collection }) => {
+ *     await api.deleteTodo(transaction.mutations[0].key)
+ *   },
+ *   sync: { sync: () => {} }
+ * })
+ *
+ * // Direct usage (handlers manage transactions)
+ * const tx = todos.insert({ id: "1", text: "Buy milk", completed: false })
+ * await tx.isPersisted.promise
+ *
+ * @example
+ * // Pattern 2: Manual transaction management
+ * const todos = createCollection({
  *   getKey: (todo) => todo.id,
+ *   schema: todoSchema,
  *   sync: { sync: () => {} }
  * })
  *
+ * // Explicit transaction usage
+ * const tx = createTransaction({
+ *   mutationFn: async ({ transaction }) => {
+ *     // Handle all mutations in transaction
+ *     await api.saveChanges(transaction.mutations)
+ *   }
+ * })
+ *
+ * tx.mutate(() => {
+ *   todos.insert({ id: "1", text: "Buy milk" })
+ *   todos.update("2", draft => { draft.completed = true })
+ * })
+ *
+ * await tx.isPersisted.promise
+ *
+ * @example
  * // Using schema for type inference (preferred as it also gives you client side validation)
  * const todoSchema = z.object({
  *   id: z.string(),
@@ -47,7 +87,7 @@ export interface Collection<T extends object = Record<string, unknown>, TKey ext
  *   sync: { sync: () => {} }
  * })
  *
- * // Note: You must provide either an explicit type or a schema, but not both
+ * // Note: You must provide either an explicit type or a schema, but not both.
  */
 export declare function createCollection<TExplicit = unknown, TKey extends string | number = string | number, TUtils extends UtilsRecord = {}, TSchema extends StandardSchemaV1 = StandardSchemaV1, TFallback extends object = Record<string, unknown>>(options: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>, TKey, TSchema> & {
     utils?: TUtils;
@@ -66,7 +106,7 @@ export declare class SchemaValidationError extends Error {
         path?: ReadonlyArray<string | number | symbol>;
     }>, message?: string);
 }
-export declare class CollectionImpl<T extends object = Record<string, unknown>, TKey extends string | number = string | number> {
+export declare class CollectionImpl<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = {}> {
     config: CollectionConfig<T, TKey, any>;
     transactions: SortedMap<string, Transaction<any>>;
     pendingSyncedTransactions: Array<PendingSyncedTransaction<T>>;
@@ -95,6 +135,11 @@ export declare class CollectionImpl<T extends object = Record<string, unknown>,
      * Register a callback to be executed on the next commit
      * Useful for preloading collections
      * @param callback Function to call after the next commit
+     * @example
+     * collection.onFirstCommit(() => {
+     *   console.log('Collection has received first data')
+     *   // Safe to access collection.state now
+     * })
      */
     onFirstCommit(callback: () => void): void;
     id: string;
@@ -231,60 +276,78 @@ export declare class CollectionImpl<T extends object = Record<string, unknown>,
     /**
      * Inserts one or more items into the collection
      * @param items - Single item or array of items to insert
-     * @param config - Optional configuration including metadata and custom keys
-     * @returns A TransactionType object representing the insert operation(s)
+     * @param config - Optional configuration including metadata
+     * @returns A Transaction object representing the insert operation(s)
      * @throws {SchemaValidationError} If the data fails schema validation
      * @example
-     * // Insert a single item
-     * insert({ text: "Buy groceries", completed: false })
+     * // Insert a single todo (requires onInsert handler)
+     * const tx = collection.insert({ id: "1", text: "Buy milk", completed: false })
+     * await tx.isPersisted.promise
      *
-     * // Insert multiple items
-     * insert([
-     *   { text: "Buy groceries", completed: false },
-     *   { text: "Walk dog", completed: false }
+     * @example
+     * // Insert multiple todos at once
+     * const tx = collection.insert([
+     *   { id: "1", text: "Buy milk", completed: false },
+     *   { id: "2", text: "Walk dog", completed: true }
      * ])
+     * await tx.isPersisted.promise
+     *
+     * @example
+     * // Insert with metadata
+     * const tx = collection.insert({ id: "1", text: "Buy groceries" },
+     *   { metadata: { source: "mobile-app" } }
+     * )
+     * await tx.isPersisted.promise
      *
-     * // Insert with custom key
-     * insert({ text: "Buy groceries" }, { key: "grocery-task" })
+     * @example
+     * // Handle errors
+     * try {
+     *   const tx = collection.insert({ id: "1", text: "New item" })
+     *   await tx.isPersisted.promise
+     *   console.log('Insert successful')
+     * } catch (error) {
+     *   console.log('Insert failed:', error)
+     * }
      */
     insert: (data: T | Array<T>, config?: InsertConfig) => Transaction<Record<string, unknown>, import('./types.js').OperationType>;
     /**
      * Updates one or more items in the collection using a callback function
-     * @param items - Single item/key or array of items/keys to update
+     * @param keys - Single key or array of keys to update
      * @param configOrCallback - Either update configuration or update callback
      * @param maybeCallback - Update callback if config was provided
      * @returns A Transaction object representing the update operation(s)
      * @throws {SchemaValidationError} If the updated data fails schema validation
      * @example
-     * // Update a single item
-     * update(todo, (draft) => { draft.completed = true })
-     *
-     * // Update multiple items
-     * update([todo1, todo2], (drafts) => {
-     *   drafts.forEach(draft => { draft.completed = true })
+     * // Update single item by key
+     * const tx = collection.update("todo-1", (draft) => {
+     *   draft.completed = true
      * })
+     * await tx.isPersisted.promise
      *
-     * // Update with metadata
-     * update(todo, { metadata: { reason: "user update" } }, (draft) => { draft.text = "Updated text" })
-     */
-    /**
-     * Updates one or more items in the collection using a callback function
-     * @param ids - Single ID or array of IDs to update
-     * @param configOrCallback - Either update configuration or update callback
-     * @param maybeCallback - Update callback if config was provided
-     * @returns A Transaction object representing the update operation(s)
-     * @throws {SchemaValidationError} If the updated data fails schema validation
      * @example
-     * // Update a single item
-     * update("todo-1", (draft) => { draft.completed = true })
-     *
      * // Update multiple items
-     * update(["todo-1", "todo-2"], (drafts) => {
+     * const tx = collection.update(["todo-1", "todo-2"], (drafts) => {
      *   drafts.forEach(draft => { draft.completed = true })
      * })
+     * await tx.isPersisted.promise
      *
+     * @example
      * // Update with metadata
-     * update("todo-1", { metadata: { reason: "user update" } }, (draft) => { draft.text = "Updated text" })
+     * const tx = collection.update("todo-1",
+     *   { metadata: { reason: "user update" } },
+     *   (draft) => { draft.text = "Updated text" }
+     * )
+     * await tx.isPersisted.promise
+     *
+     * @example
+     * // Handle errors
+     * try {
+     *   const tx = collection.update("item-1", draft => { draft.value = "new" })
+     *   await tx.isPersisted.promise
+     *   console.log('Update successful')
+     * } catch (error) {
+     *   console.log('Update failed:', error)
+     * }
      */
     update<TItem extends object = T>(key: Array<TKey | unknown>, callback: (drafts: Array<TItem>) => void): TransactionType;
     update<TItem extends object = T>(keys: Array<TKey | unknown>, config: OperationConfig, callback: (drafts: Array<TItem>) => void): TransactionType;
@@ -292,24 +355,50 @@ export declare class CollectionImpl<T extends object = Record<string, unknown>,
     update<TItem extends object = T>(id: TKey | unknown, config: OperationConfig, callback: (draft: TItem) => void): TransactionType;
     /**
      * Deletes one or more items from the collection
-     * @param ids - Single ID or array of IDs to delete
+     * @param keys - Single key or array of keys to delete
      * @param config - Optional configuration including metadata
-     * @returns A TransactionType object representing the delete operation(s)
+     * @returns A Transaction object representing the delete operation(s)
      * @example
      * // Delete a single item
-     * delete("todo-1")
+     * const tx = collection.delete("todo-1")
+     * await tx.isPersisted.promise
      *
+     * @example
      * // Delete multiple items
-     * delete(["todo-1", "todo-2"])
+     * const tx = collection.delete(["todo-1", "todo-2"])
+     * await tx.isPersisted.promise
      *
+     * @example
      * // Delete with metadata
-     * delete("todo-1", { metadata: { reason: "completed" } })
+     * const tx = collection.delete("todo-1", { metadata: { reason: "completed" } })
+     * await tx.isPersisted.promise
+     *
+     * @example
+     * // Handle errors
+     * try {
+     *   const tx = collection.delete("item-1")
+     *   await tx.isPersisted.promise
+     *   console.log('Delete successful')
+     * } catch (error) {
+     *   console.log('Delete failed:', error)
+     * }
      */
     delete: (keys: Array<TKey> | TKey, config?: OperationConfig) => TransactionType<any>;
     /**
      * Gets the current state of the collection as a Map
+     * @returns Map containing all items in the collection, with keys as identifiers
+     * @example
+     * const itemsMap = collection.state
+     * console.log(`Collection has ${itemsMap.size} items`)
      *
-     * @returns A Map containing all items in the collection, with keys as identifiers
+     * for (const [key, item] of itemsMap) {
+     *   console.log(`${key}: ${item.title}`)
+     * }
+     *
+     * // Check if specific item exists
+     * if (itemsMap.has("todo-1")) {
+     *   console.log("Todo 1 exists:", itemsMap.get("todo-1"))
+     * }
      */
     get state(): Map<TKey, T>;
     /**
@@ -339,8 +428,24 @@ export declare class CollectionImpl<T extends object = Record<string, unknown>,
     currentStateAsChanges(): Array<ChangeMessage<T>>;
     /**
      * Subscribe to changes in the collection
-     * @param callback - A function that will be called with the changes in the collection
-     * @returns A function that can be called to unsubscribe from the changes
+     * @param callback - Function called when items change
+     * @param options.includeInitialState - If true, immediately calls callback with current data
+     * @returns Unsubscribe function - Call this to stop listening for changes
+     * @example
+     * // Basic subscription
+     * const unsubscribe = collection.subscribeChanges((changes) => {
+     *   changes.forEach(change => {
+     *     console.log(`${change.type}: ${change.key}`, change.value)
+     *   })
+     * })
+     *
+     * // Later: unsubscribe()
+     *
+     * @example
+     * // Include current state immediately
+     * const unsubscribe = collection.subscribeChanges((changes) => {
+     *   updateUI(changes)
+     * }, { includeInitialState: true })
      */
     subscribeChanges(callback: (changes: Array<ChangeMessage<T>>) => void, { includeInitialState }?: {
         includeInitialState?: boolean;

package/dist/esm/collection.js

@@ -247,7 +247,10 @@ class CollectionImpl {
       } else {
         const directOpTransaction = createTransaction({
           mutationFn: async (params) => {
-            return this.config.onInsert(params);
+            return this.config.onInsert({
+              ...params,
+              collection: this
+            });
           }
         });
         directOpTransaction.applyMutations(mutations);
@@ -302,7 +305,10 @@ class CollectionImpl {
       const directOpTransaction = createTransaction({
         autoCommit: true,
         mutationFn: async (params) => {
-          return this.config.onDelete(params);
+          return this.config.onDelete({
+            ...params,
+            collection: this
+          });
         }
       });
       directOpTransaction.applyMutations(mutations);
@@ -340,6 +346,11 @@ class CollectionImpl {
    * Register a callback to be executed on the next commit
    * Useful for preloading collections
    * @param callback Function to call after the next commit
+   * @example
+   * collection.onFirstCommit(() => {
+   *   console.log('Collection has received first data')
+   *   // Safe to access collection.state now
+   * })
    */
   onFirstCommit(callback) {
     this.onFirstCommitCallbacks.push(callback);
@@ -376,7 +387,8 @@ class CollectionImpl {
     }
     const validTransitions = {
       idle: [`loading`, `error`, `cleaned-up`],
-      loading: [`ready`, `error`, `cleaned-up`],
+      loading: [`initialCommit`, `error`, `cleaned-up`],
+      initialCommit: [`ready`, `error`, `cleaned-up`],
       ready: [`cleaned-up`, `error`],
       error: [`cleaned-up`, `idle`],
       "cleaned-up": [`loading`, `error`]
@@ -458,9 +470,12 @@ class CollectionImpl {
           }
           pendingTransaction.committed = true;
           if (this._status === `loading`) {
-            this.setStatus(`ready`);
+            this.setStatus(`initialCommit`);
           }
           this.commitPendingTransactions();
+          if (this._status === `initialCommit`) {
+            this.setStatus(`ready`);
+          }
         }
       });
       this.syncCleanupFn = typeof cleanupFn === `function` ? cleanupFn : null;
@@ -1031,7 +1046,10 @@ class CollectionImpl {
     }
     const directOpTransaction = createTransaction({
       mutationFn: async (params) => {
-        return this.config.onUpdate(params);
+        return this.config.onUpdate({
+          ...params,
+          collection: this
+        });
       }
     });
     directOpTransaction.applyMutations(mutations);
@@ -1042,8 +1060,19 @@ class CollectionImpl {
   }
   /**
    * Gets the current state of the collection as a Map
+   * @returns Map containing all items in the collection, with keys as identifiers
+   * @example
+   * const itemsMap = collection.state
+   * console.log(`Collection has ${itemsMap.size} items`)
+   *
+   * for (const [key, item] of itemsMap) {
+   *   console.log(`${key}: ${item.title}`)
+   * }
    *
-   * @returns A Map containing all items in the collection, with keys as identifiers
+   * // Check if specific item exists
+   * if (itemsMap.has("todo-1")) {
+   *   console.log("Todo 1 exists:", itemsMap.get("todo-1"))
+   * }
    */
   get state() {
     const result = /* @__PURE__ */ new Map();
@@ -1105,8 +1134,24 @@ class CollectionImpl {
   }
   /**
    * Subscribe to changes in the collection
-   * @param callback - A function that will be called with the changes in the collection
-   * @returns A function that can be called to unsubscribe from the changes
+   * @param callback - Function called when items change
+   * @param options.includeInitialState - If true, immediately calls callback with current data
+   * @returns Unsubscribe function - Call this to stop listening for changes
+   * @example
+   * // Basic subscription
+   * const unsubscribe = collection.subscribeChanges((changes) => {
+   *   changes.forEach(change => {
+   *     console.log(`${change.type}: ${change.key}`, change.value)
+   *   })
+   * })
+   *
+   * // Later: unsubscribe()
+   *
+   * @example
+   * // Include current state immediately
+   * const unsubscribe = collection.subscribeChanges((changes) => {
+   *   updateUI(changes)
+   * }, { includeInitialState: true })
    */
   subscribeChanges(callback, { includeInitialState = false } = {}) {
     this.addSubscriber();