@tanstack/db 0.0.17 → 0.0.18

package/dist/esm/transactions.d.ts

@@ -1,6 +1,69 @@
 import { Deferred } from './deferred.js';
 import { MutationFn, OperationType, PendingMutation, TransactionConfig, TransactionState } from './types.js';
+/**
+ * Creates a new transaction for grouping multiple collection operations
+ * @param config - Transaction configuration with mutation function
+ * @returns A new Transaction instance
+ * @example
+ * // Basic transaction usage
+ * const tx = createTransaction({
+ *   mutationFn: async ({ transaction }) => {
+ *     // Send all mutations to API
+ *     await api.saveChanges(transaction.mutations)
+ *   }
+ * })
+ *
+ * tx.mutate(() => {
+ *   collection.insert({ id: "1", text: "Buy milk" })
+ *   collection.update("2", draft => { draft.completed = true })
+ * })
+ *
+ * await tx.isPersisted.promise
+ *
+ * @example
+ * // Handle transaction errors
+ * try {
+ *   const tx = createTransaction({
+ *     mutationFn: async () => { throw new Error("API failed") }
+ *   })
+ *
+ *   tx.mutate(() => {
+ *     collection.insert({ id: "1", text: "New item" })
+ *   })
+ *
+ *   await tx.isPersisted.promise
+ * } catch (error) {
+ *   console.log('Transaction failed:', error)
+ * }
+ *
+ * @example
+ * // Manual commit control
+ * const tx = createTransaction({
+ *   autoCommit: false,
+ *   mutationFn: async () => {
+ *     // API call
+ *   }
+ * })
+ *
+ * tx.mutate(() => {
+ *   collection.insert({ id: "1", text: "Item" })
+ * })
+ *
+ * // Commit later
+ * await tx.commit()
+ */
 export declare function createTransaction<TData extends object = Record<string, unknown>>(config: TransactionConfig<TData>): Transaction<TData>;
+/**
+ * Gets the currently active ambient transaction, if any
+ * Used internally by collection operations to join existing transactions
+ * @returns The active transaction or undefined if none is active
+ * @example
+ * // Check if operations will join an ambient transaction
+ * const ambientTx = getActiveTransaction()
+ * if (ambientTx) {
+ *   console.log('Operations will join transaction:', ambientTx.id)
+ * }
+ */
 export declare function getActiveTransaction(): Transaction | undefined;
 declare class Transaction<T extends object = Record<string, unknown>, TOperation extends OperationType = OperationType> {
     id: string;
@@ -18,12 +81,128 @@ declare class Transaction<T extends object = Record<string, unknown>, TOperation
     };
     constructor(config: TransactionConfig<T>);
     setState(newState: TransactionState): void;
+    /**
+     * Execute collection operations within this transaction
+     * @param callback - Function containing collection operations to group together
+     * @returns This transaction for chaining
+     * @example
+     * // Group multiple operations
+     * const tx = createTransaction({ mutationFn: async () => {
+     *   // Send to API
+     * }})
+     *
+     * tx.mutate(() => {
+     *   collection.insert({ id: "1", text: "Buy milk" })
+     *   collection.update("2", draft => { draft.completed = true })
+     *   collection.delete("3")
+     * })
+     *
+     * await tx.isPersisted.promise
+     *
+     * @example
+     * // Handle mutate errors
+     * try {
+     *   tx.mutate(() => {
+     *     collection.insert({ id: "invalid" }) // This might throw
+     *   })
+     * } catch (error) {
+     *   console.log('Mutation failed:', error)
+     * }
+     *
+     * @example
+     * // Manual commit control
+     * const tx = createTransaction({ autoCommit: false, mutationFn: async () => {} })
+     *
+     * tx.mutate(() => {
+     *   collection.insert({ id: "1", text: "Item" })
+     * })
+     *
+     * // Commit later when ready
+     * await tx.commit()
+     */
     mutate(callback: () => void): Transaction<T>;
     applyMutations(mutations: Array<PendingMutation<any>>): void;
