@tanstack/db 0.5.3 → 0.5.4

package/dist/esm/strategies/queueStrategy.js

@@ -1,14 +1,16 @@
-import { AsyncQueuer } from "@tanstack/pacer/async-queuer";
+import { LiteQueuer } from "@tanstack/pacer-lite/lite-queuer";
 function queueStrategy(options) {
-  const queuer = new AsyncQueuer(
-    async (fn) => {
-      const transaction = fn();
-      await transaction.isPersisted.promise;
+  let processingChain = Promise.resolve();
+  const queuer = new LiteQueuer(
+    (fn) => {
+      processingChain = processingChain.then(async () => {
+        const transaction = fn();
+        await transaction.isPersisted.promise;
+      }).catch(() => {
+      });
     },
     {
-      concurrency: 1,
-      // Process one at a time to ensure serialization
-      wait: options?.wait,
+      wait: options?.wait ?? 0,
       maxSize: options?.maxSize,
       addItemsTo: options?.addItemsTo ?? `back`,
       // Default FIFO: add to back

package/dist/esm/strategies/queueStrategy.js.map

@@ -1 +1 @@
-{"version":3,"file":"queueStrategy.js","sources":["../../../src/strategies/queueStrategy.ts"],"sourcesContent":["import { AsyncQueuer } from \"@tanstack/pacer/async-queuer\"\nimport type { QueueStrategy, QueueStrategyOptions } from \"./types\"\nimport type { Transaction } from \"../transactions\"\n\n/**\n * Creates a queue strategy that processes all mutations in order with proper serialization.\n *\n * Unlike other strategies that may drop executions, queue ensures every\n * mutation is processed sequentially. Each transaction commit completes before\n * the next one starts. Useful when data consistency is critical and\n * every operation must complete in order.\n *\n * @param options - Configuration for queue behavior (FIFO/LIFO, timing, size limits)\n * @returns A queue strategy instance\n *\n * @example\n * ```ts\n * // FIFO queue - process in order received\n * const mutate = usePacedMutations({\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 *\n * @example\n * ```ts\n * // LIFO queue - process most recent first\n * const mutate = usePacedMutations({\n *   mutationFn: async ({ transaction }) => {\n *     await api.save(transaction.mutations)\n *   },\n *   strategy: queueStrategy({\n *     wait: 200,\n *     addItemsTo: 'back',\n *     getItemsFrom: 'back'\n *   })\n * })\n * ```\n */\nexport function queueStrategy(options?: QueueStrategyOptions): QueueStrategy {\n  const queuer = new AsyncQueuer<() => Transaction>(\n    async (fn) => {\n      const transaction = fn()\n      // Wait for the transaction to be persisted before processing next item\n      // Note: fn() already calls commit(), we just wait for it to complete\n      await transaction.isPersisted.promise\n    },\n    {\n      concurrency: 1, // Process one at a time to ensure serialization\n      wait: options?.wait,\n      maxSize: options?.maxSize,\n      addItemsTo: options?.addItemsTo ?? `back`, // Default FIFO: add to back\n      getItemsFrom: options?.getItemsFrom ?? `front`, // Default FIFO: get from front\n      started: true, // Start processing immediately\n    }\n  )\n\n  return {\n    _type: `queue`,\n    options,\n    execute: <T extends object = Record<string, unknown>>(\n      fn: () => Transaction<T>\n    ) => {\n      // Add the transaction-creating function to the queue\n      queuer.addItem(fn as () => Transaction)\n    },\n    cleanup: () => {\n      queuer.stop()\n      queuer.clear()\n    },\n  }\n}\n"],"names":[],"mappings":";AA6CO,SAAS,cAAc,SAA+C;AAC3E,QAAM,SAAS,IAAI;AAAA,IACjB,OAAO,OAAO;AACZ,YAAM,cAAc,GAAA;AAGpB,YAAM,YAAY,YAAY;AAAA,IAChC;AAAA,IACA;AAAA,MACE,aAAa;AAAA;AAAA,MACb,MAAM,SAAS;AAAA,MACf,SAAS,SAAS;AAAA,MAClB,YAAY,SAAS,cAAc;AAAA;AAAA,MACnC,cAAc,SAAS,gBAAgB;AAAA;AAAA,MACvC,SAAS;AAAA;AAAA,IAAA;AAAA,EACX;AAGF,SAAO;AAAA,IACL,OAAO;AAAA,IACP;AAAA,IACA,SAAS,CACP,OACG;AAEH,aAAO,QAAQ,EAAuB;AAAA,IACxC;AAAA,IACA,SAAS,MAAM;AACb,aAAO,KAAA;AACP,aAAO,MAAA;AAAA,IACT;AAAA,EAAA;AAEJ;"}
+{"version":3,"file":"queueStrategy.js","sources":["../../../src/strategies/queueStrategy.ts"],"sourcesContent":["import { LiteQueuer } from \"@tanstack/pacer-lite/lite-queuer\"\nimport type { QueueStrategy, QueueStrategyOptions } from \"./types\"\nimport type { Transaction } from \"../transactions\"\n\n/**\n * Creates a queue strategy that processes all mutations in order with proper serialization.\n *\n * Unlike other strategies that may drop executions, queue ensures every\n * mutation is processed sequentially. Each transaction commit completes before\n * the next one starts. Useful when data consistency is critical and\n * every operation must complete in order.\n *\n * @param options - Configuration for queue behavior (FIFO/LIFO, timing, size limits)\n * @returns A queue strategy instance\n *\n * @example\n * ```ts\n * // FIFO queue - process in order received\n * const mutate = usePacedMutations({\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 *\n * @example\n * ```ts\n * // LIFO queue - process most recent first\n * const mutate = usePacedMutations({\n *   mutationFn: async ({ transaction }) => {\n *     await api.save(transaction.mutations)\n *   },\n *   strategy: queueStrategy({\n *     wait: 200,\n *     addItemsTo: 'back',\n *     getItemsFrom: 'back'\n *   })\n * })\n * ```\n */\nexport function queueStrategy(options?: QueueStrategyOptions): QueueStrategy {\n  // Manual promise chaining to ensure async serialization\n  // LiteQueuer (unlike AsyncQueuer from @tanstack/pacer) lacks built-in async queue\n  // primitives and concurrency control. We compensate by manually chaining promises\n  // to ensure each transaction completes before the next one starts.\n  let processingChain = Promise.resolve()\n\n  const queuer = new LiteQueuer<() => Transaction>(\n    (fn) => {\n      // Chain each transaction to the previous one's completion\n      processingChain = processingChain\n        .then(async () => {\n          const transaction = fn()\n          // Wait for the transaction to be persisted before processing next item\n          await transaction.isPersisted.promise\n        })\n        .catch(() => {\n          // Errors are handled via transaction.isPersisted.promise and surfaced there.\n          // This catch prevents unhandled promise rejections from breaking the chain,\n          // ensuring subsequent transactions can still execute even if one fails.\n        })\n    },\n    {\n      wait: options?.wait ?? 0,\n      maxSize: options?.maxSize,\n      addItemsTo: options?.addItemsTo ?? `back`, // Default FIFO: add to back\n      getItemsFrom: options?.getItemsFrom ?? `front`, // Default FIFO: get from front\n      started: true, // Start processing immediately\n    }\n  )\n\n  return {\n    _type: `queue`,\n    options,\n    execute: <T extends object = Record<string, unknown>>(\n      fn: () => Transaction<T>\n    ) => {\n      // Add the transaction-creating function to the queue\n      queuer.addItem(fn as () => Transaction)\n    },\n    cleanup: () => {\n      queuer.stop()\n      queuer.clear()\n    },\n  }\n}\n"],"names":[],"mappings":";AA6CO,SAAS,cAAc,SAA+C;AAK3E,MAAI,kBAAkB,QAAQ,QAAA;AAE9B,QAAM,SAAS,IAAI;AAAA,IACjB,CAAC,OAAO;AAEN,wBAAkB,gBACf,KAAK,YAAY;AAChB,cAAM,cAAc,GAAA;AAEpB,cAAM,YAAY,YAAY;AAAA,MAChC,CAAC,EACA,MAAM,MAAM;AAAA,MAIb,CAAC;AAAA,IACL;AAAA,IACA;AAAA,MACE,MAAM,SAAS,QAAQ;AAAA,MACvB,SAAS,SAAS;AAAA,MAClB,YAAY,SAAS,cAAc;AAAA;AAAA,MACnC,cAAc,SAAS,gBAAgB;AAAA;AAAA,MACvC,SAAS;AAAA;AAAA,IAAA;AAAA,EACX;AAGF,SAAO;AAAA,IACL,OAAO;AAAA,IACP;AAAA,IACA,SAAS,CACP,OACG;AAEH,aAAO,QAAQ,EAAuB;AAAA,IACxC;AAAA,IACA,SAAS,MAAM;AACb,aAAO,KAAA;AACP,aAAO,MAAA;AAAA,IACT;AAAA,EAAA;AAEJ;"}

package/dist/esm/strategies/throttleStrategy.js

@@ -1,6 +1,6 @@
-import { Throttler } from "@tanstack/pacer/throttler";
+import { LiteThrottler } from "@tanstack/pacer-lite/lite-throttler";
 function throttleStrategy(options) {
-  const throttler = new Throttler(
+  const throttler = new LiteThrottler(
     (callback) => callback(),
     options
   );

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 = 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;"}
+{"version":3,"file":"throttleStrategy.js","sources":["../../../src/strategies/throttleStrategy.ts"],"sourcesContent":["import { LiteThrottler } from \"@tanstack/pacer-lite/lite-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 LiteThrottler(\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/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@tanstack/db",
   "description": "A reactive client store for building super fast apps on sync",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "dependencies": {
     "@standard-schema/spec": "^1.0.0",
-    "@tanstack/pacer": "^0.16.3",
+    "@tanstack/pacer-lite": "^0.1.0",
     "@tanstack/db-ivm": "0.1.13"
   },
   "devDependencies": {

package/src/collection/sync.ts

@@ -231,6 +231,16 @@ export class CollectionSyncManager<
       return this.preloadPromise
     }
 
+    // Warn when calling preload on an on-demand collection
+    if (this.syncMode === `on-demand`) {
+      console.warn(
+        `${this.id ? `[${this.id}] ` : ``}Calling .preload() on a collection with syncMode "on-demand" is a no-op. ` +
+          `In on-demand mode, data is only loaded when queries request it. ` +
+          `Instead, create a live query and call .preload() on that to load the specific data you need. ` +
+          `See https://tanstack.com/blog/tanstack-db-0.5-query-driven-sync for more details.`
+      )
+    }
+
     this.preloadPromise = new Promise<void>((resolve, reject) => {
       if (this.lifecycle.status === `ready`) {
         resolve()

package/src/errors.ts

@@ -360,6 +360,15 @@ export class InvalidSourceError extends QueryBuilderError {
   }
 }
 
+export class InvalidSourceTypeError extends QueryBuilderError {
+  constructor(context: string, type: string) {
+    super(
+      `Invalid source for ${context}: Expected an object with a single key-value pair like { alias: collection }. ` +
+        `For example: .from({ todos: todosCollection }). Got: ${type}`
+    )
+  }
+}
+
 export class JoinConditionMustBeEqualityError extends QueryBuilderError {
   constructor() {
     super(`Join condition must be an equality expression`)

package/src/query/builder/index.ts

@@ -10,6 +10,7 @@ import {
 } from "../ir.js"
 import {
   InvalidSourceError,
+  InvalidSourceTypeError,
   JoinConditionMustBeEqualityError,
   OnlyOneSourceAllowedError,
   QueryMustHaveFromClauseError,
@@ -60,13 +61,38 @@ export class BaseQueryBuilder<TContext extends Context = Context> {
     source: TSource,
     context: string
   ): [string, CollectionRef | QueryRef] {
-    if (Object.keys(source).length !== 1) {
+    // Validate source is a plain object (not null, array, string, etc.)
+    // We use try-catch to handle null/undefined gracefully
+    let keys: Array<string>
+    try {
+      keys = Object.keys(source)
+    } catch {
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      const type = source === null ? `null` : `undefined`
+      throw new InvalidSourceTypeError(context, type)
+    }
+
+    // Check if it's an array (arrays pass Object.keys but aren't valid sources)
+    if (Array.isArray(source)) {
+      throw new InvalidSourceTypeError(context, `array`)
+    }
+
+    // Validate exactly one key
+    if (keys.length !== 1) {
+      if (keys.length === 0) {
+        throw new InvalidSourceTypeError(context, `empty object`)
+      }
+      // Check if it looks like a string was passed (has numeric keys)
+      if (keys.every((k) => !isNaN(Number(k)))) {
+        throw new InvalidSourceTypeError(context, `string`)
+      }
       throw new OnlyOneSourceAllowedError(context)
     }
 
-    const alias = Object.keys(source)[0]!
+    const alias = keys[0]!
     const sourceValue = source[alias]
 
+    // Validate the value is a Collection or QueryBuilder
     let ref: CollectionRef | QueryRef
 
     if (sourceValue instanceof CollectionImpl) {

package/src/strategies/debounceStrategy.ts

@@ -1,4 +1,4 @@
-import { Debouncer } from "@tanstack/pacer/debouncer"
+import { LiteDebouncer } from "@tanstack/pacer-lite/lite-debouncer"
 import type { DebounceStrategy, DebounceStrategyOptions } from "./types"
 import type { Transaction } from "../transactions"
 
@@ -28,7 +28,7 @@ import type { Transaction } from "../transactions"
 export function debounceStrategy(
   options: DebounceStrategyOptions
 ): DebounceStrategy {
-  const debouncer = new Debouncer(
+  const debouncer = new LiteDebouncer(
     (callback: () => Transaction) => callback(),
     options
   )

package/src/strategies/queueStrategy.ts

@@ -1,4 +1,4 @@
-import { AsyncQueuer } from "@tanstack/pacer/async-queuer"
+import { LiteQueuer } from "@tanstack/pacer-lite/lite-queuer"
 import type { QueueStrategy, QueueStrategyOptions } from "./types"
 import type { Transaction } from "../transactions"
 
@@ -44,16 +44,29 @@ import type { Transaction } from "../transactions"
  * ```
  */
 export function queueStrategy(options?: QueueStrategyOptions): QueueStrategy {
-  const queuer = new AsyncQueuer<() => Transaction>(
-    async (fn) => {
-      const transaction = fn()
-      // Wait for the transaction to be persisted before processing next item
-      // Note: fn() already calls commit(), we just wait for it to complete
-      await transaction.isPersisted.promise
+  // Manual promise chaining to ensure async serialization
+  // LiteQueuer (unlike AsyncQueuer from @tanstack/pacer) lacks built-in async queue
+  // primitives and concurrency control. We compensate by manually chaining promises
+  // to ensure each transaction completes before the next one starts.
+  let processingChain = Promise.resolve()
+
+  const queuer = new LiteQueuer<() => Transaction>(
+    (fn) => {
+      // Chain each transaction to the previous one's completion
+      processingChain = processingChain
+        .then(async () => {
+          const transaction = fn()
+          // Wait for the transaction to be persisted before processing next item
+          await transaction.isPersisted.promise
+        })
+        .catch(() => {
+          // Errors are handled via transaction.isPersisted.promise and surfaced there.
+          // This catch prevents unhandled promise rejections from breaking the chain,
+          // ensuring subsequent transactions can still execute even if one fails.
+        })
     },
     {
-      concurrency: 1, // Process one at a time to ensure serialization
-      wait: options?.wait,
+      wait: options?.wait ?? 0,
       maxSize: options?.maxSize,
       addItemsTo: options?.addItemsTo ?? `back`, // Default FIFO: add to back
       getItemsFrom: options?.getItemsFrom ?? `front`, // Default FIFO: get from front

package/src/strategies/throttleStrategy.ts

@@ -1,4 +1,4 @@
-import { Throttler } from "@tanstack/pacer/throttler"
+import { LiteThrottler } from "@tanstack/pacer-lite/lite-throttler"
 import type { ThrottleStrategy, ThrottleStrategyOptions } from "./types"
 import type { Transaction } from "../transactions"
 
@@ -48,7 +48,7 @@ import type { Transaction } from "../transactions"
 export function throttleStrategy(
   options: ThrottleStrategyOptions
 ): ThrottleStrategy {
-  const throttler = new Throttler(
+  const throttler = new LiteThrottler(
     (callback: () => Transaction) => callback(),
     options
   )