@tanstack/db 0.4.16 → 0.4.17

package/src/errors.ts

@@ -41,6 +41,32 @@ export class SchemaValidationError extends TanStackDBError {
   }
 }
 
+// Module Instance Errors
+export class DuplicateDbInstanceError extends TanStackDBError {
+  constructor() {
+    super(
+      `Multiple instances of @tanstack/db detected!\n\n` +
+        `This causes transaction context to be lost because each instance maintains ` +
+        `its own transaction stack.\n\n` +
+        `Common causes:\n` +
+        `1. Different versions of @tanstack/db installed\n` +
+        `2. Incompatible peer dependency versions in packages\n` +
+        `3. Module resolution issues in bundler configuration\n\n` +
+        `To fix:\n` +
+        `1. Check installed versions: npm list @tanstack/db (or pnpm/yarn list)\n` +
+        `2. Force a single version using package manager overrides:\n` +
+        `   - npm: "overrides" in package.json\n` +
+        `   - pnpm: "pnpm.overrides" in package.json\n` +
+        `   - yarn: "resolutions" in package.json\n` +
+        `3. Clear node_modules and lockfile, then reinstall\n\n` +
+        `To temporarily disable this check (not recommended):\n` +
+        `Set environment variable: TANSTACK_DB_DISABLE_DUP_CHECK=1\n\n` +
+        `See: https://tanstack.com/db/latest/docs/troubleshooting#duplicate-instances`
+    )
+    this.name = `DuplicateDbInstanceError`
+  }
+}
+
 // Collection Configuration Errors
 export class CollectionConfigurationError extends TanStackDBError {
   constructor(message: string) {
@@ -229,6 +255,15 @@ export class MissingMutationFunctionError extends TransactionError {
   }
 }
 
+export class OnMutateMustBeSynchronousError extends TransactionError {
+  constructor() {
+    super(
+      `onMutate must be synchronous and cannot return a promise. Remove async/await or returned promises from onMutate.`
+    )
+    this.name = `OnMutateMustBeSynchronousError`
+  }
+}
+
 export class TransactionNotPendingMutateError extends TransactionError {
   constructor() {
     super(

package/src/optimistic-action.ts

@@ -1,4 +1,6 @@
 import { createTransaction } from "./transactions"
+import { OnMutateMustBeSynchronousError } from "./errors"
+import { isPromiseLike } from "./utils/type-guards"
 import type { CreateOptimisticActionsOptions, Transaction } from "./types"
 
 /**
@@ -67,8 +69,11 @@ export function createOptimisticAction<TVariables = unknown>(
     // Execute the transaction. The mutationFn is called once mutate()
     // is finished.
     transaction.mutate(() => {
-      // Call onMutate with variables to apply optimistic updates
-      onMutate(variables)
+      const maybePromise = onMutate(variables) as unknown
+
+      if (isPromiseLike(maybePromise)) {
+        throw new OnMutateMustBeSynchronousError()
+      }
     })
 
     return transaction

package/src/paced-mutations.ts

@@ -53,7 +53,7 @@ export interface PacedMutationsConfig<
  *     // Apply optimistic update immediately
  *     collection.update(id, draft => { draft.text = text })
  *   },
- *   mutationFn: async (text, { transaction }) => {
+ *   mutationFn: async ({ transaction }) => {
  *     await api.save(transaction.mutations)
  *   },
  *   strategy: debounceStrategy({ wait: 500 })
@@ -73,7 +73,7 @@ export interface PacedMutationsConfig<
  *   onMutate: ({ text }) => {
  *     collection.insert({ id: uuid(), text, completed: false })
  *   },
- *   mutationFn: async ({ text }, { transaction }) => {
+ *   mutationFn: async ({ transaction }) => {
  *     await api.save(transaction.mutations)
  *   },
  *   strategy: queueStrategy({

package/src/strategies/debounceStrategy.ts

@@ -14,7 +14,10 @@ import type { Transaction } from "../transactions"
  *
  * @example
  * ```ts
- * const mutate = useSerializedTransaction({
+ * const mutate = usePacedMutations({
+ *   onMutate: (value) => {
+ *     collection.update(id, draft => { draft.value = value })
+ *   },
  *   mutationFn: async ({ transaction }) => {
  *     await api.save(transaction.mutations)
  *   },

package/src/strategies/throttleStrategy.ts

@@ -16,7 +16,10 @@ import type { Transaction } from "../transactions"
  * @example
  * ```ts
  * // Throttle slider updates to every 200ms
- * const mutate = useSerializedTransaction({
+ * const mutate = usePacedMutations({
+ *   onMutate: (volume) => {
+ *     settingsCollection.update('volume', draft => { draft.value = volume })
+ *   },
  *   mutationFn: async ({ transaction }) => {
  *     await api.updateVolume(transaction.mutations)
  *   },
@@ -27,7 +30,10 @@ import type { Transaction } from "../transactions"
  * @example
  * ```ts
  * // Throttle with leading and trailing execution
- * const mutate = useSerializedTransaction({
+ * const mutate = usePacedMutations({
+ *   onMutate: (data) => {
+ *     collection.update(id, draft => { Object.assign(draft, data) })
+ *   },
  *   mutationFn: async ({ transaction }) => {
  *     await api.save(transaction.mutations)
  *   },

package/src/transactions.ts

@@ -1,4 +1,5 @@
 import { createDeferred } from "./deferred"
+import "./duplicate-instance-check"
 import {
   MissingMutationFunctionError,
   TransactionAlreadyCompletedRollbackError,
@@ -244,7 +245,9 @@ class Transaction<T extends object = Record<string, unknown>> {
 
   /**
    * Execute collection operations within this transaction
-   * @param callback - Function containing collection operations to group together
+   * @param callback - Function containing collection operations to group together. If the
+   * callback returns a Promise, the transaction context will remain active until the promise
+   * settles, allowing optimistic writes after `await` boundaries.
    * @returns This transaction for chaining
    * @example
    * // Group multiple operations
@@ -287,6 +290,7 @@ class Transaction<T extends object = Record<string, unknown>> {
     }
 
     registerTransaction(this)
+
     try {
       callback()
     } finally {

package/src/utils/type-guards.ts

@@ -0,0 +1,12 @@
+/**
+ * Type guard to check if a value is promise-like (has a `.then` method)
+ * @param value - The value to check
+ * @returns True if the value is promise-like, false otherwise
+ */
+export function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    !!value &&
+    (typeof value === `object` || typeof value === `function`) &&
+    typeof (value as { then?: unknown }).then === `function`
+  )
+}