+    /**
+     * Rollback the transaction and any conflicting transactions
+     * @param config - Configuration for rollback behavior
+     * @returns This transaction for chaining
+     * @example
+     * // Manual rollback
+     * const tx = createTransaction({ mutationFn: async () => {
+     *   // Send to API
+     * }})
+     *
+     * tx.mutate(() => {
+     *   collection.insert({ id: "1", text: "Buy milk" })
+     * })
+     *
+     * // Rollback if needed
+     * if (shouldCancel) {
+     *   tx.rollback()
+     * }
+     *
+     * @example
+     * // Handle rollback cascade (automatic)
+     * const tx1 = createTransaction({ mutationFn: async () => {} })
+     * const tx2 = createTransaction({ mutationFn: async () => {} })
+     *
+     * tx1.mutate(() => collection.update("1", draft => { draft.value = "A" }))
+     * tx2.mutate(() => collection.update("1", draft => { draft.value = "B" })) // Same item
+     *
+     * tx1.rollback() // This will also rollback tx2 due to conflict
+     *
+     * @example
+     * // Handle rollback in error scenarios
+     * try {
+     *   await tx.isPersisted.promise
+     * } catch (error) {
+     *   console.log('Transaction was rolled back:', error)
+     *   // Transaction automatically rolled back on mutation function failure
+     * }
+     */
     rollback(config?: {
         isSecondaryRollback?: boolean;
     }): Transaction<T>;
     touchCollection(): void;
+    /**
+     * Commit the transaction and execute the mutation function
+     * @returns Promise that resolves to this transaction when complete
+     * @example
+     * // Manual commit (when autoCommit is false)
+     * const tx = createTransaction({
+     *   autoCommit: false,
+     *   mutationFn: async ({ transaction }) => {
+     *     await api.saveChanges(transaction.mutations)
+     *   }
+     * })
+     *
+     * tx.mutate(() => {
+     *   collection.insert({ id: "1", text: "Buy milk" })
+     * })
+     *
+     * await tx.commit() // Manually commit
+     *
+     * @example
+     * // Handle commit errors
+     * try {
+     *   const tx = createTransaction({
+     *     mutationFn: async () => { throw new Error("API failed") }
+     *   })
+     *
+     *   tx.mutate(() => {
+     *     collection.insert({ id: "1", text: "Item" })
+     *   })
+     *
+     *   await tx.commit()
+     * } catch (error) {
+     *   console.log('Commit failed, transaction rolled back:', error)
+     * }
+     *
+     * @example
+     * // Check transaction state after commit
+     * await tx.commit()
+     * console.log(tx.state) // "completed" or "failed"
+     */
     commit(): Promise<Transaction<T>>;
     /**
      * Compare two transactions by their createdAt time and sequence number in order

package/dist/esm/transactions.js

@@ -47,6 +47,45 @@ class Transaction {
       removeFromPendingList(this);
     }
   }
+  /**
+   * Execute collection operations within this transaction
+   * @param callback - Function containing collection operations to group together
+   * @returns This transaction for chaining
+   * @example
+   * // Group multiple operations
+   * const tx = createTransaction({ mutationFn: async () => {
+   *   // Send to API
+   * }})
+   *
+   * tx.mutate(() => {
+   *   collection.insert({ id: "1", text: "Buy milk" })
+   *   collection.update("2", draft => { draft.completed = true })
+   *   collection.delete("3")
+   * })
+   *
+   * await tx.isPersisted.promise
+   *
+   * @example
+   * // Handle mutate errors
+   * try {
+   *   tx.mutate(() => {
+   *     collection.insert({ id: "invalid" }) // This might throw
+   *   })
+   * } catch (error) {
+   *   console.log('Mutation failed:', error)
+   * }
+   *
+   * @example
+   * // Manual commit control
+   * const tx = createTransaction({ autoCommit: false, mutationFn: async () => {} })
+   *
+   * tx.mutate(() => {
+   *   collection.insert({ id: "1", text: "Item" })
+   * })
+   *
+   * // Commit later when ready
+   * await tx.commit()
+   */
   mutate(callback) {
     if (this.state !== `pending`) {
       throw `You can no longer call .mutate() as the transaction is no longer pending`;
@@ -74,6 +113,44 @@ class Transaction {
       }
     }
   }
