@tanstack/db 0.0.22 → 0.0.23

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\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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"}
+{"version":3,"file":"transactions.js","sources":["../../src/transactions.ts"],"sourcesContent":["import { createDeferred } from \"./deferred\"\nimport type { Deferred } from \"./deferred\"\nimport type {\n  MutationFn,\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<T extends object = Record<string, unknown>>(\n  config: TransactionConfig<T>\n): Transaction<T> {\n  const newTransaction = new Transaction<T>(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<T extends object = Record<string, unknown>> {\n  public id: string\n  public state: TransactionState\n  public mutationFn: MutationFn<T>\n  public mutations: Array<PendingMutation<T>>\n  public isPersisted: Deferred<Transaction<T>>\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>>()\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

@@ -8,6 +8,24 @@ import { Transaction } from './transactions.js';
  * @internal This is used by the type resolution system
  */
 export type InferSchemaOutput<T> = T extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<T> extends object ? StandardSchemaV1.InferOutput<T> : Record<string, unknown> : Record<string, unknown>;
+/**
+ * Helper type to extract the input type from a standard schema
+ *
+ * @internal This is used for collection insert type inference
+ */
+export type InferSchemaInput<T> = T extends StandardSchemaV1 ? StandardSchemaV1.InferInput<T> extends object ? StandardSchemaV1.InferInput<T> : Record<string, unknown> : Record<string, unknown>;
+/**
+ * Helper type to determine the insert input type
+ * This takes the raw generics (TExplicit, TSchema, TFallback) instead of the resolved T.
+ *
+ * Priority:
+ * 1. Explicit generic TExplicit (if not 'unknown')
+ * 2. Schema input type (if schema provided)
+ * 3. Fallback type TFallback
+ *
+ * @internal This is used for collection insert type inference
+ */
+export type ResolveInsertInput<TExplicit = unknown, TSchema extends StandardSchemaV1 = never, TFallback extends object = Record<string, unknown>> = unknown extends TExplicit ? [TSchema] extends [never] ? TFallback : InferSchemaInput<TSchema> : TExplicit extends object ? TExplicit : Record<string, unknown>;
 /**
  * Helper type to determine the final type based on priority:
  * 1. Explicit generic TExplicit (if not 'unknown')
@@ -28,25 +46,32 @@ export type Fn = (...args: Array<any>) => any;
  * A record of utility functions that can be attached to a collection
  */
 export type UtilsRecord = Record<string, Fn>;
+/**
+ *
+ * @remarks `update` and `insert` are both represented as `Partial<T>`, but changes for `insert` could me made more precise by inferring the schema input type. In practice, this has almost 0 real world impact so it's not worth the added type complexity.
+ *
+ * @see  https://github.com/TanStack/db/pull/209#issuecomment-3053001206
+ */
+export type ResolveTransactionChanges<T extends object = Record<string, unknown>, TOperation extends OperationType = OperationType> = TOperation extends `delete` ? T : Partial<T>;
 /**
  * Represents a pending mutation within a transaction
  * Contains information about the original and modified data, as well as metadata
  */
-export interface PendingMutation<T extends object = Record<string, unknown>, TOperation extends OperationType = OperationType> {
+export interface PendingMutation<T extends object = Record<string, unknown>, TOperation extends OperationType = OperationType, TCollection extends Collection<T, any, any, any, any> = Collection<T, any, any, any, any>> {
     mutationId: string;
     original: TOperation extends `insert` ? {} : T;
     modified: T;
-    changes: TOperation extends `insert` ? T : TOperation extends `delete` ? T : Partial<T>;
+    changes: ResolveTransactionChanges<T, TOperation>;
     globalKey: string;
     key: any;
-    type: OperationType;
+    type: TOperation;
     metadata: unknown;
     syncMetadata: Record<string, unknown>;
     /** Whether this mutation should be applied optimistically (defaults to true) */
     optimistic: boolean;
     createdAt: Date;
     updatedAt: Date;
-    collection: Collection<T, any, any>;
+    collection: TCollection;
 }
 /**
  * Configuration options for creating a new transaction
@@ -63,7 +88,7 @@ export type NonEmptyArray<T> = [T, ...Array<T>];
  * Utility type for a Transaction with at least one mutation
  * This is used internally by the Transaction.commit method
  */
-export type TransactionWithMutations<T extends object = Record<string, unknown>, TOperation extends OperationType = OperationType> = Transaction<T, TOperation> & {
+export type TransactionWithMutations<T extends object = Record<string, unknown>, TOperation extends OperationType = OperationType> = Transaction<T> & {
     mutations: NonEmptyArray<PendingMutation<T, TOperation>>;
 };
 export interface TransactionConfig<T extends object = Record<string, unknown>> {
@@ -77,11 +102,11 @@ export interface TransactionConfig<T extends object = Record<string, unknown>> {
 /**
  * Options for the createOptimisticAction helper
  */
-export interface CreateOptimisticActionsOptions<TVars = unknown> extends Omit<TransactionConfig, `mutationFn`> {
+export interface CreateOptimisticActionsOptions<TVars = unknown, T extends object = Record<string, unknown>> extends Omit<TransactionConfig<T>, `mutationFn`> {
     /** Function to apply optimistic updates locally before the mutation completes */
     onMutate: (vars: TVars) => void;
     /** Function to execute the mutation on the server */
-    mutationFn: (vars: TVars, params: MutationFnParams) => Promise<any>;
+    mutationFn: (vars: TVars, params: MutationFnParams<T>) => Promise<any>;
 }
 export type { Transaction };
 type Value<TExtensions = never> = string | number | boolean | bigint | null | TExtensions | Array<Value<TExtensions>> | {
@@ -91,7 +116,7 @@ export type Row<TExtensions = never> = Record<string, Value<TExtensions>>;
 export type OperationType = `insert` | `update` | `delete`;
 export interface SyncConfig<T extends object = Record<string, unknown>, TKey extends string | number = string | number> {
     sync: (params: {
-        collection: Collection<T, TKey>;
+        collection: Collection<T, TKey, any, any, any>;
         begin: () => void;
         write: (message: Omit<ChangeMessage<T>, `key`>) => void;
         commit: () => void;
@@ -189,7 +214,7 @@ export type CollectionStatus =
  | `error`
 /** Collection has been cleaned up and resources freed */
  | `cleaned-up`;
-export interface CollectionConfig<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TSchema extends StandardSchemaV1 = StandardSchemaV1> {
+export interface CollectionConfig<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TSchema extends StandardSchemaV1 = StandardSchemaV1, TInsertInput extends object = T> {
     id?: string;
     sync: SyncConfig<T, TKey>;
     schema?: TSchema;
@@ -265,7 +290,7 @@ export interface CollectionConfig<T extends object = Record<string, unknown>, TK
      *   })
      * }
      */
-    onInsert?: InsertMutationFn<T, TKey>;
+    onInsert?: InsertMutationFn<TInsertInput, TKey>;
     /**
      * Optional asynchronous handler function called before an update operation
      * @param params Object containing transaction and collection information

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.22",
+  "version": "0.0.23",
   "dependencies": {
     "@electric-sql/d2mini": "^0.1.7",
     "@standard-schema/spec": "^1.0.0"

package/src/collection.ts

@@ -12,15 +12,17 @@ import type {
   OperationConfig,
   OptimisticChangeMessage,
   PendingMutation,
+  ResolveInsertInput,
   ResolveType,
   StandardSchema,
   Transaction as TransactionType,
+  TransactionWithMutations,
   UtilsRecord,
 } from "./types"
 import type { StandardSchemaV1 } from "@standard-schema/spec"
 
 // Store collections in memory
-export const collectionsStore = new Map<string, CollectionImpl<any, any>>()
+export const collectionsStore = new Map<string, CollectionImpl<any, any, any>>()
 
 interface PendingSyncedTransaction<T extends object = Record<string, unknown>> {
   committed: boolean
@@ -32,12 +34,15 @@ interface PendingSyncedTransaction<T extends object = Record<string, unknown>> {
  * @template T - The type of items in the collection
  * @template TKey - The type of the key for the collection
  * @template TUtils - The utilities record type
+ * @template TInsertInput - The type for insert operations (can be different from T for schemas with defaults)
  */
 export interface Collection<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
   TUtils extends UtilsRecord = {},
-> extends CollectionImpl<T, TKey> {
+  TSchema extends StandardSchemaV1 = StandardSchemaV1,
+  TInsertInput extends object = T,
+> extends CollectionImpl<T, TKey, TUtils, TSchema, TInsertInput> {
   readonly utils: TUtils
 }
 
@@ -124,12 +129,22 @@ export function createCollection<
   options: CollectionConfig<
     ResolveType<TExplicit, TSchema, TFallback>,
     TKey,
-    TSchema
+    TSchema,
+    ResolveInsertInput<TExplicit, TSchema, TFallback>
   > & { utils?: TUtils }
-): Collection<ResolveType<TExplicit, TSchema, TFallback>, TKey, TUtils> {
+): Collection<
+  ResolveType<TExplicit, TSchema, TFallback>,
+  TKey,
+  TUtils,
+  TSchema,
+  ResolveInsertInput<TExplicit, TSchema, TFallback>
+> {
   const collection = new CollectionImpl<
     ResolveType<TExplicit, TSchema, TFallback>,
-    TKey
+    TKey,
+    TUtils,
+    TSchema,
+    ResolveInsertInput<TExplicit, TSchema, TFallback>
   >(options)
 
   // Copy utils to both top level and .utils namespace
@@ -142,7 +157,9 @@ export function createCollection<
   return collection as Collection<
     ResolveType<TExplicit, TSchema, TFallback>,
     TKey,
-    TUtils
+    TUtils,
+    TSchema,
+    ResolveInsertInput<TExplicit, TSchema, TFallback>
   >
 }
 
@@ -179,8 +196,10 @@ export class CollectionImpl<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
   TUtils extends UtilsRecord = {},
+  TSchema extends StandardSchemaV1 = StandardSchemaV1,
+  TInsertInput extends object = T,
 > {
-  public config: CollectionConfig<T, TKey, any>
+  public config: CollectionConfig<T, TKey, TSchema, TInsertInput>
 
   // Core state - make public for testing
   public transactions: SortedMap<string, Transaction<any>>
@@ -312,7 +331,7 @@ export class CollectionImpl<
    * @param config - Configuration object for the collection
    * @throws Error if sync config is missing
    */
-  constructor(config: CollectionConfig<T, TKey, any>) {
+  constructor(config: CollectionConfig<T, TKey, TSchema, TInsertInput>) {
     // eslint-disable-next-line
     if (!config) {
       throw new Error(`Collection requires a config`)
@@ -1322,9 +1341,11 @@ export class CollectionImpl<
    *   console.log('Insert failed:', error)
    * }
    */
-  insert = (data: T | Array<T>, config?: InsertConfig) => {
+  insert = (
+    data: TInsertInput | Array<TInsertInput>,
+    config?: InsertConfig
+  ) => {
     this.validateCollectionUsable(`insert`)
-
     const ambientTransaction = getActiveTransaction()
 
     // If no ambient transaction exists, check for an onInsert handler early
@@ -1335,7 +1356,7 @@ export class CollectionImpl<
     }
 
     const items = Array.isArray(data) ? data : [data]
-    const mutations: Array<PendingMutation<T, `insert`>> = []
+    const mutations: Array<PendingMutation<T>> = []
 
     // Create mutations for each item
     items.forEach((item) => {
@@ -1343,7 +1364,7 @@ export class CollectionImpl<
       const validatedData = this.validateData(item, `insert`)
 
       // Check if an item with this ID already exists in the collection
-      const key = this.getKeyFromItem(item)
+      const key = this.getKeyFromItem(validatedData)
       if (this.has(key)) {
         throw `Cannot insert document with ID "${key}" because it already exists in the collection`
       }
@@ -1353,7 +1374,15 @@ export class CollectionImpl<
         mutationId: crypto.randomUUID(),
         original: {},
         modified: validatedData,
-        changes: validatedData,
+        // Pick the values from validatedData based on what's passed in - this is for cases
+        // where a schema has default values. The validated data has the extra default
+        // values but for changes, we just want to show the data that was actually passed in.
+        changes: Object.fromEntries(
+          Object.keys(item).map((k) => [
+            k,
+            validatedData[k as keyof typeof validatedData],
+          ])
+        ) as TInsertInput,
         globalKey,
         key,
         metadata: config?.metadata as unknown,
@@ -1381,8 +1410,12 @@ export class CollectionImpl<
       const directOpTransaction = createTransaction<T>({
         mutationFn: async (params) => {
           // Call the onInsert handler with the transaction and collection
-          return this.config.onInsert!({
-            ...params,
+          return await this.config.onInsert!({
+            transaction:
+              params.transaction as unknown as TransactionWithMutations<
+                TInsertInput,
+                `insert`
+              >,
             collection: this as unknown as Collection<T, TKey, TUtils>,
           })
         },
@@ -1526,7 +1559,7 @@ export class CollectionImpl<
     }
 
     // Create mutations for each object that has changes
-    const mutations: Array<PendingMutation<T, `update`>> = keysArray
+    const mutations: Array<PendingMutation<T, `update`, this>> = keysArray
       .map((key, index) => {
         const itemChanges = changesArray[index] // User-provided changes for this specific item
 
@@ -1581,7 +1614,7 @@ export class CollectionImpl<
           collection: this,
         }
       })
-      .filter(Boolean) as Array<PendingMutation<T, `update`>>
+      .filter(Boolean) as Array<PendingMutation<T, `update`, this>>
 
     // If no changes were made, return an empty transaction early
     if (mutations.length === 0) {
@@ -1609,7 +1642,11 @@ export class CollectionImpl<
       mutationFn: async (params) => {
         // Call the onUpdate handler with the transaction and collection
         return this.config.onUpdate!({
-          ...params,
+          transaction:
+            params.transaction as unknown as TransactionWithMutations<
+              T,
+              `update`
+            >,
           collection: this as unknown as Collection<T, TKey, TUtils>,
         })
       },
@@ -1677,7 +1714,7 @@ export class CollectionImpl<
     }
 
     const keysArray = Array.isArray(keys) ? keys : [keys]
-    const mutations: Array<PendingMutation<T, `delete`>> = []
+    const mutations: Array<PendingMutation<T, `delete`, this>> = []
 
     for (const key of keysArray) {
       if (!this.has(key)) {
@@ -1686,7 +1723,7 @@ export class CollectionImpl<
         )
       }
       const globalKey = this.generateGlobalKey(key, this.get(key)!)
-      const mutation: PendingMutation<T, `delete`> = {
+      const mutation: PendingMutation<T, `delete`, this> = {
         mutationId: crypto.randomUUID(),
         original: this.get(key)!,
         modified: this.get(key)!,
@@ -1724,7 +1761,11 @@ export class CollectionImpl<
       mutationFn: async (params) => {
         // Call the onDelete handler with the transaction and collection
         return this.config.onDelete!({
-          ...params,
+          transaction:
+            params.transaction as unknown as TransactionWithMutations<
+              T,
+              `delete`
+            >,
           collection: this as unknown as Collection<T, TKey, TUtils>,
         })
       },

package/src/local-storage.ts

@@ -393,7 +393,7 @@ export function localStorageCollectionOptions<
     // Remove items
     params.transaction.mutations.forEach((mutation) => {
       // For delete operations, mutation.original contains the full object
-      const key = config.getKey(mutation.original)
+      const key = config.getKey(mutation.original as ResolvedType)
       currentData.delete(key)
     })
 
@@ -506,7 +506,7 @@ function createLocalStorageSync<T extends object>(
   storageKey: string,
   storage: StorageApi,
   storageEventApi: StorageEventApi,
-  getKey: (item: T) => string | number,
+  _getKey: (item: T) => string | number,
   lastKnownData: Map<string | number, StoredItem<T>>
 ): SyncConfig<T> & { manualTrigger?: () => void } {
   let syncParams: Parameters<SyncConfig<T>[`sync`]>[0] | null = null

package/src/transactions.ts

@@ -2,7 +2,6 @@ import { createDeferred } from "./deferred"
 import type { Deferred } from "./deferred"
 import type {
   MutationFn,
-  OperationType,
   PendingMutation,
   TransactionConfig,
   TransactionState,
@@ -66,10 +65,10 @@ let sequenceNumber = 0
  * // Commit later
  * await tx.commit()
  */
-export function createTransaction<
-  TData extends object = Record<string, unknown>,
->(config: TransactionConfig<TData>): Transaction<TData> {
-  const newTransaction = new Transaction<TData>(config)
+export function createTransaction<T extends object = Record<string, unknown>>(
+  config: TransactionConfig<T>
+): Transaction<T> {
+  const newTransaction = new Transaction<T>(config)
   transactions.push(newTransaction)
   return newTransaction
 }
@@ -108,15 +107,12 @@ function removeFromPendingList(tx: Transaction<any>) {
   }
 }
 
-class Transaction<
-  T extends object = Record<string, unknown>,
-  TOperation extends OperationType = OperationType,
-> {
+class Transaction<T extends object = Record<string, unknown>> {
   public id: string
   public state: TransactionState
   public mutationFn: MutationFn<T>
-  public mutations: Array<PendingMutation<T, TOperation>>
-  public isPersisted: Deferred<Transaction<T, TOperation>>
+  public mutations: Array<PendingMutation<T>>
+  public isPersisted: Deferred<Transaction<T>>
   public autoCommit: boolean
   public createdAt: Date
   public sequenceNumber: number
@@ -134,7 +130,7 @@ class Transaction<
     this.mutationFn = config.mutationFn
     this.state = `pending`
     this.mutations = []
-    this.isPersisted = createDeferred<Transaction<T, TOperation>>()
+    this.isPersisted = createDeferred<Transaction<T>>()
     this.autoCommit = config.autoCommit ?? true
     this.createdAt = new Date()
     this.sequenceNumber = sequenceNumber++

package/src/types.ts

@@ -14,6 +14,40 @@ export type InferSchemaOutput<T> = T extends StandardSchemaV1
     : Record<string, unknown>
   : Record<string, unknown>
 
+/**
+ * Helper type to extract the input type from a standard schema
+ *
+ * @internal This is used for collection insert type inference
+ */
+export type InferSchemaInput<T> = T extends StandardSchemaV1
+  ? StandardSchemaV1.InferInput<T> extends object
+    ? StandardSchemaV1.InferInput<T>
+    : Record<string, unknown>
+  : Record<string, unknown>
+
+/**
+ * Helper type to determine the insert input type
+ * This takes the raw generics (TExplicit, TSchema, TFallback) instead of the resolved T.
+ *
+ * Priority:
+ * 1. Explicit generic TExplicit (if not 'unknown')
+ * 2. Schema input type (if schema provided)
+ * 3. Fallback type TFallback
+ *
+ * @internal This is used for collection insert type inference
+ */
+export type ResolveInsertInput<
+  TExplicit = unknown,
+  TSchema extends StandardSchemaV1 = never,
+  TFallback extends object = Record<string, unknown>,
+> = unknown extends TExplicit
+  ? [TSchema] extends [never]
+    ? TFallback
+    : InferSchemaInput<TSchema>
+  : TExplicit extends object
+    ? TExplicit
+    : Record<string, unknown>
+
 /**
  * Helper type to determine the final type based on priority:
  * 1. Explicit generic TExplicit (if not 'unknown')
@@ -48,6 +82,17 @@ export type Fn = (...args: Array<any>) => any
  */
 export type UtilsRecord = Record<string, Fn>
 
+/**
+ *
+ * @remarks `update` and `insert` are both represented as `Partial<T>`, but changes for `insert` could me made more precise by inferring the schema input type. In practice, this has almost 0 real world impact so it's not worth the added type complexity.
+ *
+ * @see  https://github.com/TanStack/db/pull/209#issuecomment-3053001206
+ */
+export type ResolveTransactionChanges<
+  T extends object = Record<string, unknown>,
+  TOperation extends OperationType = OperationType,
+> = TOperation extends `delete` ? T : Partial<T>
+
 /**
  * Represents a pending mutation within a transaction
  * Contains information about the original and modified data, as well as metadata
@@ -55,25 +100,32 @@ export type UtilsRecord = Record<string, Fn>
 export interface PendingMutation<
   T extends object = Record<string, unknown>,
   TOperation extends OperationType = OperationType,
+  TCollection extends Collection<T, any, any, any, any> = Collection<
+    T,
+    any,
+    any,
+    any,
+    any
+  >,
 > {
   mutationId: string
+  // The state of the object before the mutation.
   original: TOperation extends `insert` ? {} : T
+  // The result state of the object after all mutations.
   modified: T
-  changes: TOperation extends `insert`
-    ? T
-    : TOperation extends `delete`
-      ? T
-      : Partial<T>
+  // Only the actual changes to the object by the mutation.
+  changes: ResolveTransactionChanges<T, TOperation>
   globalKey: string
+
   key: any
-  type: OperationType
+  type: TOperation
   metadata: unknown
   syncMetadata: Record<string, unknown>
   /** Whether this mutation should be applied optimistically (defaults to true) */
   optimistic: boolean
   createdAt: Date
   updatedAt: Date
-  collection: Collection<T, any, any>
+  collection: TCollection
 }
 
 /**
@@ -99,7 +151,7 @@ export type NonEmptyArray<T> = [T, ...Array<T>]
 export type TransactionWithMutations<
   T extends object = Record<string, unknown>,
   TOperation extends OperationType = OperationType,
-> = Transaction<T, TOperation> & {
+> = Transaction<T> & {
   mutations: NonEmptyArray<PendingMutation<T, TOperation>>
 }
 
@@ -116,12 +168,14 @@ export interface TransactionConfig<T extends object = Record<string, unknown>> {
 /**
  * Options for the createOptimisticAction helper
  */
-export interface CreateOptimisticActionsOptions<TVars = unknown>
-  extends Omit<TransactionConfig, `mutationFn`> {
+export interface CreateOptimisticActionsOptions<
+  TVars = unknown,
+  T extends object = Record<string, unknown>,
+> extends Omit<TransactionConfig<T>, `mutationFn`> {
   /** Function to apply optimistic updates locally before the mutation completes */
   onMutate: (vars: TVars) => void
   /** Function to execute the mutation on the server */
-  mutationFn: (vars: TVars, params: MutationFnParams) => Promise<any>
+  mutationFn: (vars: TVars, params: MutationFnParams<T>) => Promise<any>
 }
 
 export type { Transaction }
@@ -145,7 +199,7 @@ export interface SyncConfig<
   TKey extends string | number = string | number,
 > {
   sync: (params: {
-    collection: Collection<T, TKey>
+    collection: Collection<T, TKey, any, any, any>
     begin: () => void
     write: (message: Omit<ChangeMessage<T>, `key`>) => void
     commit: () => void
@@ -232,7 +286,6 @@ export type InsertMutationFnParams<
   transaction: TransactionWithMutations<T, `insert`>
   collection: Collection<T, TKey, TUtils>
 }
-
 export type DeleteMutationFnParams<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
@@ -293,6 +346,7 @@ export interface CollectionConfig<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
   TSchema extends StandardSchemaV1 = StandardSchemaV1,
+  TInsertInput extends object = T,
 > {
   // If an id isn't passed in, a UUID will be
   // generated for it.
@@ -371,7 +425,8 @@ export interface CollectionConfig<
    *   })
    * }
    */
-  onInsert?: InsertMutationFn<T, TKey>
+  onInsert?: InsertMutationFn<TInsertInput, TKey>
+
   /**
    * Optional asynchronous handler function called before an update operation
    * @param params Object containing transaction and collection information