@tanstack/db 0.4.7 → 0.4.9

package/src/scheduler.ts

@@ -0,0 +1,198 @@
+/**
+ * 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
+}
+
+/**
+ * State per context. Queue preserves order, jobs hold run functions, dependencies track
+ * prerequisites, and completed records which jobs have run during the current flush.
+ */
+interface SchedulerContextState {
+  queue: Array<unknown>
+  jobs: Map<unknown, () => void>
+  dependencies: Map<unknown, Set<unknown>>
+  completed: Set<unknown>
+}
+
+/**
+ * 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 class Scheduler {
+  private contexts = new Map<SchedulerContextId, SchedulerContextState>()
+  private clearListeners = new Set<(contextId: SchedulerContextId) => void>()
+
+  /**
+   * Get or create the state bucket for a context.
+   */
+  private getOrCreateContext(
+    contextId: SchedulerContextId
+  ): SchedulerContextState {
+    let context = this.contexts.get(contextId)
+    if (!context) {
+      context = {
+        queue: [],
+        jobs: new Map(),
+        dependencies: new Map(),
+        completed: 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 }: ScheduleOptions): void {
+    if (typeof contextId === `undefined`) {
+      run()
+      return
+    }
+
+    const context = this.getOrCreateContext(contextId)
+
+    // If this is a new job, add it to the queue
+    if (!context.jobs.has(jobId)) {
+      context.queue.push(jobId)
+    }
+
+    // Store or replace the run function
+    context.jobs.set(jobId, run)
+
+    // Update dependencies
+    if (dependencies) {
+      const depSet = new Set<unknown>(dependencies)
+      depSet.delete(jobId)
+      context.dependencies.set(jobId, depSet)
+    } else if (!context.dependencies.has(jobId)) {
+      context.dependencies.set(jobId, new Set())
+    }
+
+    // Clear completion status since we're rescheduling
+    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: SchedulerContextId): void {
+    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 the job. If it throws, we don't mark it complete, allowing the
+          // error to propagate while maintaining scheduler state consistency.
+          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(): void {
+    for (const contextId of Array.from(this.contexts.keys())) {
+      this.flush(contextId)
+    }
+  }
+
+  /** Clear all scheduled jobs for a context. */
+  clear(contextId: SchedulerContextId): void {
+    this.contexts.delete(contextId)
+    // Notify listeners that this context was cleared
+    this.clearListeners.forEach((listener) => listener(contextId))
+  }
+
+  /** Register a listener to be notified when a context is cleared. */
+  onClear(listener: (contextId: SchedulerContextId) => void): () => void {
+    this.clearListeners.add(listener)
+    return () => this.clearListeners.delete(listener)
+  }
+
+  /** Check if a context has pending jobs. */
+  hasPendingJobs(contextId: SchedulerContextId): boolean {
+    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: SchedulerContextId, jobId: unknown): void {
+    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)
+    }
+  }
+}
+
+export const transactionScopedScheduler = new Scheduler()

package/src/transactions.ts

@@ -5,6 +5,7 @@ import {
   TransactionNotPendingCommitError,
   TransactionNotPendingMutateError,
 } from "./errors"
+import { transactionScopedScheduler } from "./scheduler.js"
 import type { Deferred } from "./deferred"
 import type {
   MutationFn,
@@ -179,11 +180,21 @@ export function getActiveTransaction(): Transaction | undefined {
 }
 
 function registerTransaction(tx: Transaction<any>) {
+  // Clear any stale work that may have been left behind if a previous mutate
+  // scope aborted before we could flush.
+  transactionScopedScheduler.clear(tx.id)
   transactionStack.push(tx)
 }
 
 function unregisterTransaction(tx: Transaction<any>) {
-  transactionStack = transactionStack.filter((t) => t.id !== tx.id)
+  // Always flush pending work for this transaction before removing it from
+  // the ambient stack – this runs even if the mutate callback throws.
+  // If flush throws (e.g., due to a job error), we still clean up the stack.
+  try {
+    transactionScopedScheduler.flush(tx.id)
+  } finally {
+    transactionStack = transactionStack.filter((t) => t.id !== tx.id)
+  }
 }
 
 function removeFromPendingList(tx: Transaction<any>) {

package/src/types.ts

@@ -298,17 +298,15 @@ export type DeleteMutationFn<
  *
  * @example
  * // Status transitions
- * // idle → loading → initialCommit → ready
+ * // idle → loading → ready (when markReady() is called)
  * // Any status can transition to → error or cleaned-up
  */
 export type CollectionStatus =
   /** Collection is created but sync hasn't started yet (when startSync config is false) */
   | `idle`
-  /** Sync has started but hasn't received the first commit yet */
+  /** Sync has started and is loading data */
   | `loading`
-  /** Collection is in the process of committing its first transaction */
-  | `initialCommit`
-  /** Collection has received at least one commit and is ready for use */
+  /** Collection has been explicitly marked ready via markReady() */
   | `ready`
   /** An error occurred during sync initialization */
   | `error`