@tanstack/db 0.4.8 → 0.4.10

package/dist/cjs/scheduler.cjs

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+class Scheduler {
+  constructor() {
+    this.contexts = /* @__PURE__ */ new Map();
+    this.clearListeners = /* @__PURE__ */ new Set();
+  }
+  /**
+   * Get or create the state bucket for a context.
+   */
+  getOrCreateContext(contextId) {
+    let context = this.contexts.get(contextId);
+    if (!context) {
+      context = {
+        queue: [],
+        jobs: /* @__PURE__ */ new Map(),
+        dependencies: /* @__PURE__ */ new Map(),
+        completed: /* @__PURE__ */ new Set()
+      };
+      this.contexts.set(contextId, context);
+    }
+    return context;
+  }
+  /**
+   * Schedule work. Without a context id, executes immediately.
+   * Otherwise queues the job to be flushed once dependencies are satisfied.
+   * Scheduling the same jobId again replaces the previous run function.
+   */
+  schedule({ contextId, jobId, dependencies, run }) {
+    if (typeof contextId === `undefined`) {
+      run();
+      return;
+    }
+    const context = this.getOrCreateContext(contextId);
+    if (!context.jobs.has(jobId)) {
+      context.queue.push(jobId);
+    }
+    context.jobs.set(jobId, run);
+    if (dependencies) {
+      const depSet = new Set(dependencies);
+      depSet.delete(jobId);
+      context.dependencies.set(jobId, depSet);
+    } else if (!context.dependencies.has(jobId)) {
+      context.dependencies.set(jobId, /* @__PURE__ */ new Set());
+    }
+    context.completed.delete(jobId);
+  }
+  /**
+   * Flush all queued work for a context. Jobs with unmet dependencies are retried.
+   * Throws if a pass completes without running any job (dependency cycle).
+   */
+  flush(contextId) {
+    const context = this.contexts.get(contextId);
+    if (!context) return;
+    const { queue, jobs, dependencies, completed } = context;
+    while (queue.length > 0) {
+      let ranThisPass = false;
+      const jobsThisPass = queue.length;
+      for (let i = 0; i < jobsThisPass; i++) {
+        const jobId = queue.shift();
+        const run = jobs.get(jobId);
+        if (!run) {
+          dependencies.delete(jobId);
+          completed.delete(jobId);
+          continue;
+        }
+        const deps = dependencies.get(jobId);
+        let ready = !deps;
+        if (deps) {
+          ready = true;
+          for (const dep of deps) {
+            if (dep !== jobId && !completed.has(dep)) {
+              ready = false;
+              break;
+            }
+          }
+        }
+        if (ready) {
+          jobs.delete(jobId);
+          dependencies.delete(jobId);
+          run();
+          completed.add(jobId);
+          ranThisPass = true;
+        } else {
+          queue.push(jobId);
+        }
+      }
+      if (!ranThisPass) {
+        throw new Error(
+          `Scheduler detected unresolved dependencies for context ${String(
+            contextId
+          )}.`
+        );
+      }
+    }
+    this.contexts.delete(contextId);
+  }
+  /**
+   * Flush all contexts with pending work. Useful during tear-down.
+   */
+  flushAll() {
+    for (const contextId of Array.from(this.contexts.keys())) {
+      this.flush(contextId);
+    }
+  }
+  /** Clear all scheduled jobs for a context. */
+  clear(contextId) {
+    this.contexts.delete(contextId);
+    this.clearListeners.forEach((listener) => listener(contextId));
+  }
+  /** Register a listener to be notified when a context is cleared. */
+  onClear(listener) {
+    this.clearListeners.add(listener);
+    return () => this.clearListeners.delete(listener);
+  }
+  /** Check if a context has pending jobs. */
+  hasPendingJobs(contextId) {
+    const context = this.contexts.get(contextId);
+    return !!context && context.jobs.size > 0;
+  }
+  /** Remove a single job from a context and clean up its dependencies. */
+  clearJob(contextId, jobId) {
+    const context = this.contexts.get(contextId);
+    if (!context) return;
+    context.jobs.delete(jobId);
+    context.dependencies.delete(jobId);
+    context.completed.delete(jobId);
+    context.queue = context.queue.filter((id) => id !== jobId);
+    if (context.jobs.size === 0) {
+      this.contexts.delete(contextId);
+    }
+  }
+}
+const transactionScopedScheduler = new Scheduler();
+exports.Scheduler = Scheduler;
+exports.transactionScopedScheduler = transactionScopedScheduler;
+//# sourceMappingURL=scheduler.cjs.map