+  /**
+   * Rollback the transaction and any conflicting transactions
+   * @param config - Configuration for rollback behavior
+   * @returns This transaction for chaining
+   * @example
+   * // Manual rollback
+   * const tx = createTransaction({ mutationFn: async () => {
+   *   // Send to API
+   * }})
+   *
+   * tx.mutate(() => {
+   *   collection.insert({ id: "1", text: "Buy milk" })
+   * })
+   *
+   * // Rollback if needed
+   * if (shouldCancel) {
+   *   tx.rollback()
+   * }
+   *
+   * @example
+   * // Handle rollback cascade (automatic)
+   * const tx1 = createTransaction({ mutationFn: async () => {} })
+   * const tx2 = createTransaction({ mutationFn: async () => {} })
+   *
+   * tx1.mutate(() => collection.update("1", draft => { draft.value = "A" }))
+   * tx2.mutate(() => collection.update("1", draft => { draft.value = "B" })) // Same item
+   *
+   * tx1.rollback() // This will also rollback tx2 due to conflict
+   *
+   * @example
+   * // Handle rollback in error scenarios
+   * try {
+   *   await tx.isPersisted.promise
+   * } catch (error) {
+   *   console.log('Transaction was rolled back:', error)
+   *   // Transaction automatically rolled back on mutation function failure
+   * }
+   */
   rollback(config) {
     var _a;
     const isSecondaryRollback = (config == null ? void 0 : config.isSecondaryRollback) ?? false;
@@ -105,6 +182,45 @@ class Transaction {
       }
     }
   }
