@tanstack/db 0.5.3 → 0.5.5

package/dist/esm/types.d.ts

@@ -198,10 +198,12 @@ export type LoadSubsetOptions = {
     subscription?: Subscription;
 };
 export type LoadSubsetFn = (options: LoadSubsetOptions) => true | Promise<void>;
+export type UnloadSubsetFn = (options: LoadSubsetOptions) => void;
 export type CleanupFn = () => void;
 export type SyncConfigRes = {
     cleanup?: CleanupFn;
     loadSubset?: LoadSubsetFn;
+    unloadSubset?: UnloadSubsetFn;
 };
 export interface SyncConfig<T extends object = Record<string, unknown>, TKey extends string | number = string | number> {
     sync: (params: {

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.5",
   "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/subscription.ts

@@ -10,6 +10,7 @@ import type { BasicExpression, OrderBy } from "../query/ir.js"
 import type { IndexInterface } from "../indexes/base-index.js"
 import type {
   ChangeMessage,
+  LoadSubsetOptions,
   Subscription,
   SubscriptionEvents,
   SubscriptionStatus,
@@ -47,6 +48,12 @@ export class CollectionSubscription
   // While `snapshotSent` is false we filter out all changes from subscription to the collection.
   private snapshotSent = false
 
+  /**
+   * Track all loadSubset calls made by this subscription so we can unload them on cleanup.
+   * We store the exact LoadSubsetOptions we passed to loadSubset to ensure symmetric unload.
+   */
+  private loadedSubsets: Array<LoadSubsetOptions> = []
+
   // Keep track of the keys we've sent (needed for join and orderBy optimizations)
   private sentKeys = new Set<string | number>()
 
@@ -193,10 +200,14 @@ export class CollectionSubscription
 
     // Request the sync layer to load more data
     // don't await it, we will load the data into the collection when it comes in
-    const syncResult = this.collection._sync.loadSubset({
+    const loadOptions: LoadSubsetOptions = {
       where: stateOpts.where,
       subscription: this,
-    })
+    }
+    const syncResult = this.collection._sync.loadSubset(loadOptions)
+
+    // Track this loadSubset call so we can unload it later
+    this.loadedSubsets.push(loadOptions)
 
     const trackLoadSubsetPromise = opts?.trackLoadSubsetPromise ?? true
     if (trackLoadSubsetPromise) {
@@ -333,12 +344,16 @@ export class CollectionSubscription
 
     // Request the sync layer to load more data
     // don't await it, we will load the data into the collection when it comes in
-    const syncResult = this.collection._sync.loadSubset({
+    const loadOptions1: LoadSubsetOptions = {
       where: whereWithValueFilter,
       limit,
       orderBy,
       subscription: this,
-    })
+    }
+    const syncResult = this.collection._sync.loadSubset(loadOptions1)
+
+    // Track this loadSubset call
+    this.loadedSubsets.push(loadOptions1)
 
     // Make parallel loadSubset calls for values equal to minValue and values greater than minValue
     const promises: Array<Promise<void>> = []
@@ -348,10 +363,14 @@ export class CollectionSubscription
       const { expression } = orderBy[0]!
       const exactValueFilter = eq(expression, new Value(minValue))
 
-      const equalValueResult = this.collection._sync.loadSubset({
+      const loadOptions2: LoadSubsetOptions = {
         where: exactValueFilter,
         subscription: this,
-      })
+      }
+      const equalValueResult = this.collection._sync.loadSubset(loadOptions2)
+
+      // Track this loadSubset call
+      this.loadedSubsets.push(loadOptions2)
 
       if (equalValueResult instanceof Promise) {
         promises.push(equalValueResult)
@@ -417,6 +436,13 @@ export class CollectionSubscription
   }
 
   unsubscribe() {
+    // Unload all subsets that this subscription loaded
+    // We pass the exact same LoadSubsetOptions we used for loadSubset
+    for (const options of this.loadedSubsets) {
+      this.collection._sync.unloadSubset(options)
+    }
+    this.loadedSubsets = []
+
     this.emitInner(`unsubscribed`, {
       type: `unsubscribed`,
       subscription: this,

package/src/collection/sync.ts

@@ -43,6 +43,8 @@ export class CollectionSyncManager<
   public syncLoadSubsetFn:
     | ((options: LoadSubsetOptions) => true | Promise<void>)
     | null = null
+  public syncUnloadSubsetFn: ((options: LoadSubsetOptions) => void) | null =
+    null
 
   private pendingLoadSubsetPromises: Set<Promise<void>> = new Set()
 
@@ -209,6 +211,9 @@ export class CollectionSyncManager<
       // Store loadSubset function if provided
       this.syncLoadSubsetFn = syncRes?.loadSubset ?? null
 
+      // Store unloadSubset function if provided
+      this.syncUnloadSubsetFn = syncRes?.unloadSubset ?? null
+
       // Validate: on-demand mode requires a loadSubset function
       if (this.syncMode === `on-demand` && !this.syncLoadSubsetFn) {
         throw new CollectionConfigurationError(
@@ -231,6 +236,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()
@@ -331,6 +346,16 @@ export class CollectionSyncManager<
     return true
   }
 
+  /**
+   * Notifies the sync layer that a subset is no longer needed.
+   * @param options Options that identify what data is being unloaded
+   */
+  public unloadSubset(options: LoadSubsetOptions): void {
+    if (this.syncUnloadSubsetFn) {
+      this.syncUnloadSubsetFn(options)
+    }
+  }
+
   public cleanup(): void {
     try {
       if (this.syncCleanupFn) {

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
   )

package/src/types.ts

@@ -273,11 +273,14 @@ export type LoadSubsetOptions = {
 
 export type LoadSubsetFn = (options: LoadSubsetOptions) => true | Promise<void>
 
+export type UnloadSubsetFn = (options: LoadSubsetOptions) => void
+
 export type CleanupFn = () => void
 
 export type SyncConfigRes = {
   cleanup?: CleanupFn
   loadSubset?: LoadSubsetFn
+  unloadSubset?: UnloadSubsetFn
 }
 export interface SyncConfig<
   T extends object = Record<string, unknown>,