package/dist/cjs/scheduler.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.cjs","sources":["../../src/scheduler.ts"],"sourcesContent":["/**\n * Identifier used to scope scheduled work. Maps to a transaction id for live queries.\n */\nexport type SchedulerContextId = string | symbol\n\n/**\n * Options for {@link Scheduler.schedule}. Jobs are identified by `jobId` within a context\n * and may declare dependencies.\n */\ninterface ScheduleOptions {\n  contextId?: SchedulerContextId\n  jobId: unknown\n  dependencies?: Iterable<unknown>\n  run: () => void\n}\n\n/**\n * State per context. Queue preserves order, jobs hold run functions, dependencies track\n * prerequisites, and completed records which jobs have run during the current flush.\n */\ninterface SchedulerContextState {\n  queue: Array<unknown>\n  jobs: Map<unknown, () => void>\n  dependencies: Map<unknown, Set<unknown>>\n  completed: Set<unknown>\n}\n\n/**\n * Scoped scheduler that coalesces work by context and job.\n *\n * - **context** (e.g. transaction id) defines the batching boundary; work is queued until flushed.\n * - **job id** deduplicates work within a context; scheduling the same job replaces the previous run function.\n * - Without a context id, work executes immediately.\n *\n * Callers manage their own state; the scheduler only orchestrates execution order.\n */\nexport class Scheduler {\n  private contexts = new Map<SchedulerContextId, SchedulerContextState>()\n  private clearListeners = new Set<(contextId: SchedulerContextId) => void>()\n\n  /**\n   * Get or create the state bucket for a context.\n   */\n  private getOrCreateContext(\n    contextId: SchedulerContextId\n  ): SchedulerContextState {\n    let context = this.contexts.get(contextId)\n    if (!context) {\n      context = {\n        queue: [],\n        jobs: new Map(),\n        dependencies: new Map(),\n        completed: new Set(),\n      }\n      this.contexts.set(contextId, context)\n    }\n    return context\n  }\n\n  /**\n   * Schedule work. Without a context id, executes immediately.\n   * Otherwise queues the job to be flushed once dependencies are satisfied.\n   * Scheduling the same jobId again replaces the previous run function.\n   */\n  schedule({ contextId, jobId, dependencies, run }: ScheduleOptions): void {\n    if (typeof contextId === `undefined`) {\n      run()\n      return\n    }\n\n    const context = this.getOrCreateContext(contextId)\n\n    // If this is a new job, add it to the queue\n    if (!context.jobs.has(jobId)) {\n      context.queue.push(jobId)\n    }\n\n    // Store or replace the run function\n    context.jobs.set(jobId, run)\n\n    // Update dependencies\n    if (dependencies) {\n      const depSet = new Set<unknown>(dependencies)\n      depSet.delete(jobId)\n      context.dependencies.set(jobId, depSet)\n    } else if (!context.dependencies.has(jobId)) {\n      context.dependencies.set(jobId, new Set())\n    }\n\n    // Clear completion status since we're rescheduling\n    context.completed.delete(jobId)\n  }\n\n  /**\n   * Flush all queued work for a context. Jobs with unmet dependencies are retried.\n   * Throws if a pass completes without running any job (dependency cycle).\n   */\n  flush(contextId: SchedulerContextId): void {\n    const context = this.contexts.get(contextId)\n    if (!context) return\n\n    const { queue, jobs, dependencies, completed } = context\n\n    while (queue.length > 0) {\n      let ranThisPass = false\n      const jobsThisPass = queue.length\n\n      for (let i = 0; i < jobsThisPass; i++) {\n        const jobId = queue.shift()!\n        const run = jobs.get(jobId)\n        if (!run) {\n          dependencies.delete(jobId)\n          completed.delete(jobId)\n          continue\n        }\n\n        const deps = dependencies.get(jobId)\n        let ready = !deps\n        if (deps) {\n          ready = true\n          for (const dep of deps) {\n            if (dep !== jobId && !completed.has(dep)) {\n              ready = false\n              break\n            }\n          }\n        }\n\n        if (ready) {\n          jobs.delete(jobId)\n          dependencies.delete(jobId)\n          // Run the job. If it throws, we don't mark it complete, allowing the\n          // error to propagate while maintaining scheduler state consistency.\n          run()\n          completed.add(jobId)\n          ranThisPass = true\n        } else {\n          queue.push(jobId)\n        }\n      }\n\n      if (!ranThisPass) {\n        throw new Error(\n          `Scheduler detected unresolved dependencies for context ${String(\n            contextId\n          )}.`\n        )\n      }\n    }\n\n    this.contexts.delete(contextId)\n  }\n\n  /**\n   * Flush all contexts with pending work. Useful during tear-down.\n   */\n  flushAll(): void {\n    for (const contextId of Array.from(this.contexts.keys())) {\n      this.flush(contextId)\n    }\n  }\n\n  /** Clear all scheduled jobs for a context. */\n  clear(contextId: SchedulerContextId): void {\n    this.contexts.delete(contextId)\n    // Notify listeners that this context was cleared\n    this.clearListeners.forEach((listener) => listener(contextId))\n  }\n\n  /** Register a listener to be notified when a context is cleared. */\n  onClear(listener: (contextId: SchedulerContextId) => void): () => void {\n    this.clearListeners.add(listener)\n    return () => this.clearListeners.delete(listener)\n  }\n\n  /** Check if a context has pending jobs. */\n  hasPendingJobs(contextId: SchedulerContextId): boolean {\n    const context = this.contexts.get(contextId)\n    return !!context && context.jobs.size > 0\n  }\n\n  /** Remove a single job from a context and clean up its dependencies. */\n  clearJob(contextId: SchedulerContextId, jobId: unknown): void {\n    const context = this.contexts.get(contextId)\n    if (!context) return\n\n    context.jobs.delete(jobId)\n    context.dependencies.delete(jobId)\n    context.completed.delete(jobId)\n    context.queue = context.queue.filter((id) => id !== jobId)\n\n    if (context.jobs.size === 0) {\n      this.contexts.delete(contextId)\n    }\n  }\n}\n\nexport const transactionScopedScheduler = new Scheduler()\n"],"names":[],"mappings":";;AAoCO,MAAM,UAAU;AAAA,EAAhB,cAAA;AACL,SAAQ,+BAAe,IAAA;AACvB,SAAQ,qCAAqB,IAAA;AAAA,EAA6C;AAAA;AAAA;AAAA;AAAA,EAKlE,mBACN,WACuB;AACvB,QAAI,UAAU,KAAK,SAAS,IAAI,SAAS;AACzC,QAAI,CAAC,SAAS;AACZ,gBAAU;AAAA,QACR,OAAO,CAAA;AAAA,QACP,0BAAU,IAAA;AAAA,QACV,kCAAkB,IAAA;AAAA,QAClB,+BAAe,IAAA;AAAA,MAAI;AAErB,WAAK,SAAS,IAAI,WAAW,OAAO;AAAA,IACtC;AACA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,SAAS,EAAE,WAAW,OAAO,cAAc,OAA8B;AACvE,QAAI,OAAO,cAAc,aAAa;AACpC,UAAA;AACA;AAAA,IACF;AAEA,UAAM,UAAU,KAAK,mBAAmB,SAAS;AAGjD,QAAI,CAAC,QAAQ,KAAK,IAAI,KAAK,GAAG;AAC5B,cAAQ,MAAM,KAAK,KAAK;AAAA,IAC1B;AAGA,YAAQ,KAAK,IAAI,OAAO,GAAG;AAG3B,QAAI,cAAc;AAChB,YAAM,SAAS,IAAI,IAAa,YAAY;AAC5C,aAAO,OAAO,KAAK;AACnB,cAAQ,aAAa,IAAI,OAAO,MAAM;AAAA,IACxC,WAAW,CAAC,QAAQ,aAAa,IAAI,KAAK,GAAG;AAC3C,cAAQ,aAAa,IAAI,OAAO,oBAAI,KAAK;AAAA,IAC3C;AAGA,YAAQ,UAAU,OAAO,KAAK;AAAA,EAChC;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,WAAqC;AACzC,UAAM,UAAU,KAAK,SAAS,IAAI,SAAS;AAC3C,QAAI,CAAC,QAAS;AAEd,UAAM,EAAE,OAAO,MAAM,cAAc,cAAc;AAEjD,WAAO,MAAM,SAAS,GAAG;AACvB,UAAI,cAAc;AAClB,YAAM,eAAe,MAAM;AAE3B,eAAS,IAAI,GAAG,IAAI,cAAc,KAAK;AACrC,cAAM,QAAQ,MAAM,MAAA;AACpB,cAAM,MAAM,KAAK,IAAI,KAAK;AAC1B,YAAI,CAAC,KAAK;AACR,uBAAa,OAAO,KAAK;AACzB,oBAAU,OAAO,KAAK;AACtB;AAAA,QACF;AAEA,cAAM,OAAO,aAAa,IAAI,KAAK;AACnC,YAAI,QAAQ,CAAC;AACb,YAAI,MAAM;AACR,kBAAQ;AACR,qBAAW,OAAO,MAAM;AACtB,gBAAI,QAAQ,SAAS,CAAC,UAAU,IAAI,GAAG,GAAG;AACxC,sBAAQ;AACR;AAAA,YACF;AAAA,UACF;AAAA,QACF;AAEA,YAAI,OAAO;AACT,eAAK,OAAO,KAAK;AACjB,uBAAa,OAAO,KAAK;AAGzB,cAAA;AACA,oBAAU,IAAI,KAAK;AACnB,wBAAc;AAAA,QAChB,OAAO;AACL,gBAAM,KAAK,KAAK;AAAA,QAClB;AAAA,MACF;AAEA,UAAI,CAAC,aAAa;AAChB,cAAM,IAAI;AAAA,UACR,0DAA0D;AAAA,YACxD;AAAA,UAAA,CACD;AAAA,QAAA;AAAA,MAEL;AAAA,IACF;AAEA,SAAK,SAAS,OAAO,SAAS;AAAA,EAChC;AAAA;AAAA;AAAA;AAAA,EAKA,WAAiB;AACf,eAAW,aAAa,MAAM,KAAK,KAAK,SAAS,KAAA,CAAM,GAAG;AACxD,WAAK,MAAM,SAAS;AAAA,IACtB;AAAA,EACF;AAAA;AAAA,EAGA,MAAM,WAAqC;AACzC,SAAK,SAAS,OAAO,SAAS;AAE9B,SAAK,eAAe,QAAQ,CAAC,aAAa,SAAS,SAAS,CAAC;AAAA,EAC/D;AAAA;AAAA,EAGA,QAAQ,UAA+D;AACrE,SAAK,eAAe,IAAI,QAAQ;AAChC,WAAO,MAAM,KAAK,eAAe,OAAO,QAAQ;AAAA,EAClD;AAAA;AAAA,EAGA,eAAe,WAAwC;AACrD,UAAM,UAAU,KAAK,SAAS,IAAI,SAAS;AAC3C,WAAO,CAAC,CAAC,WAAW,QAAQ,KAAK,OAAO;AAAA,EAC1C;AAAA;AAAA,EAGA,SAAS,WAA+B,OAAsB;AAC5D,UAAM,UAAU,KAAK,SAAS,IAAI,SAAS;AAC3C,QAAI,CAAC,QAAS;AAEd,YAAQ,KAAK,OAAO,KAAK;AACzB,YAAQ,aAAa,OAAO,KAAK;AACjC,YAAQ,UAAU,OAAO,KAAK;AAC9B,YAAQ,QAAQ,QAAQ,MAAM,OAAO,CAAC,OAAO,OAAO,KAAK;AAEzD,QAAI,QAAQ,KAAK,SAAS,GAAG;AAC3B,WAAK,SAAS,OAAO,SAAS;AAAA,IAChC;AAAA,EACF;AACF;AAEO,MAAM,6BAA6B,IAAI,UAAA;;;"}

package/dist/cjs/scheduler.d.cts

@@ -0,0 +1,56 @@
+/**
+ * Identifier used to scope scheduled work. Maps to a transaction id for live queries.
+ */
+export type SchedulerContextId = string | symbol;
+/**
+ * Options for {@link Scheduler.schedule}. Jobs are identified by `jobId` within a context
+ * and may declare dependencies.
+ */
+interface ScheduleOptions {
+    contextId?: SchedulerContextId;
+    jobId: unknown;
+    dependencies?: Iterable<unknown>;
+    run: () => void;
+}
+/**
+ * Scoped scheduler that coalesces work by context and job.
+ *
+ * - **context** (e.g. transaction id) defines the batching boundary; work is queued until flushed.
+ * - **job id** deduplicates work within a context; scheduling the same job replaces the previous run function.
+ * - Without a context id, work executes immediately.
+ *
+ * Callers manage their own state; the scheduler only orchestrates execution order.
+ */
+export declare class Scheduler {
+    private contexts;
+    private clearListeners;
+    /**
+     * Get or create the state bucket for a context.
+     */
+    private getOrCreateContext;
+    /**
+     * Schedule work. Without a context id, executes immediately.
+     * Otherwise queues the job to be flushed once dependencies are satisfied.
+     * Scheduling the same jobId again replaces the previous run function.
+     */
+    schedule({ contextId, jobId, dependencies, run }: ScheduleOptions): void;
+    /**
+     * Flush all queued work for a context. Jobs with unmet dependencies are retried.
+     * Throws if a pass completes without running any job (dependency cycle).
+     */
+    flush(contextId: SchedulerContextId): void;
+    /**
+     * Flush all contexts with pending work. Useful during tear-down.
+     */
+    flushAll(): void;
+    /** Clear all scheduled jobs for a context. */
+    clear(contextId: SchedulerContextId): void;
+    /** Register a listener to be notified when a context is cleared. */
+    onClear(listener: (contextId: SchedulerContextId) => void): () => void;
+    /** Check if a context has pending jobs. */
+    hasPendingJobs(contextId: SchedulerContextId): boolean;
+    /** Remove a single job from a context and clean up its dependencies. */
+    clearJob(contextId: SchedulerContextId, jobId: unknown): void;
+}
+export declare const transactionScopedScheduler: Scheduler;
+export {};

package/dist/cjs/transactions.cjs

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const deferred = require("./deferred.cjs");
 const errors = require("./errors.cjs");
+const scheduler = require("./scheduler.cjs");
 const transactions = [];
 let transactionStack = [];
 let sequenceNumber = 0;
@@ -63,10 +64,15 @@ function getActiveTransaction() {
   }
 }
 function registerTransaction(tx) {
+  scheduler.transactionScopedScheduler.clear(tx.id);
   transactionStack.push(tx);
 }
 function unregisterTransaction(tx) {
-  transactionStack = transactionStack.filter((t) => t.id !== tx.id);
+  try {
+    scheduler.transactionScopedScheduler.flush(tx.id);
+  } finally {
+    transactionStack = transactionStack.filter((t) => t.id !== tx.id);
+  }
 }
 function removeFromPendingList(tx) {
   const index = transactions.findIndex((t) => t.id === tx.id);

package/dist/cjs/transactions.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"transactions.cjs","sources":["../../src/transactions.ts"],"sourcesContent":["import { createDeferred } from \"./deferred\"\nimport {\n  MissingMutationFunctionError,\n  TransactionAlreadyCompletedRollbackError,\n  TransactionNotPendingCommitError,\n  TransactionNotPendingMutateError,\n} from \"./errors\"\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  transactionStack.push(tx)\n}\n\nfunction unregisterTransaction(tx: Transaction<any>) {\n  transactionStack = transactionStack.filter((t) => t.id !== tx.id)\n}\n\nfunction removeFromPendingList(tx: Transaction<any>) {\n  const index = transactions.findIndex((t) => t.id === tx.id)\n  if (index !== -1) {\n    transactions.splice(index, 1)\n  }\n}\n\nclass Transaction<T extends object = Record<string, unknown>> {\n  public id: string\n  public state: TransactionState\n  public mutationFn: MutationFn<T>\n  public mutations: Array<PendingMutation<T>>\n  public isPersisted: Deferred<Transaction<T>>\n  public autoCommit: boolean\n  public createdAt: Date\n  public sequenceNumber: number\n  public metadata: Record<string, unknown>\n  public error?: {\n    message: string\n    error: Error\n  }\n\n  constructor(config: TransactionConfig<T>) {\n    if (typeof config.mutationFn === `undefined`) {\n      throw 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":["MissingMutationFunctionError","createDeferred","TransactionNotPendingMutateError","TransactionAlreadyCompletedRollbackError","TransactionNotPendingCommitError"],"mappings":"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"}
+{"version":3,"file":"transactions.cjs","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":["transactionScopedScheduler","MissingMutationFunctionError","createDeferred","TransactionNotPendingMutateError","TransactionAlreadyCompletedRollbackError","TransactionNotPendingCommitError"],"mappings":"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"}

package/dist/cjs/types.d.cts

@@ -3,6 +3,7 @@ import { Collection } from './collection/index.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Transaction } from './transactions.cjs';
 import { BasicExpression, OrderBy } from './query/ir.js';
+import { EventEmitter } from './event-emitter.js';
 /**
  * Helper type to extract the output type from a standard schema
  *
@@ -92,15 +93,74 @@ type Value<TExtensions = never> = string | number | boolean | bigint | null | TE
 };
 export type Row<TExtensions = never> = Record<string, Value<TExtensions>>;
 export type OperationType = `insert` | `update` | `delete`;
-export type OnLoadMoreOptions = {
+/**
+ * Subscription status values
+ */
+export type SubscriptionStatus = `ready` | `loadingSubset`;
+/**
+ * Event emitted when subscription status changes
+ */
+export interface SubscriptionStatusChangeEvent {
+    type: `status:change`;
+    subscription: Subscription;
+    previousStatus: SubscriptionStatus;
+    status: SubscriptionStatus;
+}
+/**
+ * Event emitted when subscription status changes to a specific status
+ */
+export interface SubscriptionStatusEvent<T extends SubscriptionStatus> {
+    type: `status:${T}`;
+    subscription: Subscription;
+    previousStatus: SubscriptionStatus;
+    status: T;
+}
+/**
+ * Event emitted when subscription is unsubscribed
+ */
+export interface SubscriptionUnsubscribedEvent {
+    type: `unsubscribed`;
+    subscription: Subscription;
+}
+/**
+ * All subscription events
+ */
+export type SubscriptionEvents = {
+    "status:change": SubscriptionStatusChangeEvent;
+    "status:ready": SubscriptionStatusEvent<`ready`>;
+    "status:loadingSubset": SubscriptionStatusEvent<`loadingSubset`>;
+    unsubscribed: SubscriptionUnsubscribedEvent;
+};
+/**
+ * Public interface for a collection subscription
+ * Used by sync implementations to track subscription lifecycle
+ */
+export interface Subscription extends EventEmitter<SubscriptionEvents> {
+    /** Current status of the subscription */
+    readonly status: SubscriptionStatus;
+}
+export type LoadSubsetOptions = {
+    /** The where expression to filter the data */
     where?: BasicExpression<boolean>;
+    /** The order by clause to sort the data */
     orderBy?: OrderBy;
+    /** The limit of the data to load */
     limit?: number;
+    /**
+     * The subscription that triggered the load.
+     * Advanced sync implementations can use this for:
+     * - LRU caching keyed by subscription
+     * - Reference counting to track active subscriptions
+     * - Subscribing to subscription events (e.g., finalization/unsubscribe)
+     * @optional Available when called from CollectionSubscription, may be undefined for direct calls
+     */
+    subscription?: Subscription;
 };
+export type LoadSubsetFn = (options: LoadSubsetOptions) => true | Promise<void>;
 export type CleanupFn = () => void;
 export type SyncConfigRes = {
     cleanup?: CleanupFn;
-    onLoadMore?: (options: OnLoadMoreOptions) => void | Promise<void>;
+    loadSubset?: LoadSubsetFn;
 };
 export interface SyncConfig<T extends object = Record<string, unknown>, TKey extends string | number = string | number> {
     sync: (params: {
@@ -161,21 +221,21 @@ export interface InsertConfig {
     /** Whether to apply optimistic updates immediately. Defaults to true. */
     optimistic?: boolean;
 }
-export type UpdateMutationFnParams<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = Record<string, Fn>> = {
+export type UpdateMutationFnParams<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord> = {
     transaction: TransactionWithMutations<T, `update`>;
     collection: Collection<T, TKey, TUtils>;
 };
-export type InsertMutationFnParams<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = Record<string, Fn>> = {
+export type InsertMutationFnParams<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord> = {
     transaction: TransactionWithMutations<T, `insert`>;
     collection: Collection<T, TKey, TUtils>;
 };
-export type DeleteMutationFnParams<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = Record<string, Fn>> = {
+export type DeleteMutationFnParams<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord> = {
     transaction: TransactionWithMutations<T, `delete`>;
     collection: Collection<T, TKey, TUtils>;
 };
-export type InsertMutationFn<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = Record<string, Fn>, TReturn = any> = (params: InsertMutationFnParams<T, TKey, TUtils>) => Promise<TReturn>;
-export type UpdateMutationFn<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = Record<string, Fn>, TReturn = any> = (params: UpdateMutationFnParams<T, TKey, TUtils>) => Promise<TReturn>;
-export type DeleteMutationFn<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = Record<string, Fn>, TReturn = any> = (params: DeleteMutationFnParams<T, TKey, TUtils>) => Promise<TReturn>;
+export type InsertMutationFn<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord, TReturn = any> = (params: InsertMutationFnParams<T, TKey, TUtils>) => Promise<TReturn>;
+export type UpdateMutationFn<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord, TReturn = any> = (params: UpdateMutationFnParams<T, TKey, TUtils>) => Promise<TReturn>;
+export type DeleteMutationFn<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord, TReturn = any> = (params: DeleteMutationFnParams<T, TKey, TUtils>) => Promise<TReturn>;
 /**
  * Collection status values for lifecycle management
  * @example
@@ -202,7 +262,8 @@ export type CollectionStatus =
  | `error`
 /** Collection has been cleaned up and resources freed */
  | `cleaned-up`;
-export interface BaseCollectionConfig<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TSchema extends StandardSchemaV1 = never, TUtils extends UtilsRecord = Record<string, Fn>, TReturn = any> {
+export type SyncMode = `eager` | `on-demand`;
+export interface BaseCollectionConfig<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TSchema extends StandardSchemaV1 = never, TUtils extends UtilsRecord = UtilsRecord, TReturn = any> {
     id?: string;
     schema?: TSchema;
     /**
@@ -251,6 +312,15 @@ export interface BaseCollectionConfig<T extends object = Record<string, unknown>
      * compare: (x, y) => x.createdAt.getTime() - y.createdAt.getTime()
      */
     compare?: (x: T, y: T) => number;
+    /**
+     * The mode of sync to use for the collection.
+     * @default `eager`
+     * @description
+     * - `eager`: syncs all data immediately on preload
+     * - `on-demand`: syncs data in incremental snapshots when the collection is queried
+     * The exact implementation of the sync mode is up to the sync implementation.
+     */
+    syncMode?: SyncMode;
     /**
      * Optional asynchronous handler function called before an insert operation
      * @param params Object containing transaction and collection information
@@ -379,8 +449,9 @@ export interface BaseCollectionConfig<T extends object = Record<string, unknown>
      * }
      */
     onDelete?: DeleteMutationFn<T, TKey, TUtils, TReturn>;
+    utils?: TUtils;
 }
-export interface CollectionConfig<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TSchema extends StandardSchemaV1 = never> extends BaseCollectionConfig<T, TKey, TSchema> {
+export interface CollectionConfig<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TSchema extends StandardSchemaV1 = never, TUtils extends UtilsRecord = UtilsRecord> extends BaseCollectionConfig<T, TKey, TSchema, TUtils> {
     sync: SyncConfig<T, TKey>;
 }
 export type SingleResult = {
@@ -395,7 +466,7 @@ export type MaybeSingleResult = {
      */
     singleResult?: true;
 };
-export type CollectionConfigSingleRowOption<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TSchema extends StandardSchemaV1 = never> = CollectionConfig<T, TKey, TSchema> & MaybeSingleResult;
+export type CollectionConfigSingleRowOption<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TSchema extends StandardSchemaV1 = never, TUtils extends UtilsRecord = {}> = CollectionConfig<T, TKey, TSchema, TUtils> & MaybeSingleResult;
 export type ChangesPayload<T extends object = Record<string, unknown>> = Array<ChangeMessage<T>>;
 /**
  * An input row from a collection

package/dist/esm/collection/events.d.ts

@@ -1,3 +1,4 @@
+import { EventEmitter } from '../event-emitter.js';
 import { Collection } from './index.js';
 import { CollectionStatus } from '../types.js';
 /**
@@ -27,25 +28,35 @@ export interface CollectionSubscribersChangeEvent {
     previousSubscriberCount: number;
     subscriberCount: number;
 }
+/**
+ * Event emitted when the collection's loading more state changes
+ */
+export interface CollectionLoadingSubsetChangeEvent {
+    type: `loadingSubset:change`;
+    collection: Collection<any, any, any, any, any>;
+    isLoadingSubset: boolean;
+    previousIsLoadingSubset: boolean;
+    loadingSubsetTransition: `start` | `end`;
+}
 export type AllCollectionEvents = {
     "status:change": CollectionStatusChangeEvent;
     "subscribers:change": CollectionSubscribersChangeEvent;
+    "loadingSubset:change": CollectionLoadingSubsetChangeEvent;
 } & {
     [K in CollectionStatus as `status:${K}`]: CollectionStatusEvent<K>;
 };
-export type CollectionEvent = AllCollectionEvents[keyof AllCollectionEvents] | CollectionStatusChangeEvent | CollectionSubscribersChangeEvent;
+export type CollectionEvent = AllCollectionEvents[keyof AllCollectionEvents] | CollectionStatusChangeEvent | CollectionSubscribersChangeEvent | CollectionLoadingSubsetChangeEvent;
 export type CollectionEventHandler<T extends keyof AllCollectionEvents> = (event: AllCollectionEvents[T]) => void;
-export declare class CollectionEventsManager {
+export declare class CollectionEventsManager extends EventEmitter<AllCollectionEvents> {
     private collection;
-    private listeners;
     constructor();
     setDeps(deps: {
         collection: Collection<any, any, any, any, any>;
     }): void;
-    on<T extends keyof AllCollectionEvents>(event: T, callback: CollectionEventHandler<T>): () => void;
-    once<T extends keyof AllCollectionEvents>(event: T, callback: CollectionEventHandler<T>): () => void;
-    off<T extends keyof AllCollectionEvents>(event: T, callback: CollectionEventHandler<T>): void;
-    waitFor<T extends keyof AllCollectionEvents>(event: T, timeout?: number): Promise<AllCollectionEvents[T]>;
+    /**
+     * Emit an event to all listeners
+     * Public API for emitting collection events
+     */
     emit<T extends keyof AllCollectionEvents>(event: T, eventPayload: AllCollectionEvents[T]): void;
     emitStatusChange<T extends CollectionStatus>(status: T, previousStatus: CollectionStatus): void;
     emitSubscribersChange(subscriberCount: number, previousSubscriberCount: number): void;

package/dist/esm/collection/events.js

@@ -1,59 +1,17 @@
-class CollectionEventsManager {
+import { EventEmitter } from "../event-emitter.js";
+class CollectionEventsManager extends EventEmitter {
   constructor() {
-    this.listeners = /* @__PURE__ */ new Map();
+    super();
   }
   setDeps(deps) {
     this.collection = deps.collection;
   }
-  on(event, callback) {
-    if (!this.listeners.has(event)) {
-      this.listeners.set(event, /* @__PURE__ */ new Set());
-    }
-    this.listeners.get(event).add(callback);
-    return () => {
-      this.listeners.get(event)?.delete(callback);
-    };
-  }
-  once(event, callback) {
-    const unsubscribe = this.on(event, (eventPayload) => {
-      callback(eventPayload);
-      unsubscribe();
-    });
-    return unsubscribe;
-  }
-  off(event, callback) {
-    this.listeners.get(event)?.delete(callback);
-  }
-  waitFor(event, timeout) {
-    return new Promise((resolve, reject) => {
-      let timeoutId;
-      const unsubscribe = this.on(event, (eventPayload) => {
-        if (timeoutId) {
-          clearTimeout(timeoutId);
-          timeoutId = void 0;
-        }
-        resolve(eventPayload);
-        unsubscribe();
-      });
-      if (timeout) {
-        timeoutId = setTimeout(() => {
-          timeoutId = void 0;
-          unsubscribe();
-          reject(new Error(`Timeout waiting for event ${event}`));
-        }, timeout);
-      }
-    });
-  }
+  /**
+   * Emit an event to all listeners
+   * Public API for emitting collection events
+   */
   emit(event, eventPayload) {
-    this.listeners.get(event)?.forEach((listener) => {
-      try {
-        listener(eventPayload);
-      } catch (error) {
-        queueMicrotask(() => {
-          throw error;
-        });
-      }
-    });
+    this.emitInner(event, eventPayload);
   }
   emitStatusChange(status, previousStatus) {
     this.emit(`status:change`, {
@@ -79,7 +37,7 @@ class CollectionEventsManager {
     });
   }
   cleanup() {
-    this.listeners.clear();
+    this.clearListeners();
   }
 }
 export {