+  /**
+   * Commit the transaction and execute the mutation function
+   * @returns Promise that resolves to this transaction when complete
+   * @example
+   * // Manual commit (when autoCommit is false)
+   * const tx = createTransaction({
+   *   autoCommit: false,
+   *   mutationFn: async ({ transaction }) => {
+   *     await api.saveChanges(transaction.mutations)
+   *   }
+   * })
+   *
+   * tx.mutate(() => {
+   *   collection.insert({ id: "1", text: "Buy milk" })
+   * })
+   *
+   * await tx.commit() // Manually commit
+   *
+   * @example
+   * // Handle commit errors
+   * try {
+   *   const tx = createTransaction({
+   *     mutationFn: async () => { throw new Error("API failed") }
+   *   })
+   *
+   *   tx.mutate(() => {
+   *     collection.insert({ id: "1", text: "Item" })
+   *   })
+   *
+   *   await tx.commit()
+   * } catch (error) {
+   *   console.log('Commit failed, transaction rolled back:', error)
+   * }
+   *
+   * @example
+   * // Check transaction state after commit
+   * await tx.commit()
+   * console.log(tx.state) // "completed" or "failed"
+   */
   async commit() {
     if (this.state !== `pending`) {
       throw `You can no longer call .commit() as the transaction is no longer pending`;

package/dist/esm/transactions.js.map

@@ -1 +1 @@
-{"version":3,"file":"transactions.js","sources":["../../src/transactions.ts"],"sourcesContent":["import { createDeferred } from \"./deferred\"\nimport type { Deferred } from \"./deferred\"\nimport type {\n  MutationFn,\n  OperationType,\n  PendingMutation,\n  TransactionConfig,\n  TransactionState,\n  TransactionWithMutations,\n} from \"./types\"\n\nconst transactions: Array<Transaction<any>> = []\nlet transactionStack: Array<Transaction<any>> = []\n\nlet sequenceNumber = 0\n\nexport function createTransaction<\n  TData extends object = Record<string, unknown>,\n>(config: TransactionConfig<TData>): Transaction<TData> {\n  const newTransaction = new Transaction<TData>(config)\n  transactions.push(newTransaction)\n  return newTransaction\n}\n\nexport function getActiveTransaction(): Transaction | undefined {\n  if (transactionStack.length > 0) {\n    return transactionStack.slice(-1)[0]\n  } else {\n    return undefined\n  }\n}\n\nfunction registerTransaction(tx: Transaction<any>) {\n  transactionStack.push(tx)\n}\n\nfunction unregisterTransaction(tx: Transaction<any>) {\n  transactionStack = transactionStack.filter((t) => t.id !== tx.id)\n}\n\nfunction removeFromPendingList(tx: Transaction<any>) {\n  const index = transactions.findIndex((t) => t.id === tx.id)\n  if (index !== -1) {\n    transactions.splice(index, 1)\n  }\n}\n\nclass Transaction<\n  T extends object = Record<string, unknown>,\n  TOperation extends OperationType = OperationType,\n> {\n  public id: string\n  public state: TransactionState\n  public mutationFn: MutationFn<T>\n  public mutations: Array<PendingMutation<T, TOperation>>\n  public isPersisted: Deferred<Transaction<T, TOperation>>\n  public autoCommit: boolean\n  public createdAt: Date\n  public sequenceNumber: number\n  public metadata: Record<string, unknown>\n  public error?: {\n    message: string\n    error: Error\n  }\n\n  constructor(config: TransactionConfig<T>) {\n    if (typeof config.mutationFn === `undefined`) {\n      throw `mutationFn is required when creating a transaction`\n    }\n    this.id = config.id ?? crypto.randomUUID()\n    this.mutationFn = config.mutationFn\n    this.state = `pending`\n    this.mutations = []\n    this.isPersisted = createDeferred<Transaction<T, TOperation>>()\n    this.autoCommit = config.autoCommit ?? true\n    this.createdAt = new Date()\n    this.sequenceNumber = sequenceNumber++\n    this.metadata = config.metadata ?? {}\n  }\n\n  setState(newState: TransactionState) {\n    this.state = newState\n\n    if (newState === `completed` || newState === `failed`) {\n      removeFromPendingList(this)\n    }\n  }\n\n  mutate(callback: () => void): Transaction<T> {\n    if (this.state !== `pending`) {\n      throw `You can no longer call .mutate() as the transaction is no longer pending`\n    }\n\n    registerTransaction(this)\n    try {\n      callback()\n    } finally {\n      unregisterTransaction(this)\n    }\n\n    if (this.autoCommit) {\n      this.commit()\n    }\n\n    return this\n  }\n\n  applyMutations(mutations: Array<PendingMutation<any>>): void {\n    for (const newMutation of mutations) {\n      const existingIndex = this.mutations.findIndex(\n        (m) => m.globalKey === newMutation.globalKey\n      )\n\n      if (existingIndex >= 0) {\n        // Replace existing mutation\n        this.mutations[existingIndex] = newMutation\n      } else {\n        // Insert new mutation\n        this.mutations.push(newMutation)\n      }\n    }\n  }\n\n  rollback(config?: { isSecondaryRollback?: boolean }): Transaction<T> {\n    const isSecondaryRollback = config?.isSecondaryRollback ?? false\n    if (this.state === `completed`) {\n      throw `You can no longer call .rollback() as the transaction is already completed`\n    }\n\n    this.setState(`failed`)\n\n    // See if there's any other transactions w/ mutations on the same ids\n    // and roll them back as well.\n    if (!isSecondaryRollback) {\n      const mutationIds = new Set()\n      this.mutations.forEach((m) => mutationIds.add(m.globalKey))\n      for (const t of transactions) {\n        t.state === `pending` &&\n          t.mutations.some((m) => mutationIds.has(m.globalKey)) &&\n          t.rollback({ isSecondaryRollback: true })\n      }\n    }\n\n    // Reject the promise\n    this.isPersisted.reject(this.error?.error)\n    this.touchCollection()\n\n    return this\n  }\n\n  // Tell collection that something has changed with the transaction\n  touchCollection(): void {\n    const hasCalled = new Set()\n    for (const mutation of this.mutations) {\n      if (!hasCalled.has(mutation.collection.id)) {\n        mutation.collection.onTransactionStateChange()\n\n        // Only call commitPendingTransactions if there are pending sync transactions\n        if (mutation.collection.pendingSyncedTransactions.length > 0) {\n          mutation.collection.commitPendingTransactions()\n        }\n\n        hasCalled.add(mutation.collection.id)\n      }\n    }\n  }\n\n  async commit(): Promise<Transaction<T>> {\n    if (this.state !== `pending`) {\n      throw `You can no longer call .commit() as the transaction is no longer pending`\n    }\n\n    this.setState(`persisting`)\n\n    if (this.mutations.length === 0) {\n      this.setState(`completed`)\n\n      return this\n    }\n\n    // Run mutationFn\n    try {\n      // At this point we know there's at least one mutation\n      // We've already verified mutations is non-empty, so this cast is safe\n      // Use a direct type assertion instead of object spreading to preserve the original type\n      await this.mutationFn({\n        transaction: this as unknown as TransactionWithMutations<T>,\n      })\n\n      this.setState(`completed`)\n      this.touchCollection()\n\n      this.isPersisted.resolve(this)\n    } catch (error) {\n      // Update transaction with error information\n      this.error = {\n        message: error instanceof Error ? error.message : String(error),\n        error: error instanceof Error ? error : new Error(String(error)),\n      }\n\n      // rollback the transaction\n      return this.rollback()\n    }\n\n    return this\n  }\n\n  /**\n   * Compare two transactions by their createdAt time and sequence number in order\n   * to sort them in the order they were created.\n   * @param other - The other transaction to compare to\n   * @returns -1 if this transaction was created before the other, 1 if it was created after, 0 if they were created at the same time\n   */\n  compareCreatedAt(other: Transaction<any>): number {\n    const createdAtComparison =\n      this.createdAt.getTime() - other.createdAt.getTime()\n    if (createdAtComparison !== 0) {\n      return createdAtComparison\n    }\n    return this.sequenceNumber - other.sequenceNumber\n  }\n}\n\nexport type { Transaction }\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"transactions.js","sources":["../../src/transactions.ts"],"sourcesContent":["import { createDeferred } from \"./deferred\"\nimport type { Deferred } from \"./deferred\"\nimport type {\n  MutationFn,\n  OperationType,\n  PendingMutation,\n  TransactionConfig,\n  TransactionState,\n  TransactionWithMutations,\n} from \"./types\"\n\nconst transactions: Array<Transaction<any>> = []\nlet transactionStack: Array<Transaction<any>> = []\n\nlet sequenceNumber = 0\n\n/**\n * Creates a new transaction for grouping multiple collection operations\n * @param config - Transaction configuration with mutation function\n * @returns A new Transaction instance\n * @example\n * // Basic transaction usage\n * const tx = createTransaction({\n *   mutationFn: async ({ transaction }) => {\n *     // Send all mutations to API\n *     await api.saveChanges(transaction.mutations)\n *   }\n * })\n *\n * tx.mutate(() => {\n *   collection.insert({ id: \"1\", text: \"Buy milk\" })\n *   collection.update(\"2\", draft => { draft.completed = true })\n * })\n *\n * await tx.isPersisted.promise\n *\n * @example\n * // Handle transaction errors\n * try {\n *   const tx = createTransaction({\n *     mutationFn: async () => { throw new Error(\"API failed\") }\n *   })\n *\n *   tx.mutate(() => {\n *     collection.insert({ id: \"1\", text: \"New item\" })\n *   })\n *\n *   await tx.isPersisted.promise\n * } catch (error) {\n *   console.log('Transaction failed:', error)\n * }\n *\n * @example\n * // Manual commit control\n * const tx = createTransaction({\n *   autoCommit: false,\n *   mutationFn: async () => {\n *     // API call\n *   }\n * })\n *\n * tx.mutate(() => {\n *   collection.insert({ id: \"1\", text: \"Item\" })\n * })\n *\n * // Commit later\n * await tx.commit()\n */\nexport function createTransaction<\n  TData extends object = Record<string, unknown>,\n>(config: TransactionConfig<TData>): Transaction<TData> {\n  const newTransaction = new Transaction<TData>(config)\n  transactions.push(newTransaction)\n  return newTransaction\n}\n\n/**\n * Gets the currently active ambient transaction, if any\n * Used internally by collection operations to join existing transactions\n * @returns The active transaction or undefined if none is active\n * @example\n * // Check if operations will join an ambient transaction\n * const ambientTx = getActiveTransaction()\n * if (ambientTx) {\n *   console.log('Operations will join transaction:', ambientTx.id)\n * }\n */\nexport function getActiveTransaction(): Transaction | undefined {\n  if (transactionStack.length > 0) {\n    return transactionStack.slice(-1)[0]\n  } else {\n    return undefined\n  }\n}\n\nfunction registerTransaction(tx: Transaction<any>) {\n  transactionStack.push(tx)\n}\n\nfunction unregisterTransaction(tx: Transaction<any>) {\n  transactionStack = transactionStack.filter((t) => t.id !== tx.id)\n}\n\nfunction removeFromPendingList(tx: Transaction<any>) {\n  const index = transactions.findIndex((t) => t.id === tx.id)\n  if (index !== -1) {\n    transactions.splice(index, 1)\n  }\n}\n\nclass Transaction<\n  T extends object = Record<string, unknown>,\n  TOperation extends OperationType = OperationType,\n> {\n  public id: string\n  public state: TransactionState\n  public mutationFn: MutationFn<T>\n  public mutations: Array<PendingMutation<T, TOperation>>\n  public isPersisted: Deferred<Transaction<T, TOperation>>\n  public autoCommit: boolean\n  public createdAt: Date\n  public sequenceNumber: number\n  public metadata: Record<string, unknown>\n  public error?: {\n    message: string\n    error: Error\n  }\n\n  constructor(config: TransactionConfig<T>) {\n    if (typeof config.mutationFn === `undefined`) {\n      throw `mutationFn is required when creating a transaction`\n    }\n    this.id = config.id ?? crypto.randomUUID()\n    this.mutationFn = config.mutationFn\n    this.state = `pending`\n    this.mutations = []\n    this.isPersisted = createDeferred<Transaction<T, TOperation>>()\n    this.autoCommit = config.autoCommit ?? true\n    this.createdAt = new Date()\n    this.sequenceNumber = sequenceNumber++\n    this.metadata = config.metadata ?? {}\n  }\n\n  setState(newState: TransactionState) {\n    this.state = newState\n\n    if (newState === `completed` || newState === `failed`) {\n      removeFromPendingList(this)\n    }\n  }\n\n  /**\n   * Execute collection operations within this transaction\n   * @param callback - Function containing collection operations to group together\n   * @returns This transaction for chaining\n   * @example\n   * // Group multiple operations\n   * const tx = createTransaction({ mutationFn: async () => {\n   *   // Send to API\n   * }})\n   *\n   * tx.mutate(() => {\n   *   collection.insert({ id: \"1\", text: \"Buy milk\" })\n   *   collection.update(\"2\", draft => { draft.completed = true })\n   *   collection.delete(\"3\")\n   * })\n   *\n   * await tx.isPersisted.promise\n   *\n   * @example\n   * // Handle mutate errors\n   * try {\n   *   tx.mutate(() => {\n   *     collection.insert({ id: \"invalid\" }) // This might throw\n   *   })\n   * } catch (error) {\n   *   console.log('Mutation failed:', error)\n   * }\n   *\n   * @example\n   * // Manual commit control\n   * const tx = createTransaction({ autoCommit: false, mutationFn: async () => {} })\n   *\n   * tx.mutate(() => {\n   *   collection.insert({ id: \"1\", text: \"Item\" })\n   * })\n   *\n   * // Commit later when ready\n   * await tx.commit()\n   */\n  mutate(callback: () => void): Transaction<T> {\n    if (this.state !== `pending`) {\n      throw `You can no longer call .mutate() as the transaction is no longer pending`\n    }\n\n    registerTransaction(this)\n    try {\n      callback()\n    } finally {\n      unregisterTransaction(this)\n    }\n\n    if (this.autoCommit) {\n      this.commit()\n    }\n\n    return this\n  }\n\n  applyMutations(mutations: Array<PendingMutation<any>>): void {\n    for (const newMutation of mutations) {\n      const existingIndex = this.mutations.findIndex(\n        (m) => m.globalKey === newMutation.globalKey\n      )\n\n      if (existingIndex >= 0) {\n        // Replace existing mutation\n        this.mutations[existingIndex] = newMutation\n      } else {\n        // Insert new mutation\n        this.mutations.push(newMutation)\n      }\n    }\n  }\n\n  /**\n   * Rollback the transaction and any conflicting transactions\n   * @param config - Configuration for rollback behavior\n   * @returns This transaction for chaining\n   * @example\n   * // Manual rollback\n   * const tx = createTransaction({ mutationFn: async () => {\n   *   // Send to API\n   * }})\n   *\n   * tx.mutate(() => {\n   *   collection.insert({ id: \"1\", text: \"Buy milk\" })\n   * })\n   *\n   * // Rollback if needed\n   * if (shouldCancel) {\n   *   tx.rollback()\n   * }\n   *\n   * @example\n   * // Handle rollback cascade (automatic)\n   * const tx1 = createTransaction({ mutationFn: async () => {} })\n   * const tx2 = createTransaction({ mutationFn: async () => {} })\n   *\n   * tx1.mutate(() => collection.update(\"1\", draft => { draft.value = \"A\" }))\n   * tx2.mutate(() => collection.update(\"1\", draft => { draft.value = \"B\" })) // Same item\n   *\n   * tx1.rollback() // This will also rollback tx2 due to conflict\n   *\n   * @example\n   * // Handle rollback in error scenarios\n   * try {\n   *   await tx.isPersisted.promise\n   * } catch (error) {\n   *   console.log('Transaction was rolled back:', error)\n   *   // Transaction automatically rolled back on mutation function failure\n   * }\n   */\n  rollback(config?: { isSecondaryRollback?: boolean }): Transaction<T> {\n    const isSecondaryRollback = config?.isSecondaryRollback ?? false\n    if (this.state === `completed`) {\n      throw `You can no longer call .rollback() as the transaction is already completed`\n    }\n\n    this.setState(`failed`)\n\n    // See if there's any other transactions w/ mutations on the same ids\n    // and roll them back as well.\n    if (!isSecondaryRollback) {\n      const mutationIds = new Set()\n      this.mutations.forEach((m) => mutationIds.add(m.globalKey))\n      for (const t of transactions) {\n        t.state === `pending` &&\n          t.mutations.some((m) => mutationIds.has(m.globalKey)) &&\n          t.rollback({ isSecondaryRollback: true })\n      }\n    }\n\n    // Reject the promise\n    this.isPersisted.reject(this.error?.error)\n    this.touchCollection()\n\n    return this\n  }\n\n  // Tell collection that something has changed with the transaction\n  touchCollection(): void {\n    const hasCalled = new Set()\n    for (const mutation of this.mutations) {\n      if (!hasCalled.has(mutation.collection.id)) {\n        mutation.collection.onTransactionStateChange()\n\n        // Only call commitPendingTransactions if there are pending sync transactions\n        if (mutation.collection.pendingSyncedTransactions.length > 0) {\n          mutation.collection.commitPendingTransactions()\n        }\n\n        hasCalled.add(mutation.collection.id)\n      }\n    }\n  }\n\n  /**\n   * Commit the transaction and execute the mutation function\n   * @returns Promise that resolves to this transaction when complete\n   * @example\n   * // Manual commit (when autoCommit is false)\n   * const tx = createTransaction({\n   *   autoCommit: false,\n   *   mutationFn: async ({ transaction }) => {\n   *     await api.saveChanges(transaction.mutations)\n   *   }\n   * })\n   *\n   * tx.mutate(() => {\n   *   collection.insert({ id: \"1\", text: \"Buy milk\" })\n   * })\n   *\n   * await tx.commit() // Manually commit\n   *\n   * @example\n   * // Handle commit errors\n   * try {\n   *   const tx = createTransaction({\n   *     mutationFn: async () => { throw new Error(\"API failed\") }\n   *   })\n   *\n   *   tx.mutate(() => {\n   *     collection.insert({ id: \"1\", text: \"Item\" })\n   *   })\n   *\n   *   await tx.commit()\n   * } catch (error) {\n   *   console.log('Commit failed, transaction rolled back:', error)\n   * }\n   *\n   * @example\n   * // Check transaction state after commit\n   * await tx.commit()\n   * console.log(tx.state) // \"completed\" or \"failed\"\n   */\n  async commit(): Promise<Transaction<T>> {\n    if (this.state !== `pending`) {\n      throw `You can no longer call .commit() as the transaction is no longer pending`\n    }\n\n    this.setState(`persisting`)\n\n    if (this.mutations.length === 0) {\n      this.setState(`completed`)\n\n      return this\n    }\n\n    // Run mutationFn\n    try {\n      // At this point we know there's at least one mutation\n      // We've already verified mutations is non-empty, so this cast is safe\n      // Use a direct type assertion instead of object spreading to preserve the original type\n      await this.mutationFn({\n        transaction: this as unknown as TransactionWithMutations<T>,\n      })\n\n      this.setState(`completed`)\n      this.touchCollection()\n\n      this.isPersisted.resolve(this)\n    } catch (error) {\n      // Update transaction with error information\n      this.error = {\n        message: error instanceof Error ? error.message : String(error),\n        error: error instanceof Error ? error : new Error(String(error)),\n      }\n\n      // rollback the transaction\n      return this.rollback()\n    }\n\n    return this\n  }\n\n  /**\n   * Compare two transactions by their createdAt time and sequence number in order\n   * to sort them in the order they were created.\n   * @param other - The other transaction to compare to\n   * @returns -1 if this transaction was created before the other, 1 if it was created after, 0 if they were created at the same time\n   */\n  compareCreatedAt(other: Transaction<any>): number {\n    const createdAtComparison =\n      this.createdAt.getTime() - other.createdAt.getTime()\n    if (createdAtComparison !== 0) {\n      return createdAtComparison\n    }\n    return this.sequenceNumber - other.sequenceNumber\n  }\n}\n\nexport type { Transaction }\n"],"names":[],"mappings":"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"}

package/dist/esm/types.d.ts

@@ -140,20 +140,35 @@ 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) */
@@ -205,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>>;
 /**
@@ -252,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/package.json

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