@tanstack/db 0.4.16 → 0.4.17

package/dist/esm/errors.js

@@ -20,6 +20,34 @@ class SchemaValidationError extends TanStackDBError {
     this.issues = issues;
   }
 }
+class DuplicateDbInstanceError extends TanStackDBError {
+  constructor() {
+    super(
+      `Multiple instances of @tanstack/db detected!
+
+This causes transaction context to be lost because each instance maintains its own transaction stack.
+
+Common causes:
+1. Different versions of @tanstack/db installed
+2. Incompatible peer dependency versions in packages
+3. Module resolution issues in bundler configuration
+
+To fix:
+1. Check installed versions: npm list @tanstack/db (or pnpm/yarn list)
+2. Force a single version using package manager overrides:
+   - npm: "overrides" in package.json
+   - pnpm: "pnpm.overrides" in package.json
+   - yarn: "resolutions" in package.json
+3. Clear node_modules and lockfile, then reinstall
+
+To temporarily disable this check (not recommended):
+Set environment variable: TANSTACK_DB_DISABLE_DUP_CHECK=1
+
+See: https://tanstack.com/db/latest/docs/troubleshooting#duplicate-instances`
+    );
+    this.name = `DuplicateDbInstanceError`;
+  }
+}
 class CollectionConfigurationError extends TanStackDBError {
   constructor(message) {
     super(message);
@@ -177,6 +205,14 @@ class MissingMutationFunctionError extends TransactionError {
     super(`mutationFn is required when creating a transaction`);
   }
 }
+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`;
+  }
+}
 class TransactionNotPendingMutateError extends TransactionError {
   constructor() {
     super(
@@ -494,6 +530,7 @@ export {
   CollectionStateError,
   DeleteKeyNotFoundError,
   DistinctRequiresSelectError,
+  DuplicateDbInstanceError,
   DuplicateKeyError,
   DuplicateKeySyncError,
   EmptyReferencePathError,
@@ -529,6 +566,7 @@ export {
   NoPendingSyncTransactionWriteError,
   NonAggregateExpressionNotInGroupByError,
   NonRetriableError,
+  OnMutateMustBeSynchronousError,
   OnlyOneSourceAllowedError,
   QueryBuilderError,
   QueryCompilationError,

package/dist/esm/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sources":["../../src/errors.ts"],"sourcesContent":["// Root error class for all TanStack DB errors\nexport class TanStackDBError extends Error {\n  constructor(message: string) {\n    super(message)\n    this.name = `TanStackDBError`\n  }\n}\n\n// Base error classes\nexport class NonRetriableError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `NonRetriableError`\n  }\n}\n\n// Schema validation error (exported from index for backward compatibility)\nexport class SchemaValidationError extends TanStackDBError {\n  type: `insert` | `update`\n  issues: ReadonlyArray<{\n    message: string\n    path?: ReadonlyArray<string | number | symbol>\n  }>\n\n  constructor(\n    type: `insert` | `update`,\n    issues: ReadonlyArray<{\n      message: string\n      path?: ReadonlyArray<string | number | symbol>\n    }>,\n    message?: string\n  ) {\n    const defaultMessage = `${type === `insert` ? `Insert` : `Update`} validation failed: ${issues\n      .map((issue) => `\\n- ${issue.message} - path: ${issue.path}`)\n      .join(``)}`\n\n    super(message || defaultMessage)\n    this.name = `SchemaValidationError`\n    this.type = type\n    this.issues = issues\n  }\n}\n\n// Collection Configuration Errors\nexport class CollectionConfigurationError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `CollectionConfigurationError`\n  }\n}\n\nexport class CollectionRequiresConfigError extends CollectionConfigurationError {\n  constructor() {\n    super(`Collection requires a config`)\n  }\n}\n\nexport class CollectionRequiresSyncConfigError extends CollectionConfigurationError {\n  constructor() {\n    super(`Collection requires a sync config`)\n  }\n}\n\nexport class InvalidSchemaError extends CollectionConfigurationError {\n  constructor() {\n    super(`Schema must implement the standard-schema interface`)\n  }\n}\n\nexport class SchemaMustBeSynchronousError extends CollectionConfigurationError {\n  constructor() {\n    super(`Schema validation must be synchronous`)\n  }\n}\n\n// Collection State Errors\nexport class CollectionStateError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `CollectionStateError`\n  }\n}\n\nexport class CollectionInErrorStateError extends CollectionStateError {\n  constructor(operation: string, collectionId: string) {\n    super(\n      `Cannot perform ${operation} on collection \"${collectionId}\" - collection is in error state. Try calling cleanup() and restarting the collection.`\n    )\n  }\n}\n\nexport class InvalidCollectionStatusTransitionError extends CollectionStateError {\n  constructor(from: string, to: string, collectionId: string) {\n    super(\n      `Invalid collection status transition from \"${from}\" to \"${to}\" for collection \"${collectionId}\"`\n    )\n  }\n}\n\nexport class CollectionIsInErrorStateError extends CollectionStateError {\n  constructor() {\n    super(`Collection is in error state`)\n  }\n}\n\nexport class NegativeActiveSubscribersError extends CollectionStateError {\n  constructor() {\n    super(`Active subscribers count is negative - this should never happen`)\n  }\n}\n\n// Collection Operation Errors\nexport class CollectionOperationError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `CollectionOperationError`\n  }\n}\n\nexport class UndefinedKeyError extends CollectionOperationError {\n  constructor(item: any) {\n    super(\n      `An object was created without a defined key: ${JSON.stringify(item)}`\n    )\n  }\n}\n\nexport class DuplicateKeyError extends CollectionOperationError {\n  constructor(key: string | number) {\n    super(\n      `Cannot insert document with ID \"${key}\" because it already exists in the collection`\n    )\n  }\n}\n\nexport class DuplicateKeySyncError extends CollectionOperationError {\n  constructor(key: string | number, collectionId: string) {\n    super(\n      `Cannot insert document with key \"${key}\" from sync because it already exists in the collection \"${collectionId}\"`\n    )\n  }\n}\n\nexport class MissingUpdateArgumentError extends CollectionOperationError {\n  constructor() {\n    super(`The first argument to update is missing`)\n  }\n}\n\nexport class NoKeysPassedToUpdateError extends CollectionOperationError {\n  constructor() {\n    super(`No keys were passed to update`)\n  }\n}\n\nexport class UpdateKeyNotFoundError extends CollectionOperationError {\n  constructor(key: string | number) {\n    super(\n      `The key \"${key}\" was passed to update but an object for this key was not found in the collection`\n    )\n  }\n}\n\nexport class KeyUpdateNotAllowedError extends CollectionOperationError {\n  constructor(originalKey: string | number, newKey: string | number) {\n    super(\n      `Updating the key of an item is not allowed. Original key: \"${originalKey}\", Attempted new key: \"${newKey}\". Please delete the old item and create a new one if a key change is necessary.`\n    )\n  }\n}\n\nexport class NoKeysPassedToDeleteError extends CollectionOperationError {\n  constructor() {\n    super(`No keys were passed to delete`)\n  }\n}\n\nexport class DeleteKeyNotFoundError extends CollectionOperationError {\n  constructor(key: string | number) {\n    super(\n      `Collection.delete was called with key '${key}' but there is no item in the collection with this key`\n    )\n  }\n}\n\n// Collection Handler Errors\nexport class MissingHandlerError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `MissingHandlerError`\n  }\n}\n\nexport class MissingInsertHandlerError extends MissingHandlerError {\n  constructor() {\n    super(\n      `Collection.insert called directly (not within an explicit transaction) but no 'onInsert' handler is configured.`\n    )\n  }\n}\n\nexport class MissingUpdateHandlerError extends MissingHandlerError {\n  constructor() {\n    super(\n      `Collection.update called directly (not within an explicit transaction) but no 'onUpdate' handler is configured.`\n    )\n  }\n}\n\nexport class MissingDeleteHandlerError extends MissingHandlerError {\n  constructor() {\n    super(\n      `Collection.delete called directly (not within an explicit transaction) but no 'onDelete' handler is configured.`\n    )\n  }\n}\n\n// Transaction Errors\nexport class TransactionError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `TransactionError`\n  }\n}\n\nexport class MissingMutationFunctionError extends TransactionError {\n  constructor() {\n    super(`mutationFn is required when creating a transaction`)\n  }\n}\n\nexport class TransactionNotPendingMutateError extends TransactionError {\n  constructor() {\n    super(\n      `You can no longer call .mutate() as the transaction is no longer pending`\n    )\n  }\n}\n\nexport class TransactionAlreadyCompletedRollbackError extends TransactionError {\n  constructor() {\n    super(\n      `You can no longer call .rollback() as the transaction is already completed`\n    )\n  }\n}\n\nexport class TransactionNotPendingCommitError extends TransactionError {\n  constructor() {\n    super(\n      `You can no longer call .commit() as the transaction is no longer pending`\n    )\n  }\n}\n\nexport class NoPendingSyncTransactionWriteError extends TransactionError {\n  constructor() {\n    super(`No pending sync transaction to write to`)\n  }\n}\n\nexport class SyncTransactionAlreadyCommittedWriteError extends TransactionError {\n  constructor() {\n    super(\n      `The pending sync transaction is already committed, you can't still write to it.`\n    )\n  }\n}\n\nexport class NoPendingSyncTransactionCommitError extends TransactionError {\n  constructor() {\n    super(`No pending sync transaction to commit`)\n  }\n}\n\nexport class SyncTransactionAlreadyCommittedError extends TransactionError {\n  constructor() {\n    super(\n      `The pending sync transaction is already committed, you can't commit it again.`\n    )\n  }\n}\n\n// Query Builder Errors\nexport class QueryBuilderError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `QueryBuilderError`\n  }\n}\n\nexport class OnlyOneSourceAllowedError extends QueryBuilderError {\n  constructor(context: string) {\n    super(`Only one source is allowed in the ${context}`)\n  }\n}\n\nexport class SubQueryMustHaveFromClauseError extends QueryBuilderError {\n  constructor(context: string) {\n    super(`A sub query passed to a ${context} must have a from clause itself`)\n  }\n}\n\nexport class InvalidSourceError extends QueryBuilderError {\n  constructor(alias: string) {\n    super(\n      `Invalid source for live query: The value provided for alias \"${alias}\" is not a Collection or subquery. Live queries only accept Collection instances or subqueries. Please ensure you're passing a valid Collection or QueryBuilder, not a plain array or other data type.`\n    )\n  }\n}\n\nexport class JoinConditionMustBeEqualityError extends QueryBuilderError {\n  constructor() {\n    super(`Join condition must be an equality expression`)\n  }\n}\n\nexport class QueryMustHaveFromClauseError extends QueryBuilderError {\n  constructor() {\n    super(`Query must have a from clause`)\n  }\n}\n\n// Query Compilation Errors\nexport class QueryCompilationError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `QueryCompilationError`\n  }\n}\n\nexport class DistinctRequiresSelectError extends QueryCompilationError {\n  constructor() {\n    super(`DISTINCT requires a SELECT clause.`)\n  }\n}\n\nexport class HavingRequiresGroupByError extends QueryCompilationError {\n  constructor() {\n    super(`HAVING clause requires GROUP BY clause`)\n  }\n}\n\nexport class LimitOffsetRequireOrderByError extends QueryCompilationError {\n  constructor() {\n    super(\n      `LIMIT and OFFSET require an ORDER BY clause to ensure deterministic results`\n    )\n  }\n}\n\n/**\n * Error thrown when a collection input stream is not found during query compilation.\n * In self-joins, each alias (e.g., 'employee', 'manager') requires its own input stream.\n */\nexport class CollectionInputNotFoundError extends QueryCompilationError {\n  constructor(\n    alias: string,\n    collectionId?: string,\n    availableKeys?: Array<string>\n  ) {\n    const details = collectionId\n      ? `alias \"${alias}\" (collection \"${collectionId}\")`\n      : `collection \"${alias}\"`\n    const availableKeysMsg = availableKeys?.length\n      ? `. Available keys: ${availableKeys.join(`, `)}`\n      : ``\n    super(`Input for ${details} not found in inputs map${availableKeysMsg}`)\n  }\n}\n\nexport class UnsupportedFromTypeError extends QueryCompilationError {\n  constructor(type: string) {\n    super(`Unsupported FROM type: ${type}`)\n  }\n}\n\nexport class UnknownExpressionTypeError extends QueryCompilationError {\n  constructor(type: string) {\n    super(`Unknown expression type: ${type}`)\n  }\n}\n\nexport class EmptyReferencePathError extends QueryCompilationError {\n  constructor() {\n    super(`Reference path cannot be empty`)\n  }\n}\n\nexport class UnknownFunctionError extends QueryCompilationError {\n  constructor(functionName: string) {\n    super(`Unknown function: ${functionName}`)\n  }\n}\n\nexport class JoinCollectionNotFoundError extends QueryCompilationError {\n  constructor(collectionId: string) {\n    super(`Collection \"${collectionId}\" not found during compilation of join`)\n  }\n}\n\n// JOIN Operation Errors\nexport class JoinError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `JoinError`\n  }\n}\n\nexport class UnsupportedJoinTypeError extends JoinError {\n  constructor(joinType: string) {\n    super(`Unsupported join type: ${joinType}`)\n  }\n}\n\nexport class InvalidJoinConditionSameSourceError extends JoinError {\n  constructor(sourceAlias: string) {\n    super(\n      `Invalid join condition: both expressions refer to the same source \"${sourceAlias}\"`\n    )\n  }\n}\n\nexport class InvalidJoinConditionSourceMismatchError extends JoinError {\n  constructor() {\n    super(`Invalid join condition: expressions must reference source aliases`)\n  }\n}\n\nexport class InvalidJoinConditionLeftSourceError extends JoinError {\n  constructor(sourceAlias: string) {\n    super(\n      `Invalid join condition: left expression refers to an unavailable source \"${sourceAlias}\"`\n    )\n  }\n}\n\nexport class InvalidJoinConditionRightSourceError extends JoinError {\n  constructor(sourceAlias: string) {\n    super(\n      `Invalid join condition: right expression does not refer to the joined source \"${sourceAlias}\"`\n    )\n  }\n}\n\nexport class InvalidJoinCondition extends JoinError {\n  constructor() {\n    super(`Invalid join condition`)\n  }\n}\n\nexport class UnsupportedJoinSourceTypeError extends JoinError {\n  constructor(type: string) {\n    super(`Unsupported join source type: ${type}`)\n  }\n}\n\n// GROUP BY and Aggregation Errors\nexport class GroupByError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `GroupByError`\n  }\n}\n\nexport class NonAggregateExpressionNotInGroupByError extends GroupByError {\n  constructor(alias: string) {\n    super(\n      `Non-aggregate expression '${alias}' in SELECT must also appear in GROUP BY clause`\n    )\n  }\n}\n\nexport class UnsupportedAggregateFunctionError extends GroupByError {\n  constructor(functionName: string) {\n    super(`Unsupported aggregate function: ${functionName}`)\n  }\n}\n\nexport class AggregateFunctionNotInSelectError extends GroupByError {\n  constructor(functionName: string) {\n    super(\n      `Aggregate function in HAVING clause must also be in SELECT clause: ${functionName}`\n    )\n  }\n}\n\nexport class UnknownHavingExpressionTypeError extends GroupByError {\n  constructor(type: string) {\n    super(`Unknown expression type in HAVING clause: ${type}`)\n  }\n}\n\n// Storage Errors\nexport class StorageError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `StorageError`\n  }\n}\n\nexport class SerializationError extends StorageError {\n  constructor(operation: string, originalError: string) {\n    super(\n      `Cannot ${operation} item because it cannot be JSON serialized: ${originalError}`\n    )\n  }\n}\n\n// LocalStorage Collection Errors\nexport class LocalStorageCollectionError extends StorageError {\n  constructor(message: string) {\n    super(message)\n    this.name = `LocalStorageCollectionError`\n  }\n}\n\nexport class StorageKeyRequiredError extends LocalStorageCollectionError {\n  constructor() {\n    super(`[LocalStorageCollection] storageKey must be provided.`)\n  }\n}\n\nexport class InvalidStorageDataFormatError extends LocalStorageCollectionError {\n  constructor(storageKey: string, key: string) {\n    super(\n      `[LocalStorageCollection] Invalid data format in storage key \"${storageKey}\" for key \"${key}\".`\n    )\n  }\n}\n\nexport class InvalidStorageObjectFormatError extends LocalStorageCollectionError {\n  constructor(storageKey: string) {\n    super(\n      `[LocalStorageCollection] Invalid data format in storage key \"${storageKey}\". Expected object format.`\n    )\n  }\n}\n\n// Sync Cleanup Errors\nexport class SyncCleanupError extends TanStackDBError {\n  constructor(collectionId: string, error: Error | string) {\n    const message = error instanceof Error ? error.message : String(error)\n    super(\n      `Collection \"${collectionId}\" sync cleanup function threw an error: ${message}`\n    )\n    this.name = `SyncCleanupError`\n  }\n}\n\n// Query Optimizer Errors\nexport class QueryOptimizerError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `QueryOptimizerError`\n  }\n}\n\nexport class CannotCombineEmptyExpressionListError extends QueryOptimizerError {\n  constructor() {\n    super(`Cannot combine empty expression list`)\n  }\n}\n\n/**\n * Internal error when the query optimizer fails to convert a WHERE clause to a collection filter.\n */\nexport class WhereClauseConversionError extends QueryOptimizerError {\n  constructor(collectionId: string, alias: string) {\n    super(\n      `Failed to convert WHERE clause to collection filter for collection '${collectionId}' alias '${alias}'. This indicates a bug in the query optimization logic.`\n    )\n  }\n}\n\n/**\n * Error when a subscription cannot be found during lazy join processing.\n * For subqueries, aliases may be remapped (e.g., 'activeUser' → 'user').\n */\nexport class SubscriptionNotFoundError extends QueryCompilationError {\n  constructor(\n    resolvedAlias: string,\n    originalAlias: string,\n    collectionId: string,\n    availableAliases: Array<string>\n  ) {\n    super(\n      `Internal error: subscription for alias '${resolvedAlias}' (remapped from '${originalAlias}', collection '${collectionId}') is missing in join pipeline. Available aliases: ${availableAliases.join(`, `)}. This indicates a bug in alias tracking.`\n    )\n  }\n}\n\n/**\n * Error thrown when aggregate expressions are used outside of a GROUP BY context.\n */\nexport class AggregateNotSupportedError extends QueryCompilationError {\n  constructor() {\n    super(\n      `Aggregate expressions are not supported in this context. Use GROUP BY clause for aggregates.`\n    )\n  }\n}\n\n/**\n * Internal error when the compiler returns aliases that don't have corresponding input streams.\n * This should never happen since all aliases come from user declarations.\n */\nexport class MissingAliasInputsError extends QueryCompilationError {\n  constructor(missingAliases: Array<string>) {\n    super(\n      `Internal error: compiler returned aliases without inputs: ${missingAliases.join(`, `)}. ` +\n        `This indicates a bug in query compilation. Please report this issue.`\n    )\n  }\n}\n\n/**\n * Error thrown when setWindow is called on a collection without an ORDER BY clause.\n */\nexport class SetWindowRequiresOrderByError extends QueryCompilationError {\n  constructor() {\n    super(\n      `setWindow() can only be called on collections with an ORDER BY clause. ` +\n        `Add .orderBy() to your query to enable window movement.`\n    )\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sources":["../../src/errors.ts"],"sourcesContent":["// Root error class for all TanStack DB errors\nexport class TanStackDBError extends Error {\n  constructor(message: string) {\n    super(message)\n    this.name = `TanStackDBError`\n  }\n}\n\n// Base error classes\nexport class NonRetriableError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `NonRetriableError`\n  }\n}\n\n// Schema validation error (exported from index for backward compatibility)\nexport class SchemaValidationError extends TanStackDBError {\n  type: `insert` | `update`\n  issues: ReadonlyArray<{\n    message: string\n    path?: ReadonlyArray<string | number | symbol>\n  }>\n\n  constructor(\n    type: `insert` | `update`,\n    issues: ReadonlyArray<{\n      message: string\n      path?: ReadonlyArray<string | number | symbol>\n    }>,\n    message?: string\n  ) {\n    const defaultMessage = `${type === `insert` ? `Insert` : `Update`} validation failed: ${issues\n      .map((issue) => `\\n- ${issue.message} - path: ${issue.path}`)\n      .join(``)}`\n\n    super(message || defaultMessage)\n    this.name = `SchemaValidationError`\n    this.type = type\n    this.issues = issues\n  }\n}\n\n// Module Instance Errors\nexport class DuplicateDbInstanceError extends TanStackDBError {\n  constructor() {\n    super(\n      `Multiple instances of @tanstack/db detected!\\n\\n` +\n        `This causes transaction context to be lost because each instance maintains ` +\n        `its own transaction stack.\\n\\n` +\n        `Common causes:\\n` +\n        `1. Different versions of @tanstack/db installed\\n` +\n        `2. Incompatible peer dependency versions in packages\\n` +\n        `3. Module resolution issues in bundler configuration\\n\\n` +\n        `To fix:\\n` +\n        `1. Check installed versions: npm list @tanstack/db (or pnpm/yarn list)\\n` +\n        `2. Force a single version using package manager overrides:\\n` +\n        `   - npm: \"overrides\" in package.json\\n` +\n        `   - pnpm: \"pnpm.overrides\" in package.json\\n` +\n        `   - yarn: \"resolutions\" in package.json\\n` +\n        `3. Clear node_modules and lockfile, then reinstall\\n\\n` +\n        `To temporarily disable this check (not recommended):\\n` +\n        `Set environment variable: TANSTACK_DB_DISABLE_DUP_CHECK=1\\n\\n` +\n        `See: https://tanstack.com/db/latest/docs/troubleshooting#duplicate-instances`\n    )\n    this.name = `DuplicateDbInstanceError`\n  }\n}\n\n// Collection Configuration Errors\nexport class CollectionConfigurationError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `CollectionConfigurationError`\n  }\n}\n\nexport class CollectionRequiresConfigError extends CollectionConfigurationError {\n  constructor() {\n    super(`Collection requires a config`)\n  }\n}\n\nexport class CollectionRequiresSyncConfigError extends CollectionConfigurationError {\n  constructor() {\n    super(`Collection requires a sync config`)\n  }\n}\n\nexport class InvalidSchemaError extends CollectionConfigurationError {\n  constructor() {\n    super(`Schema must implement the standard-schema interface`)\n  }\n}\n\nexport class SchemaMustBeSynchronousError extends CollectionConfigurationError {\n  constructor() {\n    super(`Schema validation must be synchronous`)\n  }\n}\n\n// Collection State Errors\nexport class CollectionStateError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `CollectionStateError`\n  }\n}\n\nexport class CollectionInErrorStateError extends CollectionStateError {\n  constructor(operation: string, collectionId: string) {\n    super(\n      `Cannot perform ${operation} on collection \"${collectionId}\" - collection is in error state. Try calling cleanup() and restarting the collection.`\n    )\n  }\n}\n\nexport class InvalidCollectionStatusTransitionError extends CollectionStateError {\n  constructor(from: string, to: string, collectionId: string) {\n    super(\n      `Invalid collection status transition from \"${from}\" to \"${to}\" for collection \"${collectionId}\"`\n    )\n  }\n}\n\nexport class CollectionIsInErrorStateError extends CollectionStateError {\n  constructor() {\n    super(`Collection is in error state`)\n  }\n}\n\nexport class NegativeActiveSubscribersError extends CollectionStateError {\n  constructor() {\n    super(`Active subscribers count is negative - this should never happen`)\n  }\n}\n\n// Collection Operation Errors\nexport class CollectionOperationError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `CollectionOperationError`\n  }\n}\n\nexport class UndefinedKeyError extends CollectionOperationError {\n  constructor(item: any) {\n    super(\n      `An object was created without a defined key: ${JSON.stringify(item)}`\n    )\n  }\n}\n\nexport class DuplicateKeyError extends CollectionOperationError {\n  constructor(key: string | number) {\n    super(\n      `Cannot insert document with ID \"${key}\" because it already exists in the collection`\n    )\n  }\n}\n\nexport class DuplicateKeySyncError extends CollectionOperationError {\n  constructor(key: string | number, collectionId: string) {\n    super(\n      `Cannot insert document with key \"${key}\" from sync because it already exists in the collection \"${collectionId}\"`\n    )\n  }\n}\n\nexport class MissingUpdateArgumentError extends CollectionOperationError {\n  constructor() {\n    super(`The first argument to update is missing`)\n  }\n}\n\nexport class NoKeysPassedToUpdateError extends CollectionOperationError {\n  constructor() {\n    super(`No keys were passed to update`)\n  }\n}\n\nexport class UpdateKeyNotFoundError extends CollectionOperationError {\n  constructor(key: string | number) {\n    super(\n      `The key \"${key}\" was passed to update but an object for this key was not found in the collection`\n    )\n  }\n}\n\nexport class KeyUpdateNotAllowedError extends CollectionOperationError {\n  constructor(originalKey: string | number, newKey: string | number) {\n    super(\n      `Updating the key of an item is not allowed. Original key: \"${originalKey}\", Attempted new key: \"${newKey}\". Please delete the old item and create a new one if a key change is necessary.`\n    )\n  }\n}\n\nexport class NoKeysPassedToDeleteError extends CollectionOperationError {\n  constructor() {\n    super(`No keys were passed to delete`)\n  }\n}\n\nexport class DeleteKeyNotFoundError extends CollectionOperationError {\n  constructor(key: string | number) {\n    super(\n      `Collection.delete was called with key '${key}' but there is no item in the collection with this key`\n    )\n  }\n}\n\n// Collection Handler Errors\nexport class MissingHandlerError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `MissingHandlerError`\n  }\n}\n\nexport class MissingInsertHandlerError extends MissingHandlerError {\n  constructor() {\n    super(\n      `Collection.insert called directly (not within an explicit transaction) but no 'onInsert' handler is configured.`\n    )\n  }\n}\n\nexport class MissingUpdateHandlerError extends MissingHandlerError {\n  constructor() {\n    super(\n      `Collection.update called directly (not within an explicit transaction) but no 'onUpdate' handler is configured.`\n    )\n  }\n}\n\nexport class MissingDeleteHandlerError extends MissingHandlerError {\n  constructor() {\n    super(\n      `Collection.delete called directly (not within an explicit transaction) but no 'onDelete' handler is configured.`\n    )\n  }\n}\n\n// Transaction Errors\nexport class TransactionError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `TransactionError`\n  }\n}\n\nexport class MissingMutationFunctionError extends TransactionError {\n  constructor() {\n    super(`mutationFn is required when creating a transaction`)\n  }\n}\n\nexport class OnMutateMustBeSynchronousError extends TransactionError {\n  constructor() {\n    super(\n      `onMutate must be synchronous and cannot return a promise. Remove async/await or returned promises from onMutate.`\n    )\n    this.name = `OnMutateMustBeSynchronousError`\n  }\n}\n\nexport class TransactionNotPendingMutateError extends TransactionError {\n  constructor() {\n    super(\n      `You can no longer call .mutate() as the transaction is no longer pending`\n    )\n  }\n}\n\nexport class TransactionAlreadyCompletedRollbackError extends TransactionError {\n  constructor() {\n    super(\n      `You can no longer call .rollback() as the transaction is already completed`\n    )\n  }\n}\n\nexport class TransactionNotPendingCommitError extends TransactionError {\n  constructor() {\n    super(\n      `You can no longer call .commit() as the transaction is no longer pending`\n    )\n  }\n}\n\nexport class NoPendingSyncTransactionWriteError extends TransactionError {\n  constructor() {\n    super(`No pending sync transaction to write to`)\n  }\n}\n\nexport class SyncTransactionAlreadyCommittedWriteError extends TransactionError {\n  constructor() {\n    super(\n      `The pending sync transaction is already committed, you can't still write to it.`\n    )\n  }\n}\n\nexport class NoPendingSyncTransactionCommitError extends TransactionError {\n  constructor() {\n    super(`No pending sync transaction to commit`)\n  }\n}\n\nexport class SyncTransactionAlreadyCommittedError extends TransactionError {\n  constructor() {\n    super(\n      `The pending sync transaction is already committed, you can't commit it again.`\n    )\n  }\n}\n\n// Query Builder Errors\nexport class QueryBuilderError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `QueryBuilderError`\n  }\n}\n\nexport class OnlyOneSourceAllowedError extends QueryBuilderError {\n  constructor(context: string) {\n    super(`Only one source is allowed in the ${context}`)\n  }\n}\n\nexport class SubQueryMustHaveFromClauseError extends QueryBuilderError {\n  constructor(context: string) {\n    super(`A sub query passed to a ${context} must have a from clause itself`)\n  }\n}\n\nexport class InvalidSourceError extends QueryBuilderError {\n  constructor(alias: string) {\n    super(\n      `Invalid source for live query: The value provided for alias \"${alias}\" is not a Collection or subquery. Live queries only accept Collection instances or subqueries. Please ensure you're passing a valid Collection or QueryBuilder, not a plain array or other data type.`\n    )\n  }\n}\n\nexport class JoinConditionMustBeEqualityError extends QueryBuilderError {\n  constructor() {\n    super(`Join condition must be an equality expression`)\n  }\n}\n\nexport class QueryMustHaveFromClauseError extends QueryBuilderError {\n  constructor() {\n    super(`Query must have a from clause`)\n  }\n}\n\n// Query Compilation Errors\nexport class QueryCompilationError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `QueryCompilationError`\n  }\n}\n\nexport class DistinctRequiresSelectError extends QueryCompilationError {\n  constructor() {\n    super(`DISTINCT requires a SELECT clause.`)\n  }\n}\n\nexport class HavingRequiresGroupByError extends QueryCompilationError {\n  constructor() {\n    super(`HAVING clause requires GROUP BY clause`)\n  }\n}\n\nexport class LimitOffsetRequireOrderByError extends QueryCompilationError {\n  constructor() {\n    super(\n      `LIMIT and OFFSET require an ORDER BY clause to ensure deterministic results`\n    )\n  }\n}\n\n/**\n * Error thrown when a collection input stream is not found during query compilation.\n * In self-joins, each alias (e.g., 'employee', 'manager') requires its own input stream.\n */\nexport class CollectionInputNotFoundError extends QueryCompilationError {\n  constructor(\n    alias: string,\n    collectionId?: string,\n    availableKeys?: Array<string>\n  ) {\n    const details = collectionId\n      ? `alias \"${alias}\" (collection \"${collectionId}\")`\n      : `collection \"${alias}\"`\n    const availableKeysMsg = availableKeys?.length\n      ? `. Available keys: ${availableKeys.join(`, `)}`\n      : ``\n    super(`Input for ${details} not found in inputs map${availableKeysMsg}`)\n  }\n}\n\nexport class UnsupportedFromTypeError extends QueryCompilationError {\n  constructor(type: string) {\n    super(`Unsupported FROM type: ${type}`)\n  }\n}\n\nexport class UnknownExpressionTypeError extends QueryCompilationError {\n  constructor(type: string) {\n    super(`Unknown expression type: ${type}`)\n  }\n}\n\nexport class EmptyReferencePathError extends QueryCompilationError {\n  constructor() {\n    super(`Reference path cannot be empty`)\n  }\n}\n\nexport class UnknownFunctionError extends QueryCompilationError {\n  constructor(functionName: string) {\n    super(`Unknown function: ${functionName}`)\n  }\n}\n\nexport class JoinCollectionNotFoundError extends QueryCompilationError {\n  constructor(collectionId: string) {\n    super(`Collection \"${collectionId}\" not found during compilation of join`)\n  }\n}\n\n// JOIN Operation Errors\nexport class JoinError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `JoinError`\n  }\n}\n\nexport class UnsupportedJoinTypeError extends JoinError {\n  constructor(joinType: string) {\n    super(`Unsupported join type: ${joinType}`)\n  }\n}\n\nexport class InvalidJoinConditionSameSourceError extends JoinError {\n  constructor(sourceAlias: string) {\n    super(\n      `Invalid join condition: both expressions refer to the same source \"${sourceAlias}\"`\n    )\n  }\n}\n\nexport class InvalidJoinConditionSourceMismatchError extends JoinError {\n  constructor() {\n    super(`Invalid join condition: expressions must reference source aliases`)\n  }\n}\n\nexport class InvalidJoinConditionLeftSourceError extends JoinError {\n  constructor(sourceAlias: string) {\n    super(\n      `Invalid join condition: left expression refers to an unavailable source \"${sourceAlias}\"`\n    )\n  }\n}\n\nexport class InvalidJoinConditionRightSourceError extends JoinError {\n  constructor(sourceAlias: string) {\n    super(\n      `Invalid join condition: right expression does not refer to the joined source \"${sourceAlias}\"`\n    )\n  }\n}\n\nexport class InvalidJoinCondition extends JoinError {\n  constructor() {\n    super(`Invalid join condition`)\n  }\n}\n\nexport class UnsupportedJoinSourceTypeError extends JoinError {\n  constructor(type: string) {\n    super(`Unsupported join source type: ${type}`)\n  }\n}\n\n// GROUP BY and Aggregation Errors\nexport class GroupByError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `GroupByError`\n  }\n}\n\nexport class NonAggregateExpressionNotInGroupByError extends GroupByError {\n  constructor(alias: string) {\n    super(\n      `Non-aggregate expression '${alias}' in SELECT must also appear in GROUP BY clause`\n    )\n  }\n}\n\nexport class UnsupportedAggregateFunctionError extends GroupByError {\n  constructor(functionName: string) {\n    super(`Unsupported aggregate function: ${functionName}`)\n  }\n}\n\nexport class AggregateFunctionNotInSelectError extends GroupByError {\n  constructor(functionName: string) {\n    super(\n      `Aggregate function in HAVING clause must also be in SELECT clause: ${functionName}`\n    )\n  }\n}\n\nexport class UnknownHavingExpressionTypeError extends GroupByError {\n  constructor(type: string) {\n    super(`Unknown expression type in HAVING clause: ${type}`)\n  }\n}\n\n// Storage Errors\nexport class StorageError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `StorageError`\n  }\n}\n\nexport class SerializationError extends StorageError {\n  constructor(operation: string, originalError: string) {\n    super(\n      `Cannot ${operation} item because it cannot be JSON serialized: ${originalError}`\n    )\n  }\n}\n\n// LocalStorage Collection Errors\nexport class LocalStorageCollectionError extends StorageError {\n  constructor(message: string) {\n    super(message)\n    this.name = `LocalStorageCollectionError`\n  }\n}\n\nexport class StorageKeyRequiredError extends LocalStorageCollectionError {\n  constructor() {\n    super(`[LocalStorageCollection] storageKey must be provided.`)\n  }\n}\n\nexport class InvalidStorageDataFormatError extends LocalStorageCollectionError {\n  constructor(storageKey: string, key: string) {\n    super(\n      `[LocalStorageCollection] Invalid data format in storage key \"${storageKey}\" for key \"${key}\".`\n    )\n  }\n}\n\nexport class InvalidStorageObjectFormatError extends LocalStorageCollectionError {\n  constructor(storageKey: string) {\n    super(\n      `[LocalStorageCollection] Invalid data format in storage key \"${storageKey}\". Expected object format.`\n    )\n  }\n}\n\n// Sync Cleanup Errors\nexport class SyncCleanupError extends TanStackDBError {\n  constructor(collectionId: string, error: Error | string) {\n    const message = error instanceof Error ? error.message : String(error)\n    super(\n      `Collection \"${collectionId}\" sync cleanup function threw an error: ${message}`\n    )\n    this.name = `SyncCleanupError`\n  }\n}\n\n// Query Optimizer Errors\nexport class QueryOptimizerError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `QueryOptimizerError`\n  }\n}\n\nexport class CannotCombineEmptyExpressionListError extends QueryOptimizerError {\n  constructor() {\n    super(`Cannot combine empty expression list`)\n  }\n}\n\n/**\n * Internal error when the query optimizer fails to convert a WHERE clause to a collection filter.\n */\nexport class WhereClauseConversionError extends QueryOptimizerError {\n  constructor(collectionId: string, alias: string) {\n    super(\n      `Failed to convert WHERE clause to collection filter for collection '${collectionId}' alias '${alias}'. This indicates a bug in the query optimization logic.`\n    )\n  }\n}\n\n/**\n * Error when a subscription cannot be found during lazy join processing.\n * For subqueries, aliases may be remapped (e.g., 'activeUser' → 'user').\n */\nexport class SubscriptionNotFoundError extends QueryCompilationError {\n  constructor(\n    resolvedAlias: string,\n    originalAlias: string,\n    collectionId: string,\n    availableAliases: Array<string>\n  ) {\n    super(\n      `Internal error: subscription for alias '${resolvedAlias}' (remapped from '${originalAlias}', collection '${collectionId}') is missing in join pipeline. Available aliases: ${availableAliases.join(`, `)}. This indicates a bug in alias tracking.`\n    )\n  }\n}\n\n/**\n * Error thrown when aggregate expressions are used outside of a GROUP BY context.\n */\nexport class AggregateNotSupportedError extends QueryCompilationError {\n  constructor() {\n    super(\n      `Aggregate expressions are not supported in this context. Use GROUP BY clause for aggregates.`\n    )\n  }\n}\n\n/**\n * Internal error when the compiler returns aliases that don't have corresponding input streams.\n * This should never happen since all aliases come from user declarations.\n */\nexport class MissingAliasInputsError extends QueryCompilationError {\n  constructor(missingAliases: Array<string>) {\n    super(\n      `Internal error: compiler returned aliases without inputs: ${missingAliases.join(`, `)}. ` +\n        `This indicates a bug in query compilation. Please report this issue.`\n    )\n  }\n}\n\n/**\n * Error thrown when setWindow is called on a collection without an ORDER BY clause.\n */\nexport class SetWindowRequiresOrderByError extends QueryCompilationError {\n  constructor() {\n    super(\n      `setWindow() can only be called on collections with an ORDER BY clause. ` +\n        `Add .orderBy() to your query to enable window movement.`\n    )\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/index.js

@@ -6,7 +6,7 @@ import { createArrayChangeProxy, createChangeProxy, withArrayChangeTracking, wit
 import { createOptimisticAction } from "./optimistic-action.js";
 import { localOnlyCollectionOptions } from "./local-only.js";
 import { localStorageCollectionOptions } from "./local-storage.js";
-import { AggregateFunctionNotInSelectError, AggregateNotSupportedError, CannotCombineEmptyExpressionListError, CollectionConfigurationError, CollectionInErrorStateError, CollectionInputNotFoundError, CollectionIsInErrorStateError, CollectionOperationError, CollectionRequiresConfigError, CollectionRequiresSyncConfigError, CollectionStateError, DeleteKeyNotFoundError, DistinctRequiresSelectError, DuplicateKeyError, DuplicateKeySyncError, EmptyReferencePathError, GroupByError, HavingRequiresGroupByError, InvalidCollectionStatusTransitionError, InvalidJoinCondition, InvalidJoinConditionLeftSourceError, InvalidJoinConditionRightSourceError, InvalidJoinConditionSameSourceError, InvalidJoinConditionSourceMismatchError, InvalidSchemaError, InvalidSourceError, InvalidStorageDataFormatError, InvalidStorageObjectFormatError, JoinCollectionNotFoundError, JoinConditionMustBeEqualityError, JoinError, KeyUpdateNotAllowedError, LimitOffsetRequireOrderByError, LocalStorageCollectionError, MissingAliasInputsError, MissingDeleteHandlerError, MissingHandlerError, MissingInsertHandlerError, MissingMutationFunctionError, MissingUpdateArgumentError, MissingUpdateHandlerError, NegativeActiveSubscribersError, NoKeysPassedToDeleteError, NoKeysPassedToUpdateError, NoPendingSyncTransactionCommitError, NoPendingSyncTransactionWriteError, NonAggregateExpressionNotInGroupByError, NonRetriableError, OnlyOneSourceAllowedError, QueryBuilderError, QueryCompilationError, QueryMustHaveFromClauseError, QueryOptimizerError, SchemaMustBeSynchronousError, SchemaValidationError, SerializationError, SetWindowRequiresOrderByError, StorageError, StorageKeyRequiredError, SubQueryMustHaveFromClauseError, SubscriptionNotFoundError, SyncCleanupError, SyncTransactionAlreadyCommittedError, SyncTransactionAlreadyCommittedWriteError, TanStackDBError, TransactionAlreadyCompletedRollbackError, TransactionError, TransactionNotPendingCommitError, TransactionNotPendingMutateError, UndefinedKeyError, UnknownExpressionTypeError, UnknownFunctionError, UnknownHavingExpressionTypeError, UnsupportedAggregateFunctionError, UnsupportedFromTypeError, UnsupportedJoinSourceTypeError, UnsupportedJoinTypeError, UpdateKeyNotFoundError, WhereClauseConversionError } from "./errors.js";
+import { AggregateFunctionNotInSelectError, AggregateNotSupportedError, CannotCombineEmptyExpressionListError, CollectionConfigurationError, CollectionInErrorStateError, CollectionInputNotFoundError, CollectionIsInErrorStateError, CollectionOperationError, CollectionRequiresConfigError, CollectionRequiresSyncConfigError, CollectionStateError, DeleteKeyNotFoundError, DistinctRequiresSelectError, DuplicateDbInstanceError, DuplicateKeyError, DuplicateKeySyncError, EmptyReferencePathError, GroupByError, HavingRequiresGroupByError, InvalidCollectionStatusTransitionError, InvalidJoinCondition, InvalidJoinConditionLeftSourceError, InvalidJoinConditionRightSourceError, InvalidJoinConditionSameSourceError, InvalidJoinConditionSourceMismatchError, InvalidSchemaError, InvalidSourceError, InvalidStorageDataFormatError, InvalidStorageObjectFormatError, JoinCollectionNotFoundError, JoinConditionMustBeEqualityError, JoinError, KeyUpdateNotAllowedError, LimitOffsetRequireOrderByError, LocalStorageCollectionError, MissingAliasInputsError, MissingDeleteHandlerError, MissingHandlerError, MissingInsertHandlerError, MissingMutationFunctionError, MissingUpdateArgumentError, MissingUpdateHandlerError, NegativeActiveSubscribersError, NoKeysPassedToDeleteError, NoKeysPassedToUpdateError, NoPendingSyncTransactionCommitError, NoPendingSyncTransactionWriteError, NonAggregateExpressionNotInGroupByError, NonRetriableError, OnMutateMustBeSynchronousError, OnlyOneSourceAllowedError, QueryBuilderError, QueryCompilationError, QueryMustHaveFromClauseError, QueryOptimizerError, SchemaMustBeSynchronousError, SchemaValidationError, SerializationError, SetWindowRequiresOrderByError, StorageError, StorageKeyRequiredError, SubQueryMustHaveFromClauseError, SubscriptionNotFoundError, SyncCleanupError, SyncTransactionAlreadyCommittedError, SyncTransactionAlreadyCommittedWriteError, TanStackDBError, TransactionAlreadyCompletedRollbackError, TransactionError, TransactionNotPendingCommitError, TransactionNotPendingMutateError, UndefinedKeyError, UnknownExpressionTypeError, UnknownFunctionError, UnknownHavingExpressionTypeError, UnsupportedAggregateFunctionError, UnsupportedFromTypeError, UnsupportedJoinSourceTypeError, UnsupportedJoinTypeError, UpdateKeyNotFoundError, WhereClauseConversionError } from "./errors.js";
 import { createPacedMutations } from "./paced-mutations.js";
 import { BaseIndex, IndexOperation } from "./indexes/base-index.js";
 import { BTreeIndex } from "./indexes/btree-index.js";
@@ -36,6 +36,7 @@ export {
   CollectionStateError,
   DeleteKeyNotFoundError,
   DistinctRequiresSelectError,
+  DuplicateDbInstanceError,
   DuplicateKeyError,
   DuplicateKeySyncError,
   EmptyReferencePathError,
@@ -75,6 +76,7 @@ export {
   NoPendingSyncTransactionWriteError,
   NonAggregateExpressionNotInGroupByError,
   NonRetriableError,
+  OnMutateMustBeSynchronousError,
   OnlyOneSourceAllowedError,
   Query,
   QueryBuilderError,

package/dist/esm/optimistic-action.js

@@ -1,4 +1,6 @@
 import { createTransaction } from "./transactions.js";
+import { OnMutateMustBeSynchronousError } from "./errors.js";
+import { isPromiseLike } from "./utils/type-guards.js";
 function createOptimisticAction(options) {
   const { mutationFn, onMutate, ...config } = options;
   return (variables) => {
@@ -10,7 +12,10 @@ function createOptimisticAction(options) {
       }
     });
     transaction.mutate(() => {
-      onMutate(variables);
+      const maybePromise = onMutate(variables);
+      if (isPromiseLike(maybePromise)) {
+        throw new OnMutateMustBeSynchronousError();
+      }
     });
     return transaction;
   };

package/dist/esm/optimistic-action.js.map

@@ -1 +1 @@
-{"version":3,"file":"optimistic-action.js","sources":["../../src/optimistic-action.ts"],"sourcesContent":["import { createTransaction } from \"./transactions\"\nimport type { CreateOptimisticActionsOptions, Transaction } from \"./types\"\n\n/**\n * Creates an optimistic action function that applies local optimistic updates immediately\n * before executing the actual mutation on the server.\n *\n * This pattern allows for responsive UI updates while the actual mutation is in progress.\n * The optimistic update is applied via the `onMutate` callback, and the server mutation\n * is executed via the `mutationFn`.\n *\n * **Important:** Inside your `mutationFn`, you must ensure that your server writes have synced back\n * before you return, as the optimistic state is dropped when you return from the mutation function.\n * You generally use collection-specific helpers to do this, such as Query's `utils.refetch()`,\n * direct write APIs, or Electric's `utils.awaitTxId()`.\n *\n * @example\n * ```ts\n * const addTodo = createOptimisticAction<string>({\n *   onMutate: (text) => {\n *     // Instantly applies local optimistic state\n *     todoCollection.insert({\n *       id: uuid(),\n *       text,\n *       completed: false\n *     })\n *   },\n *   mutationFn: async (text, params) => {\n *     // Persist the todo to your backend\n *     const response = await fetch('/api/todos', {\n *       method: 'POST',\n *       body: JSON.stringify({ text, completed: false }),\n *     })\n *     const result = await response.json()\n *\n *     // IMPORTANT: Ensure server writes have synced back before returning\n *     // This ensures the optimistic state can be safely discarded\n *     await todoCollection.utils.refetch()\n *\n *     return result\n *   }\n * })\n *\n * // Usage\n * const transaction = addTodo('New Todo Item')\n * ```\n *\n * @template TVariables - The type of variables that will be passed to the action function\n * @param options - Configuration options for the optimistic action\n * @returns A function that accepts variables of type TVariables and returns a Transaction\n */\nexport function createOptimisticAction<TVariables = unknown>(\n  options: CreateOptimisticActionsOptions<TVariables>\n) {\n  const { mutationFn, onMutate, ...config } = options\n\n  return (variables: TVariables): Transaction => {\n    // Create transaction with the original config\n    const transaction = createTransaction({\n      ...config,\n      // Wire the mutationFn to use the provided variables\n      mutationFn: async (params) => {\n        return await mutationFn(variables, params)\n      },\n    })\n\n    // Execute the transaction. The mutationFn is called once mutate()\n    // is finished.\n    transaction.mutate(() => {\n      // Call onMutate with variables to apply optimistic updates\n      onMutate(variables)\n    })\n\n    return transaction\n  }\n}\n"],"names":[],"mappings":";AAmDO,SAAS,uBACd,SACA;AACA,QAAM,EAAE,YAAY,UAAU,GAAG,WAAW;AAE5C,SAAO,CAAC,cAAuC;AAE7C,UAAM,cAAc,kBAAkB;AAAA,MACpC,GAAG;AAAA;AAAA,MAEH,YAAY,OAAO,WAAW;AAC5B,eAAO,MAAM,WAAW,WAAW,MAAM;AAAA,MAC3C;AAAA,IAAA,CACD;AAID,gBAAY,OAAO,MAAM;AAEvB,eAAS,SAAS;AAAA,IACpB,CAAC;AAED,WAAO;AAAA,EACT;AACF;"}
+{"version":3,"file":"optimistic-action.js","sources":["../../src/optimistic-action.ts"],"sourcesContent":["import { createTransaction } from \"./transactions\"\nimport { OnMutateMustBeSynchronousError } from \"./errors\"\nimport { isPromiseLike } from \"./utils/type-guards\"\nimport type { CreateOptimisticActionsOptions, Transaction } from \"./types\"\n\n/**\n * Creates an optimistic action function that applies local optimistic updates immediately\n * before executing the actual mutation on the server.\n *\n * This pattern allows for responsive UI updates while the actual mutation is in progress.\n * The optimistic update is applied via the `onMutate` callback, and the server mutation\n * is executed via the `mutationFn`.\n *\n * **Important:** Inside your `mutationFn`, you must ensure that your server writes have synced back\n * before you return, as the optimistic state is dropped when you return from the mutation function.\n * You generally use collection-specific helpers to do this, such as Query's `utils.refetch()`,\n * direct write APIs, or Electric's `utils.awaitTxId()`.\n *\n * @example\n * ```ts\n * const addTodo = createOptimisticAction<string>({\n *   onMutate: (text) => {\n *     // Instantly applies local optimistic state\n *     todoCollection.insert({\n *       id: uuid(),\n *       text,\n *       completed: false\n *     })\n *   },\n *   mutationFn: async (text, params) => {\n *     // Persist the todo to your backend\n *     const response = await fetch('/api/todos', {\n *       method: 'POST',\n *       body: JSON.stringify({ text, completed: false }),\n *     })\n *     const result = await response.json()\n *\n *     // IMPORTANT: Ensure server writes have synced back before returning\n *     // This ensures the optimistic state can be safely discarded\n *     await todoCollection.utils.refetch()\n *\n *     return result\n *   }\n * })\n *\n * // Usage\n * const transaction = addTodo('New Todo Item')\n * ```\n *\n * @template TVariables - The type of variables that will be passed to the action function\n * @param options - Configuration options for the optimistic action\n * @returns A function that accepts variables of type TVariables and returns a Transaction\n */\nexport function createOptimisticAction<TVariables = unknown>(\n  options: CreateOptimisticActionsOptions<TVariables>\n) {\n  const { mutationFn, onMutate, ...config } = options\n\n  return (variables: TVariables): Transaction => {\n    // Create transaction with the original config\n    const transaction = createTransaction({\n      ...config,\n      // Wire the mutationFn to use the provided variables\n      mutationFn: async (params) => {\n        return await mutationFn(variables, params)\n      },\n    })\n\n    // Execute the transaction. The mutationFn is called once mutate()\n    // is finished.\n    transaction.mutate(() => {\n      const maybePromise = onMutate(variables) as unknown\n\n      if (isPromiseLike(maybePromise)) {\n        throw new OnMutateMustBeSynchronousError()\n      }\n    })\n\n    return transaction\n  }\n}\n"],"names":[],"mappings":";;;AAqDO,SAAS,uBACd,SACA;AACA,QAAM,EAAE,YAAY,UAAU,GAAG,WAAW;AAE5C,SAAO,CAAC,cAAuC;AAE7C,UAAM,cAAc,kBAAkB;AAAA,MACpC,GAAG;AAAA;AAAA,MAEH,YAAY,OAAO,WAAW;AAC5B,eAAO,MAAM,WAAW,WAAW,MAAM;AAAA,MAC3C;AAAA,IAAA,CACD;AAID,gBAAY,OAAO,MAAM;AACvB,YAAM,eAAe,SAAS,SAAS;AAEvC,UAAI,cAAc,YAAY,GAAG;AAC/B,cAAM,IAAI,+BAAA;AAAA,MACZ;AAAA,IACF,CAAC;AAED,WAAO;AAAA,EACT;AACF;"}

package/dist/esm/paced-mutations.d.ts

@@ -47,7 +47,7 @@ export interface PacedMutationsConfig<TVariables = unknown, T extends object = R
  *     // 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 })
@@ -67,7 +67,7 @@ export interface PacedMutationsConfig<TVariables = unknown, T extends object = R
  *   onMutate: ({ text }) => {
  *     collection.insert({ id: uuid(), text, completed: false })
  *   },
- *   mutationFn: async ({ text }, { transaction }) => {
+ *   mutationFn: async ({ transaction }) => {
  *     await api.save(transaction.mutations)
  *   },
  *   strategy: queueStrategy({

package/dist/esm/paced-mutations.js.map

@@ -1 +1 @@
-{"version":3,"file":"paced-mutations.js","sources":["../../src/paced-mutations.ts"],"sourcesContent":["import { createTransaction } from \"./transactions\"\nimport type { MutationFn, Transaction } from \"./types\"\nimport type { Strategy } from \"./strategies/types\"\n\n/**\n * Configuration for creating a paced mutations manager\n */\nexport interface PacedMutationsConfig<\n  TVariables = unknown,\n  T extends object = Record<string, unknown>,\n> {\n  /**\n   * Callback to apply optimistic updates immediately.\n   * Receives the variables passed to the mutate function.\n   */\n  onMutate: (variables: TVariables) => void\n  /**\n   * Function to execute the mutation on the server.\n   * Receives the transaction parameters containing all merged mutations.\n   */\n  mutationFn: MutationFn<T>\n  /**\n   * Strategy for controlling mutation execution timing\n   * Examples: debounceStrategy, queueStrategy, throttleStrategy\n   */\n  strategy: Strategy\n  /**\n   * Custom metadata to associate with transactions\n   */\n  metadata?: Record<string, unknown>\n}\n\n/**\n * Creates a paced mutations manager with pluggable timing strategies.\n *\n * This function provides a way to control when and how optimistic mutations\n * are persisted to the backend, using strategies like debouncing, queuing,\n * or throttling. The optimistic updates are applied immediately via `onMutate`,\n * and the actual persistence is controlled by the strategy.\n *\n * The returned function accepts variables of type TVariables and returns a\n * Transaction object that can be awaited to know when persistence completes\n * or to handle errors.\n *\n * @param config - Configuration including onMutate, mutationFn and strategy\n * @returns A function that accepts variables and returns a Transaction\n *\n * @example\n * ```ts\n * // Debounced mutations for auto-save\n * const updateTodo = createPacedMutations<string>({\n *   onMutate: (text) => {\n *     // Apply optimistic update immediately\n *     collection.update(id, draft => { draft.text = text })\n *   },\n *   mutationFn: async (text, { transaction }) => {\n *     await api.save(transaction.mutations)\n *   },\n *   strategy: debounceStrategy({ wait: 500 })\n * })\n *\n * // Call with variables, returns a transaction\n * const tx = updateTodo('New text')\n *\n * // Await persistence or handle errors\n * await tx.isPersisted.promise\n * ```\n *\n * @example\n * ```ts\n * // Queue strategy for sequential processing\n * const addTodo = createPacedMutations<{ text: string }>({\n *   onMutate: ({ text }) => {\n *     collection.insert({ id: uuid(), text, completed: false })\n *   },\n *   mutationFn: async ({ text }, { transaction }) => {\n *     await api.save(transaction.mutations)\n *   },\n *   strategy: queueStrategy({\n *     wait: 200,\n *     addItemsTo: 'back',\n *     getItemsFrom: 'front'\n *   })\n * })\n * ```\n */\nexport function createPacedMutations<\n  TVariables = unknown,\n  T extends object = Record<string, unknown>,\n>(\n  config: PacedMutationsConfig<TVariables, T>\n): (variables: TVariables) => Transaction<T> {\n  const { onMutate, mutationFn, strategy, ...transactionConfig } = config\n\n  // The currently active transaction (pending, not yet persisting)\n  let activeTransaction: Transaction<T> | null = null\n\n  // Commit callback that the strategy will call when it's time to persist\n  const commitCallback = () => {\n    if (!activeTransaction) {\n      throw new Error(\n        `Strategy callback called but no active transaction exists. This indicates a bug in the strategy implementation.`\n      )\n    }\n\n    if (activeTransaction.state !== `pending`) {\n      throw new Error(\n        `Strategy callback called but active transaction is in state \"${activeTransaction.state}\". Expected \"pending\".`\n      )\n    }\n\n    const txToCommit = activeTransaction\n\n    // Clear active transaction reference before committing\n    activeTransaction = null\n\n    // Commit the transaction\n    txToCommit.commit().catch(() => {\n      // Errors are handled via transaction.isPersisted.promise\n      // This catch prevents unhandled promise rejections\n    })\n\n    return txToCommit\n  }\n\n  /**\n   * Executes a mutation with the given variables. Creates a new transaction if none is active,\n   * or adds to the existing active transaction. The strategy controls when\n   * the transaction is actually committed.\n   */\n  function mutate(variables: TVariables): Transaction<T> {\n    // Create a new transaction if we don't have an active one\n    if (!activeTransaction || activeTransaction.state !== `pending`) {\n      activeTransaction = createTransaction<T>({\n        ...transactionConfig,\n        mutationFn,\n        autoCommit: false,\n      })\n    }\n\n    // Execute onMutate with variables to apply optimistic updates\n    activeTransaction.mutate(() => {\n      onMutate(variables)\n    })\n\n    // Save reference before calling strategy.execute\n    const txToReturn = activeTransaction\n\n    // For queue strategy, pass a function that commits the captured transaction\n    // This prevents the error when commitCallback tries to access the cleared activeTransaction\n    if (strategy._type === `queue`) {\n      const capturedTx = activeTransaction\n      activeTransaction = null // Clear so next mutation creates a new transaction\n      strategy.execute(() => {\n        capturedTx.commit().catch(() => {\n          // Errors are handled via transaction.isPersisted.promise\n        })\n        return capturedTx\n      })\n    } else {\n      // For debounce/throttle, use commitCallback which manages activeTransaction\n      strategy.execute(commitCallback)\n    }\n\n    return txToReturn\n  }\n\n  return mutate\n}\n"],"names":[],"mappings":";AAsFO,SAAS,qBAId,QAC2C;AAC3C,QAAM,EAAE,UAAU,YAAY,UAAU,GAAG,sBAAsB;AAGjE,MAAI,oBAA2C;AAG/C,QAAM,iBAAiB,MAAM;AAC3B,QAAI,CAAC,mBAAmB;AACtB,YAAM,IAAI;AAAA,QACR;AAAA,MAAA;AAAA,IAEJ;AAEA,QAAI,kBAAkB,UAAU,WAAW;AACzC,YAAM,IAAI;AAAA,QACR,gEAAgE,kBAAkB,KAAK;AAAA,MAAA;AAAA,IAE3F;AAEA,UAAM,aAAa;AAGnB,wBAAoB;AAGpB,eAAW,SAAS,MAAM,MAAM;AAAA,IAGhC,CAAC;AAED,WAAO;AAAA,EACT;AAOA,WAAS,OAAO,WAAuC;AAErD,QAAI,CAAC,qBAAqB,kBAAkB,UAAU,WAAW;AAC/D,0BAAoB,kBAAqB;AAAA,QACvC,GAAG;AAAA,QACH;AAAA,QACA,YAAY;AAAA,MAAA,CACb;AAAA,IACH;AAGA,sBAAkB,OAAO,MAAM;AAC7B,eAAS,SAAS;AAAA,IACpB,CAAC;AAGD,UAAM,aAAa;AAInB,QAAI,SAAS,UAAU,SAAS;AAC9B,YAAM,aAAa;AACnB,0BAAoB;AACpB,eAAS,QAAQ,MAAM;AACrB,mBAAW,SAAS,MAAM,MAAM;AAAA,QAEhC,CAAC;AACD,eAAO;AAAA,MACT,CAAC;AAAA,IACH,OAAO;AAEL,eAAS,QAAQ,cAAc;AAAA,IACjC;AAEA,WAAO;AAAA,EACT;AAEA,SAAO;AACT;"}
+{"version":3,"file":"paced-mutations.js","sources":["../../src/paced-mutations.ts"],"sourcesContent":["import { createTransaction } from \"./transactions\"\nimport type { MutationFn, Transaction } from \"./types\"\nimport type { Strategy } from \"./strategies/types\"\n\n/**\n * Configuration for creating a paced mutations manager\n */\nexport interface PacedMutationsConfig<\n  TVariables = unknown,\n  T extends object = Record<string, unknown>,\n> {\n  /**\n   * Callback to apply optimistic updates immediately.\n   * Receives the variables passed to the mutate function.\n   */\n  onMutate: (variables: TVariables) => void\n  /**\n   * Function to execute the mutation on the server.\n   * Receives the transaction parameters containing all merged mutations.\n   */\n  mutationFn: MutationFn<T>\n  /**\n   * Strategy for controlling mutation execution timing\n   * Examples: debounceStrategy, queueStrategy, throttleStrategy\n   */\n  strategy: Strategy\n  /**\n   * Custom metadata to associate with transactions\n   */\n  metadata?: Record<string, unknown>\n}\n\n/**\n * Creates a paced mutations manager with pluggable timing strategies.\n *\n * This function provides a way to control when and how optimistic mutations\n * are persisted to the backend, using strategies like debouncing, queuing,\n * or throttling. The optimistic updates are applied immediately via `onMutate`,\n * and the actual persistence is controlled by the strategy.\n *\n * The returned function accepts variables of type TVariables and returns a\n * Transaction object that can be awaited to know when persistence completes\n * or to handle errors.\n *\n * @param config - Configuration including onMutate, mutationFn and strategy\n * @returns A function that accepts variables and returns a Transaction\n *\n * @example\n * ```ts\n * // Debounced mutations for auto-save\n * const updateTodo = createPacedMutations<string>({\n *   onMutate: (text) => {\n *     // Apply optimistic update immediately\n *     collection.update(id, draft => { draft.text = text })\n *   },\n *   mutationFn: async ({ transaction }) => {\n *     await api.save(transaction.mutations)\n *   },\n *   strategy: debounceStrategy({ wait: 500 })\n * })\n *\n * // Call with variables, returns a transaction\n * const tx = updateTodo('New text')\n *\n * // Await persistence or handle errors\n * await tx.isPersisted.promise\n * ```\n *\n * @example\n * ```ts\n * // Queue strategy for sequential processing\n * const addTodo = createPacedMutations<{ text: string }>({\n *   onMutate: ({ text }) => {\n *     collection.insert({ id: uuid(), text, completed: false })\n *   },\n *   mutationFn: async ({ transaction }) => {\n *     await api.save(transaction.mutations)\n *   },\n *   strategy: queueStrategy({\n *     wait: 200,\n *     addItemsTo: 'back',\n *     getItemsFrom: 'front'\n *   })\n * })\n * ```\n */\nexport function createPacedMutations<\n  TVariables = unknown,\n  T extends object = Record<string, unknown>,\n>(\n  config: PacedMutationsConfig<TVariables, T>\n): (variables: TVariables) => Transaction<T> {\n  const { onMutate, mutationFn, strategy, ...transactionConfig } = config\n\n  // The currently active transaction (pending, not yet persisting)\n  let activeTransaction: Transaction<T> | null = null\n\n  // Commit callback that the strategy will call when it's time to persist\n  const commitCallback = () => {\n    if (!activeTransaction) {\n      throw new Error(\n        `Strategy callback called but no active transaction exists. This indicates a bug in the strategy implementation.`\n      )\n    }\n\n    if (activeTransaction.state !== `pending`) {\n      throw new Error(\n        `Strategy callback called but active transaction is in state \"${activeTransaction.state}\". Expected \"pending\".`\n      )\n    }\n\n    const txToCommit = activeTransaction\n\n    // Clear active transaction reference before committing\n    activeTransaction = null\n\n    // Commit the transaction\n    txToCommit.commit().catch(() => {\n      // Errors are handled via transaction.isPersisted.promise\n      // This catch prevents unhandled promise rejections\n    })\n\n    return txToCommit\n  }\n\n  /**\n   * Executes a mutation with the given variables. Creates a new transaction if none is active,\n   * or adds to the existing active transaction. The strategy controls when\n   * the transaction is actually committed.\n   */\n  function mutate(variables: TVariables): Transaction<T> {\n    // Create a new transaction if we don't have an active one\n    if (!activeTransaction || activeTransaction.state !== `pending`) {\n      activeTransaction = createTransaction<T>({\n        ...transactionConfig,\n        mutationFn,\n        autoCommit: false,\n      })\n    }\n\n    // Execute onMutate with variables to apply optimistic updates\n    activeTransaction.mutate(() => {\n      onMutate(variables)\n    })\n\n    // Save reference before calling strategy.execute\n    const txToReturn = activeTransaction\n\n    // For queue strategy, pass a function that commits the captured transaction\n    // This prevents the error when commitCallback tries to access the cleared activeTransaction\n    if (strategy._type === `queue`) {\n      const capturedTx = activeTransaction\n      activeTransaction = null // Clear so next mutation creates a new transaction\n      strategy.execute(() => {\n        capturedTx.commit().catch(() => {\n          // Errors are handled via transaction.isPersisted.promise\n        })\n        return capturedTx\n      })\n    } else {\n      // For debounce/throttle, use commitCallback which manages activeTransaction\n      strategy.execute(commitCallback)\n    }\n\n    return txToReturn\n  }\n\n  return mutate\n}\n"],"names":[],"mappings":";AAsFO,SAAS,qBAId,QAC2C;AAC3C,QAAM,EAAE,UAAU,YAAY,UAAU,GAAG,sBAAsB;AAGjE,MAAI,oBAA2C;AAG/C,QAAM,iBAAiB,MAAM;AAC3B,QAAI,CAAC,mBAAmB;AACtB,YAAM,IAAI;AAAA,QACR;AAAA,MAAA;AAAA,IAEJ;AAEA,QAAI,kBAAkB,UAAU,WAAW;AACzC,YAAM,IAAI;AAAA,QACR,gEAAgE,kBAAkB,KAAK;AAAA,MAAA;AAAA,IAE3F;AAEA,UAAM,aAAa;AAGnB,wBAAoB;AAGpB,eAAW,SAAS,MAAM,MAAM;AAAA,IAGhC,CAAC;AAED,WAAO;AAAA,EACT;AAOA,WAAS,OAAO,WAAuC;AAErD,QAAI,CAAC,qBAAqB,kBAAkB,UAAU,WAAW;AAC/D,0BAAoB,kBAAqB;AAAA,QACvC,GAAG;AAAA,QACH;AAAA,QACA,YAAY;AAAA,MAAA,CACb;AAAA,IACH;AAGA,sBAAkB,OAAO,MAAM;AAC7B,eAAS,SAAS;AAAA,IACpB,CAAC;AAGD,UAAM,aAAa;AAInB,QAAI,SAAS,UAAU,SAAS;AAC9B,YAAM,aAAa;AACnB,0BAAoB;AACpB,eAAS,QAAQ,MAAM;AACrB,mBAAW,SAAS,MAAM,MAAM;AAAA,QAEhC,CAAC;AACD,eAAO;AAAA,MACT,CAAC;AAAA,IACH,OAAO;AAEL,eAAS,QAAQ,cAAc;AAAA,IACjC;AAEA,WAAO;AAAA,EACT;AAEA,SAAO;AACT;"}

package/dist/esm/strategies/debounceStrategy.d.ts

@@ -11,7 +11,10 @@ import { DebounceStrategy, DebounceStrategyOptions } from './types.js';
  *
  * @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/dist/esm/strategies/debounceStrategy.js.map

@@ -1 +1 @@
-{"version":3,"file":"debounceStrategy.js","sources":["../../../src/strategies/debounceStrategy.ts"],"sourcesContent":["import { Debouncer } from \"@tanstack/pacer/debouncer\"\nimport type { DebounceStrategy, DebounceStrategyOptions } from \"./types\"\nimport type { Transaction } from \"../transactions\"\n\n/**\n * Creates a debounce strategy that delays transaction execution until after\n * a period of inactivity.\n *\n * Ideal for scenarios like search inputs or auto-save fields where you want\n * to wait for the user to stop typing before persisting changes.\n *\n * @param options - Configuration for the debounce behavior\n * @returns A debounce strategy instance\n *\n * @example\n * ```ts\n * const mutate = useSerializedTransaction({\n *   mutationFn: async ({ transaction }) => {\n *     await api.save(transaction.mutations)\n *   },\n *   strategy: debounceStrategy({ wait: 500 })\n * })\n * ```\n */\nexport function debounceStrategy(\n  options: DebounceStrategyOptions\n): DebounceStrategy {\n  const debouncer = new Debouncer(\n    (callback: () => Transaction) => callback(),\n    options\n  )\n\n  return {\n    _type: `debounce`,\n    options,\n    execute: <T extends object = Record<string, unknown>>(\n      fn: () => Transaction<T>\n    ) => {\n      debouncer.maybeExecute(fn as () => Transaction)\n    },\n    cleanup: () => {\n      debouncer.cancel()\n    },\n  }\n}\n"],"names":[],"mappings":";AAwBO,SAAS,iBACd,SACkB;AAClB,QAAM,YAAY,IAAI;AAAA,IACpB,CAAC,aAAgC,SAAA;AAAA,IACjC;AAAA,EAAA;AAGF,SAAO;AAAA,IACL,OAAO;AAAA,IACP;AAAA,IACA,SAAS,CACP,OACG;AACH,gBAAU,aAAa,EAAuB;AAAA,IAChD;AAAA,IACA,SAAS,MAAM;AACb,gBAAU,OAAA;AAAA,IACZ;AAAA,EAAA;AAEJ;"}
+{"version":3,"file":"debounceStrategy.js","sources":["../../../src/strategies/debounceStrategy.ts"],"sourcesContent":["import { Debouncer } from \"@tanstack/pacer/debouncer\"\nimport type { DebounceStrategy, DebounceStrategyOptions } from \"./types\"\nimport type { Transaction } from \"../transactions\"\n\n/**\n * Creates a debounce strategy that delays transaction execution until after\n * a period of inactivity.\n *\n * Ideal for scenarios like search inputs or auto-save fields where you want\n * to wait for the user to stop typing before persisting changes.\n *\n * @param options - Configuration for the debounce behavior\n * @returns A debounce strategy instance\n *\n * @example\n * ```ts\n * const mutate = usePacedMutations({\n *   onMutate: (value) => {\n *     collection.update(id, draft => { draft.value = value })\n *   },\n *   mutationFn: async ({ transaction }) => {\n *     await api.save(transaction.mutations)\n *   },\n *   strategy: debounceStrategy({ wait: 500 })\n * })\n * ```\n */\nexport function debounceStrategy(\n  options: DebounceStrategyOptions\n): DebounceStrategy {\n  const debouncer = new Debouncer(\n    (callback: () => Transaction) => callback(),\n    options\n  )\n\n  return {\n    _type: `debounce`,\n    options,\n    execute: <T extends object = Record<string, unknown>>(\n      fn: () => Transaction<T>\n    ) => {\n      debouncer.maybeExecute(fn as () => Transaction)\n    },\n    cleanup: () => {\n      debouncer.cancel()\n    },\n  }\n}\n"],"names":[],"mappings":";AA2BO,SAAS,iBACd,SACkB;AAClB,QAAM,YAAY,IAAI;AAAA,IACpB,CAAC,aAAgC,SAAA;AAAA,IACjC;AAAA,EAAA;AAGF,SAAO;AAAA,IACL,OAAO;AAAA,IACP;AAAA,IACA,SAAS,CACP,OACG;AACH,gBAAU,aAAa,EAAuB;AAAA,IAChD;AAAA,IACA,SAAS,MAAM;AACb,gBAAU,OAAA;AAAA,IACZ;AAAA,EAAA;AAEJ;"}

package/dist/esm/strategies/throttleStrategy.d.ts

@@ -13,7 +13,10 @@ import { ThrottleStrategy, ThrottleStrategyOptions } from './types.js';
  * @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)
  *   },
@@ -24,7 +27,10 @@ import { ThrottleStrategy, ThrottleStrategyOptions } from './types.js';
  * @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/dist/esm/strategies/throttleStrategy.js.map

@@ -1 +1 @@
-{"version":3,"file":"throttleStrategy.js","sources":["../../../src/strategies/throttleStrategy.ts"],"sourcesContent":["import { Throttler } from \"@tanstack/pacer/throttler\"\nimport type { ThrottleStrategy, ThrottleStrategyOptions } from \"./types\"\nimport type { Transaction } from \"../transactions\"\n\n/**\n * Creates a throttle strategy that ensures transactions are evenly spaced\n * over time.\n *\n * Provides smooth, controlled execution patterns ideal for UI updates like\n * sliders, progress bars, or scroll handlers where you want consistent\n * execution timing.\n *\n * @param options - Configuration for throttle behavior\n * @returns A throttle strategy instance\n *\n * @example\n * ```ts\n * // Throttle slider updates to every 200ms\n * const mutate = useSerializedTransaction({\n *   mutationFn: async ({ transaction }) => {\n *     await api.updateVolume(transaction.mutations)\n *   },\n *   strategy: throttleStrategy({ wait: 200 })\n * })\n * ```\n *\n * @example\n * ```ts\n * // Throttle with leading and trailing execution\n * const mutate = useSerializedTransaction({\n *   mutationFn: async ({ transaction }) => {\n *     await api.save(transaction.mutations)\n *   },\n *   strategy: throttleStrategy({\n *     wait: 500,\n *     leading: true,\n *     trailing: true\n *   })\n * })\n * ```\n */\nexport function throttleStrategy(\n  options: ThrottleStrategyOptions\n): ThrottleStrategy {\n  const throttler = new Throttler(\n    (callback: () => Transaction) => callback(),\n    options\n  )\n\n  return {\n    _type: `throttle`,\n    options,\n    execute: <T extends object = Record<string, unknown>>(\n      fn: () => Transaction<T>\n    ) => {\n      throttler.maybeExecute(fn as () => Transaction)\n    },\n    cleanup: () => {\n      throttler.cancel()\n    },\n  }\n}\n"],"names":[],"mappings":";AAyCO,SAAS,iBACd,SACkB;AAClB,QAAM,YAAY,IAAI;AAAA,IACpB,CAAC,aAAgC,SAAA;AAAA,IACjC;AAAA,EAAA;AAGF,SAAO;AAAA,IACL,OAAO;AAAA,IACP;AAAA,IACA,SAAS,CACP,OACG;AACH,gBAAU,aAAa,EAAuB;AAAA,IAChD;AAAA,IACA,SAAS,MAAM;AACb,gBAAU,OAAA;AAAA,IACZ;AAAA,EAAA;AAEJ;"}
+{"version":3,"file":"throttleStrategy.js","sources":["../../../src/strategies/throttleStrategy.ts"],"sourcesContent":["import { Throttler } from \"@tanstack/pacer/throttler\"\nimport type { ThrottleStrategy, ThrottleStrategyOptions } from \"./types\"\nimport type { Transaction } from \"../transactions\"\n\n/**\n * Creates a throttle strategy that ensures transactions are evenly spaced\n * over time.\n *\n * Provides smooth, controlled execution patterns ideal for UI updates like\n * sliders, progress bars, or scroll handlers where you want consistent\n * execution timing.\n *\n * @param options - Configuration for throttle behavior\n * @returns A throttle strategy instance\n *\n * @example\n * ```ts\n * // Throttle slider updates to every 200ms\n * const mutate = usePacedMutations({\n *   onMutate: (volume) => {\n *     settingsCollection.update('volume', draft => { draft.value = volume })\n *   },\n *   mutationFn: async ({ transaction }) => {\n *     await api.updateVolume(transaction.mutations)\n *   },\n *   strategy: throttleStrategy({ wait: 200 })\n * })\n * ```\n *\n * @example\n * ```ts\n * // Throttle with leading and trailing execution\n * const mutate = usePacedMutations({\n *   onMutate: (data) => {\n *     collection.update(id, draft => { Object.assign(draft, data) })\n *   },\n *   mutationFn: async ({ transaction }) => {\n *     await api.save(transaction.mutations)\n *   },\n *   strategy: throttleStrategy({\n *     wait: 500,\n *     leading: true,\n *     trailing: true\n *   })\n * })\n * ```\n */\nexport function throttleStrategy(\n  options: ThrottleStrategyOptions\n): ThrottleStrategy {\n  const throttler = new Throttler(\n    (callback: () => Transaction) => callback(),\n    options\n  )\n\n  return {\n    _type: `throttle`,\n    options,\n    execute: <T extends object = Record<string, unknown>>(\n      fn: () => Transaction<T>\n    ) => {\n      throttler.maybeExecute(fn as () => Transaction)\n    },\n    cleanup: () => {\n      throttler.cancel()\n    },\n  }\n}\n"],"names":[],"mappings":";AA+CO,SAAS,iBACd,SACkB;AAClB,QAAM,YAAY,IAAI;AAAA,IACpB,CAAC,aAAgC,SAAA;AAAA,IACjC;AAAA,EAAA;AAGF,SAAO;AAAA,IACL,OAAO;AAAA,IACP;AAAA,IACA,SAAS,CACP,OACG;AACH,gBAAU,aAAa,EAAuB;AAAA,IAChD;AAAA,IACA,SAAS,MAAM;AACb,gBAAU,OAAA;AAAA,IACZ;AAAA,EAAA;AAEJ;"}

package/dist/esm/transactions.d.ts

@@ -83,7 +83,9 @@ declare class Transaction<T extends object = Record<string, unknown>> {
     setState(newState: TransactionState): void;
     /**
      * 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

package/dist/esm/transactions.js

@@ -101,7 +101,9 @@ class Transaction {
   }
   /**
    * 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

package/dist/esm/transactions.js.map

@@ -1 +1 @@
-{"version":3,"file":"transactions.js","sources":["../../src/transactions.ts"],"sourcesContent":["import { createDeferred } from \"./deferred\"\nimport {\n  MissingMutationFunctionError,\n  TransactionAlreadyCompletedRollbackError,\n  TransactionNotPendingCommitError,\n  TransactionNotPendingMutateError,\n} from \"./errors\"\nimport { transactionScopedScheduler } from \"./scheduler.js\"\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 * Merges two pending mutations for the same item within a transaction\n *\n * Merge behavior truth table:\n * - (insert, update) → insert (merge changes, keep empty original)\n * - (insert, delete) → null (cancel both mutations)\n * - (update, delete) → delete (delete dominates)\n * - (update, update) → update (replace with latest, union changes)\n * - (delete, delete) → delete (replace with latest)\n * - (insert, insert) → insert (replace with latest)\n *\n * Note: (delete, update) and (delete, insert) should never occur as the collection\n * layer prevents operations on deleted items within the same transaction.\n *\n * @param existing - The existing mutation in the transaction\n * @param incoming - The new mutation being applied\n * @returns The merged mutation, or null if both should be removed\n */\nfunction mergePendingMutations<T extends object>(\n  existing: PendingMutation<T>,\n  incoming: PendingMutation<T>\n): PendingMutation<T> | null {\n  // Truth table implementation\n  switch (`${existing.type}-${incoming.type}` as const) {\n    case `insert-update`: {\n      // Update after insert: keep as insert but merge changes\n      // For insert-update, the key should remain the same since collections don't allow key changes\n      return {\n        ...existing,\n        type: `insert` as const,\n        original: {},\n        modified: incoming.modified,\n        changes: { ...existing.changes, ...incoming.changes },\n        // Keep existing keys (key changes not allowed in updates)\n        key: existing.key,\n        globalKey: existing.globalKey,\n        // Merge metadata (last-write-wins)\n        metadata: incoming.metadata ?? existing.metadata,\n        syncMetadata: { ...existing.syncMetadata, ...incoming.syncMetadata },\n        // Update tracking info\n        mutationId: incoming.mutationId,\n        updatedAt: incoming.updatedAt,\n      }\n    }\n\n    case `insert-delete`:\n      // Delete after insert: cancel both mutations\n      return null\n\n    case `update-delete`:\n      // Delete after update: delete dominates\n      return incoming\n\n    case `update-update`: {\n      // Update after update: replace with latest, union changes\n      return {\n        ...incoming,\n        // Keep original from first update\n        original: existing.original,\n        // Union the changes from both updates\n        changes: { ...existing.changes, ...incoming.changes },\n        // Merge metadata\n        metadata: incoming.metadata ?? existing.metadata,\n        syncMetadata: { ...existing.syncMetadata, ...incoming.syncMetadata },\n      }\n    }\n\n    case `delete-delete`:\n    case `insert-insert`:\n      // Same type: replace with latest\n      return incoming\n\n    default: {\n      // Exhaustiveness check\n      const _exhaustive: never = `${existing.type}-${incoming.type}` as never\n      throw new Error(`Unhandled mutation combination: ${_exhaustive}`)\n    }\n  }\n}\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  // Clear any stale work that may have been left behind if a previous mutate\n  // scope aborted before we could flush.\n  transactionScopedScheduler.clear(tx.id)\n  transactionStack.push(tx)\n}\n\nfunction unregisterTransaction(tx: Transaction<any>) {\n  // Always flush pending work for this transaction before removing it from\n  // the ambient stack – this runs even if the mutate callback throws.\n  // If flush throws (e.g., due to a job error), we still clean up the stack.\n  try {\n    transactionScopedScheduler.flush(tx.id)\n  } finally {\n    transactionStack = transactionStack.filter((t) => t.id !== tx.id)\n  }\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 new MissingMutationFunctionError()\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 new TransactionNotPendingMutateError()\n    }\n\n    registerTransaction(this)\n    try {\n      callback()\n    } finally {\n      unregisterTransaction(this)\n    }\n\n    if (this.autoCommit) {\n      this.commit().catch(() => {\n        // Errors from autoCommit are handled via isPersisted.promise\n        // This catch prevents unhandled promise rejections\n      })\n    }\n\n    return this\n  }\n\n  /**\n   * Apply new mutations to this transaction, intelligently merging with existing mutations\n   *\n   * When mutations operate on the same item (same globalKey), they are merged according to\n   * the following rules:\n   *\n   * - **insert + update** → insert (merge changes, keep empty original)\n   * - **insert + delete** → removed (mutations cancel each other out)\n   * - **update + delete** → delete (delete dominates)\n   * - **update + update** → update (union changes, keep first original)\n   * - **same type** → replace with latest\n   *\n   * This merging reduces over-the-wire churn and keeps the optimistic local view\n   * aligned with user intent.\n   *\n   * @param mutations - Array of new mutations to apply\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        const existingMutation = this.mutations[existingIndex]!\n        const mergeResult = mergePendingMutations(existingMutation, newMutation)\n\n        if (mergeResult === null) {\n          // Remove the mutation (e.g., delete after insert cancels both)\n          this.mutations.splice(existingIndex, 1)\n        } else {\n          // Replace with merged mutation\n          this.mutations[existingIndex] = mergeResult\n        }\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 new TransactionAlreadyCompletedRollbackError()\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._state.onTransactionStateChange()\n\n        // Only call commitPendingTransactions if there are pending sync transactions\n        if (mutation.collection._state.pendingSyncedTransactions.length > 0) {\n          mutation.collection._state.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 new TransactionNotPendingCommitError()\n    }\n\n    this.setState(`persisting`)\n\n    if (this.mutations.length === 0) {\n      this.setState(`completed`)\n      this.isPersisted.resolve(this)\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      // Preserve the original error for rethrowing\n      const originalError =\n        error instanceof Error ? error : new Error(String(error))\n\n      // Update transaction with error information\n      this.error = {\n        message: originalError.message,\n        error: originalError,\n      }\n\n      // rollback the transaction\n      this.rollback()\n\n      // Re-throw the original error to preserve identity and stack\n      throw originalError\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 \"./duplicate-instance-check\"\nimport {\n  MissingMutationFunctionError,\n  TransactionAlreadyCompletedRollbackError,\n  TransactionNotPendingCommitError,\n  TransactionNotPendingMutateError,\n} from \"./errors\"\nimport { transactionScopedScheduler } from \"./scheduler.js\"\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 * Merges two pending mutations for the same item within a transaction\n *\n * Merge behavior truth table:\n * - (insert, update) → insert (merge changes, keep empty original)\n * - (insert, delete) → null (cancel both mutations)\n * - (update, delete) → delete (delete dominates)\n * - (update, update) → update (replace with latest, union changes)\n * - (delete, delete) → delete (replace with latest)\n * - (insert, insert) → insert (replace with latest)\n *\n * Note: (delete, update) and (delete, insert) should never occur as the collection\n * layer prevents operations on deleted items within the same transaction.\n *\n * @param existing - The existing mutation in the transaction\n * @param incoming - The new mutation being applied\n * @returns The merged mutation, or null if both should be removed\n */\nfunction mergePendingMutations<T extends object>(\n  existing: PendingMutation<T>,\n  incoming: PendingMutation<T>\n): PendingMutation<T> | null {\n  // Truth table implementation\n  switch (`${existing.type}-${incoming.type}` as const) {\n    case `insert-update`: {\n      // Update after insert: keep as insert but merge changes\n      // For insert-update, the key should remain the same since collections don't allow key changes\n      return {\n        ...existing,\n        type: `insert` as const,\n        original: {},\n        modified: incoming.modified,\n        changes: { ...existing.changes, ...incoming.changes },\n        // Keep existing keys (key changes not allowed in updates)\n        key: existing.key,\n        globalKey: existing.globalKey,\n        // Merge metadata (last-write-wins)\n        metadata: incoming.metadata ?? existing.metadata,\n        syncMetadata: { ...existing.syncMetadata, ...incoming.syncMetadata },\n        // Update tracking info\n        mutationId: incoming.mutationId,\n        updatedAt: incoming.updatedAt,\n      }\n    }\n\n    case `insert-delete`:\n      // Delete after insert: cancel both mutations\n      return null\n\n    case `update-delete`:\n      // Delete after update: delete dominates\n      return incoming\n\n    case `update-update`: {\n      // Update after update: replace with latest, union changes\n      return {\n        ...incoming,\n        // Keep original from first update\n        original: existing.original,\n        // Union the changes from both updates\n        changes: { ...existing.changes, ...incoming.changes },\n        // Merge metadata\n        metadata: incoming.metadata ?? existing.metadata,\n        syncMetadata: { ...existing.syncMetadata, ...incoming.syncMetadata },\n      }\n    }\n\n    case `delete-delete`:\n    case `insert-insert`:\n      // Same type: replace with latest\n      return incoming\n\n    default: {\n      // Exhaustiveness check\n      const _exhaustive: never = `${existing.type}-${incoming.type}` as never\n      throw new Error(`Unhandled mutation combination: ${_exhaustive}`)\n    }\n  }\n}\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  // Clear any stale work that may have been left behind if a previous mutate\n  // scope aborted before we could flush.\n  transactionScopedScheduler.clear(tx.id)\n  transactionStack.push(tx)\n}\n\nfunction unregisterTransaction(tx: Transaction<any>) {\n  // Always flush pending work for this transaction before removing it from\n  // the ambient stack – this runs even if the mutate callback throws.\n  // If flush throws (e.g., due to a job error), we still clean up the stack.\n  try {\n    transactionScopedScheduler.flush(tx.id)\n  } finally {\n    transactionStack = transactionStack.filter((t) => t.id !== tx.id)\n  }\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 new MissingMutationFunctionError()\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. If the\n   * callback returns a Promise, the transaction context will remain active until the promise\n   * settles, allowing optimistic writes after `await` boundaries.\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 new TransactionNotPendingMutateError()\n    }\n\n    registerTransaction(this)\n\n    try {\n      callback()\n    } finally {\n      unregisterTransaction(this)\n    }\n\n    if (this.autoCommit) {\n      this.commit().catch(() => {\n        // Errors from autoCommit are handled via isPersisted.promise\n        // This catch prevents unhandled promise rejections\n      })\n    }\n\n    return this\n  }\n\n  /**\n   * Apply new mutations to this transaction, intelligently merging with existing mutations\n   *\n   * When mutations operate on the same item (same globalKey), they are merged according to\n   * the following rules:\n   *\n   * - **insert + update** → insert (merge changes, keep empty original)\n   * - **insert + delete** → removed (mutations cancel each other out)\n   * - **update + delete** → delete (delete dominates)\n   * - **update + update** → update (union changes, keep first original)\n   * - **same type** → replace with latest\n   *\n   * This merging reduces over-the-wire churn and keeps the optimistic local view\n   * aligned with user intent.\n   *\n   * @param mutations - Array of new mutations to apply\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        const existingMutation = this.mutations[existingIndex]!\n        const mergeResult = mergePendingMutations(existingMutation, newMutation)\n\n        if (mergeResult === null) {\n          // Remove the mutation (e.g., delete after insert cancels both)\n          this.mutations.splice(existingIndex, 1)\n        } else {\n          // Replace with merged mutation\n          this.mutations[existingIndex] = mergeResult\n        }\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 new TransactionAlreadyCompletedRollbackError()\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._state.onTransactionStateChange()\n\n        // Only call commitPendingTransactions if there are pending sync transactions\n        if (mutation.collection._state.pendingSyncedTransactions.length > 0) {\n          mutation.collection._state.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 new TransactionNotPendingCommitError()\n    }\n\n    this.setState(`persisting`)\n\n    if (this.mutations.length === 0) {\n      this.setState(`completed`)\n      this.isPersisted.resolve(this)\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      // Preserve the original error for rethrowing\n      const originalError =\n        error instanceof Error ? error : new Error(String(error))\n\n      // Update transaction with error information\n      this.error = {\n        message: originalError.message,\n        error: originalError,\n      }\n\n      // rollback the transaction\n      this.rollback()\n\n      // Re-throw the original error to preserve identity and stack\n      throw originalError\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/utils/type-guards.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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 declare function isPromiseLike(value: unknown): value is PromiseLike<unknown>;

package/dist/esm/utils/type-guards.js

@@ -0,0 +1,7 @@
+function isPromiseLike(value) {
+  return !!value && (typeof value === `object` || typeof value === `function`) && typeof value.then === `function`;
+}
+export {
+  isPromiseLike
+};
+//# sourceMappingURL=type-guards.js.map

package/dist/esm/utils/type-guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-guards.js","sources":["../../../src/utils/type-guards.ts"],"sourcesContent":["/**\n * Type guard to check if a value is promise-like (has a `.then` method)\n * @param value - The value to check\n * @returns True if the value is promise-like, false otherwise\n */\nexport function isPromiseLike(value: unknown): value is PromiseLike<unknown> {\n  return (\n    !!value &&\n    (typeof value === `object` || typeof value === `function`) &&\n    typeof (value as { then?: unknown }).then === `function`\n  )\n}\n"],"names":[],"mappings":"AAKO,SAAS,cAAc,OAA+C;AAC3E,SACE,CAAC,CAAC,UACD,OAAO,UAAU,YAAY,OAAO,UAAU,eAC/C,OAAQ,MAA6B,SAAS;AAElD;"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tanstack/db",
   "description": "A reactive client store for building super fast apps on sync",
-  "version": "0.4.16",
+  "version": "0.4.17",
   "dependencies": {
     "@standard-schema/spec": "^1.0.0",
     "@tanstack/pacer": "^0.1.0",

package/src/duplicate-instance-check.ts

@@ -0,0 +1,32 @@
+import { DuplicateDbInstanceError } from "./errors"
+
+/**
+ * Check if we're in a browser top-level window (not a worker, SSR, or iframe).
+ * This helps avoid false positives in environments where multiple instances are legitimate.
+ */
+function isBrowserTopWindow(): boolean {
+  const w = (globalThis as any).window
+  // Exclude workers and SSR-ish shims
+  if (!w || !(`document` in w)) return false
+  // Avoid triggering inside iframes (cross-origin iframes can throw)
+  try {
+    return w === w.top
+  } catch {
+    return true // If we can't access w.top due to cross-origin, assume we should check
+  }
+}
+
+// Detect duplicate @tanstack/db instances (dev-only, browser top-window only)
+const DB_INSTANCE_MARKER = Symbol.for(`@tanstack/db/instance-marker`)
+const DEV =
+  typeof process !== `undefined` && process.env.NODE_ENV !== `production`
+const DISABLED =
+  typeof process !== `undefined` &&
+  process.env.TANSTACK_DB_DISABLE_DUP_CHECK === `1`
+
+if (DEV && !DISABLED && isBrowserTopWindow()) {
+  if ((globalThis as any)[DB_INSTANCE_MARKER]) {
+    throw new DuplicateDbInstanceError()
+  }
+  ;(globalThis as any)[DB_INSTANCE_MARKER] = true
+}