@tanstack/db 0.4.9 → 0.4.11

package/dist/esm/types.d.ts

@@ -3,6 +3,7 @@ import { Collection } from './collection/index.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Transaction } from './transactions.js';
 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/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@tanstack/db",
   "description": "A reactive client store for building super fast apps on sync",
-  "version": "0.4.9",
+  "version": "0.4.11",
   "dependencies": {
     "@standard-schema/spec": "^1.0.0",
-    "@tanstack/db-ivm": "0.1.10"
+    "@tanstack/db-ivm": "0.1.11"
   },
   "devDependencies": {
     "@vitest/coverage-istanbul": "^3.2.4",

package/src/collection/events.ts

@@ -1,3 +1,4 @@
+import { EventEmitter } from "../event-emitter.js"
 import type { Collection } from "./index.js"
 import type { CollectionStatus } from "../types.js"
 
@@ -31,9 +32,21 @@ export interface CollectionSubscribersChangeEvent {
   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>
 }
@@ -42,94 +55,32 @@ export type CollectionEvent =
   | AllCollectionEvents[keyof AllCollectionEvents]
   | CollectionStatusChangeEvent
   | CollectionSubscribersChangeEvent
+  | CollectionLoadingSubsetChangeEvent
 
 export type CollectionEventHandler<T extends keyof AllCollectionEvents> = (
   event: AllCollectionEvents[T]
 ) => void
 
-export class CollectionEventsManager {
+export class CollectionEventsManager extends EventEmitter<AllCollectionEvents> {
   private collection!: Collection<any, any, any, any, any>
-  private listeners = new Map<
-    keyof AllCollectionEvents,
-    Set<CollectionEventHandler<any>>
-  >()
 
-  constructor() {}
+  constructor() {
+    super()
+  }
 
   setDeps(deps: { collection: Collection<any, any, any, any, any> }) {
     this.collection = deps.collection
   }
 
-  on<T extends keyof AllCollectionEvents>(
-    event: T,
-    callback: CollectionEventHandler<T>
-  ) {
-    if (!this.listeners.has(event)) {
-      this.listeners.set(event, new Set())
-    }
-    this.listeners.get(event)!.add(callback)
-
-    return () => {
-      this.listeners.get(event)?.delete(callback)
-    }
-  }
-
-  once<T extends keyof AllCollectionEvents>(
-    event: T,
-    callback: CollectionEventHandler<T>
-  ) {
-    const unsubscribe = this.on(event, (eventPayload) => {
-      callback(eventPayload)
-      unsubscribe()
-    })
-    return unsubscribe
-  }
-
-  off<T extends keyof AllCollectionEvents>(
-    event: T,
-    callback: CollectionEventHandler<T>
-  ) {
-    this.listeners.get(event)?.delete(callback)
-  }
-
-  waitFor<T extends keyof AllCollectionEvents>(
-    event: T,
-    timeout?: number
-  ): Promise<AllCollectionEvents[T]> {
-    return new Promise((resolve, reject) => {
-      let timeoutId: NodeJS.Timeout | undefined
-      const unsubscribe = this.on(event, (eventPayload) => {
-        if (timeoutId) {
-          clearTimeout(timeoutId)
-          timeoutId = undefined
-        }
-        resolve(eventPayload)
-        unsubscribe()
-      })
-      if (timeout) {
-        timeoutId = setTimeout(() => {
-          timeoutId = undefined
-          unsubscribe()
-          reject(new Error(`Timeout waiting for event ${event}`))
-        }, timeout)
-      }
-    })
-  }
-
+  /**
+   * Emit an event to all listeners
+   * Public API for emitting collection events
+   */
   emit<T extends keyof AllCollectionEvents>(
     event: T,
     eventPayload: AllCollectionEvents[T]
-  ) {
-    this.listeners.get(event)?.forEach((listener) => {
-      try {
-        listener(eventPayload)
-      } catch (error) {
-        // Re-throw in a microtask to surface the error
-        queueMicrotask(() => {
-          throw error
-        })
-      }
-    })
+  ): void {
+    this.emitInner(event, eventPayload)
   }
 
   emitStatusChange<T extends CollectionStatus>(
@@ -166,6 +117,6 @@ export class CollectionEventsManager {
   }
 
   cleanup() {
-    this.listeners.clear()
+    this.clearListeners()
   }
 }

package/src/collection/index.ts

@@ -25,7 +25,6 @@ import type {
   InferSchemaOutput,
   InsertConfig,
   NonSingleResult,
-  OnLoadMoreOptions,
   OperationConfig,
   SingleResult,
   SubscribeChangesOptions,
@@ -48,7 +47,7 @@ import type { IndexProxy } from "../indexes/lazy-index.js"
 export interface Collection<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
-  TUtils extends UtilsRecord = {},
+  TUtils extends UtilsRecord = UtilsRecord,
   TSchema extends StandardSchemaV1 = StandardSchemaV1,
   TInsertInput extends object = T,
 > extends CollectionImpl<T, TKey, TUtils, TSchema, TInsertInput> {
@@ -131,7 +130,7 @@ export interface Collection<
 export function createCollection<
   T extends StandardSchemaV1,
   TKey extends string | number = string | number,
-  TUtils extends UtilsRecord = {},
+  TUtils extends UtilsRecord = UtilsRecord,
 >(
   options: CollectionConfig<InferSchemaOutput<T>, TKey, T> & {
     schema: T
@@ -144,7 +143,7 @@ export function createCollection<
 export function createCollection<
   T extends StandardSchemaV1,
   TKey extends string | number = string | number,
-  TUtils extends UtilsRecord = {},
+  TUtils extends UtilsRecord = UtilsRecord,
 >(
   options: CollectionConfig<InferSchemaOutput<T>, TKey, T> & {
     schema: T
@@ -158,7 +157,7 @@ export function createCollection<
 export function createCollection<
   T extends object,
   TKey extends string | number = string | number,
-  TUtils extends UtilsRecord = {},
+  TUtils extends UtilsRecord = UtilsRecord,
 >(
   options: CollectionConfig<T, TKey, never> & {
     schema?: never // prohibit schema if an explicit type is provided
@@ -171,7 +170,7 @@ export function createCollection<
 export function createCollection<
   T extends object,
   TKey extends string | number = string | number,
-  TUtils extends UtilsRecord = {},
+  TUtils extends UtilsRecord = UtilsRecord,
 >(
   options: CollectionConfig<T, TKey, never> & {
     schema?: never // prohibit schema if an explicit type is provided
@@ -218,7 +217,7 @@ export class CollectionImpl<
   private _events: CollectionEventsManager
   private _changes: CollectionChangesManager<TOutput, TKey, TSchema, TInput>
   public _lifecycle: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>
-  private _sync: CollectionSyncManager<TOutput, TKey, TSchema, TInput>
+  public _sync: CollectionSyncManager<TOutput, TKey, TSchema, TInput>
   private _indexes: CollectionIndexesManager<TOutput, TKey, TSchema, TInput>
   private _mutations: CollectionMutationsManager<
     TOutput,
@@ -303,6 +302,7 @@ export class CollectionImpl<
       collection: this, // Required for passing to config.sync callback
       state: this._state,
       lifecycle: this._lifecycle,
+      events: this._events,
     })
 
     // Only start sync immediately if explicitly enabled
@@ -356,23 +356,19 @@ export class CollectionImpl<
   }
 
   /**
-   * Start sync immediately - internal method for compiled queries
-   * This bypasses lazy loading for special cases like live query results
+   * Check if the collection is currently loading more data
+   * @returns true if the collection has pending load more operations, false otherwise
    */
-  public startSyncImmediate(): void {
-    this._sync.startSync()
+  public get isLoadingSubset(): boolean {
+    return this._sync.isLoadingSubset
   }
 
   /**
-   * Requests the sync layer to load more data.
-   * @param options Options to control what data is being loaded
-   * @returns If data loading is asynchronous, this method returns a promise that resolves when the data is loaded.
-   *          If data loading is synchronous, the data is loaded when the method returns.
+   * Start sync immediately - internal method for compiled queries
+   * This bypasses lazy loading for special cases like live query results
    */
-  public syncMore(options: OnLoadMoreOptions): void | Promise<void> {
-    if (this._sync.syncOnLoadMoreFn) {
-      return this._sync.syncOnLoadMoreFn(options)
-    }
+  public startSyncImmediate(): void {
+    this._sync.startSync()
   }
 
   /**

package/src/collection/subscription.ts

@@ -1,13 +1,20 @@
 import { ensureIndexForExpression } from "../indexes/auto-index.js"
 import { and, gt, lt } from "../query/builder/functions.js"
 import { Value } from "../query/ir.js"
+import { EventEmitter } from "../event-emitter.js"
 import {
   createFilterFunctionFromExpression,
   createFilteredCallback,
 } from "./change-events.js"
 import type { BasicExpression, OrderBy } from "../query/ir.js"
 import type { IndexInterface } from "../indexes/base-index.js"
-import type { ChangeMessage } from "../types.js"
+import type {
+  ChangeMessage,
+  Subscription,
+  SubscriptionEvents,
+  SubscriptionStatus,
+  SubscriptionUnsubscribedEvent,
+} from "../types.js"
 import type { CollectionImpl } from "./index.js"
 
 type RequestSnapshotOptions = {
@@ -22,13 +29,17 @@ type RequestLimitedSnapshotOptions = {
 }
 
 type CollectionSubscriptionOptions = {
+  includeInitialState?: boolean
   /** Pre-compiled expression for filtering changes */
   whereExpression?: BasicExpression<boolean>
   /** Callback to call when the subscription is unsubscribed */
-  onUnsubscribe?: () => void
+  onUnsubscribe?: (event: SubscriptionUnsubscribedEvent) => void
 }
 
-export class CollectionSubscription {
+export class CollectionSubscription
+  extends EventEmitter<SubscriptionEvents>
+  implements Subscription
+{
   private loadedInitialState = false
 
   // Flag to indicate that we have sent at least 1 snapshot.
@@ -42,11 +53,24 @@ export class CollectionSubscription {
 
   private orderByIndex: IndexInterface<string | number> | undefined
 
+  // Status tracking
+  private _status: SubscriptionStatus = `ready`
+  private pendingLoadSubsetPromises: Set<Promise<void>> = new Set()
+
+  public get status(): SubscriptionStatus {
+    return this._status
+  }
+
   constructor(
     private collection: CollectionImpl<any, any, any, any, any>,
     private callback: (changes: Array<ChangeMessage<any, any>>) => void,
     private options: CollectionSubscriptionOptions
   ) {
+    super()
+    if (options.onUnsubscribe) {
+      this.on(`unsubscribed`, (event) => options.onUnsubscribe!(event))
+    }
+
     // Auto-index for where expressions if enabled
     if (options.whereExpression) {
       ensureIndexForExpression(options.whereExpression, this.collection)
@@ -71,6 +95,53 @@ export class CollectionSubscription {
     this.orderByIndex = index
   }
 
+  /**
+   * Set subscription status and emit events if changed
+   */
+  private setStatus(newStatus: SubscriptionStatus) {
+    if (this._status === newStatus) {
+      return // No change
+    }
+
+    const previousStatus = this._status
+    this._status = newStatus
+
+    // Emit status:change event
+    this.emitInner(`status:change`, {
+      type: `status:change`,
+      subscription: this,
+      previousStatus,
+      status: newStatus,
+    })
+
+    // Emit specific status event
+    const eventKey: `status:${SubscriptionStatus}` = `status:${newStatus}`
+    this.emitInner(eventKey, {
+      type: eventKey,
+      subscription: this,
+      previousStatus,
+      status: newStatus,
+    } as SubscriptionEvents[typeof eventKey])
+  }
+
+  /**
+   * Track a loadSubset promise and manage loading status
+   */
+  private trackLoadSubsetPromise(syncResult: Promise<void> | true) {
+    // Track the promise if it's actually a promise (async work)
+    if (syncResult instanceof Promise) {
+      this.pendingLoadSubsetPromises.add(syncResult)
+      this.setStatus(`loadingSubset`)
+
+      syncResult.finally(() => {
+        this.pendingLoadSubsetPromises.delete(syncResult)
+        if (this.pendingLoadSubsetPromises.size === 0) {
+          this.setStatus(`ready`)
+        }
+      })
+    }
+  }
+
   hasLoadedInitialState() {
     return this.loadedInitialState
   }
@@ -121,10 +192,13 @@ 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
-    this.collection.syncMore({
+    const syncResult = this.collection._sync.loadSubset({
       where: stateOpts.where,
+      subscription: this,
     })
 
+    this.trackLoadSubsetPromise(syncResult)
+
     // Also load data immediately from the collection
     const snapshot = this.collection.currentStateAsChanges(stateOpts)
 
@@ -215,11 +289,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
-    this.collection.syncMore({
+    const syncResult = this.collection._sync.loadSubset({
       where: whereWithValueFilter,
       limit,
       orderBy,
+      subscription: this,
     })
+
+    this.trackLoadSubsetPromise(syncResult)
   }
 
   /**
@@ -264,6 +341,11 @@ export class CollectionSubscription {
   }
 
   unsubscribe() {
-    this.options.onUnsubscribe?.()
+    this.emitInner(`unsubscribed`, {
+      type: `unsubscribed`,
+      subscription: this,
+    })
+    // Clear all event listeners to prevent memory leaks
+    this.clearListeners()
   }
 }