@tanstack/db 0.4.9 → 0.4.11

package/src/query/live/collection-subscriber.ts

@@ -24,6 +24,12 @@ export class CollectionSubscriber<
   // Keep track of the biggest value we've sent so far (needed for orderBy optimization)
   private biggest: any = undefined
 
+  // Track deferred promises for subscription loading states
+  private subscriptionLoadingPromises = new Map<
+    CollectionSubscription,
+    { resolve: () => void }
+  >()
+
   constructor(
     private alias: string,
     private collectionId: string,
@@ -66,7 +72,51 @@ export class CollectionSubscriber<
         includeInitialState
       )
     }
+
+    // Subscribe to subscription status changes to propagate loading state
+    const statusUnsubscribe = subscription.on(`status:change`, (event) => {
+      // TODO: For now we are setting this loading state whenever the subscription
+      // status changes to 'loadingSubset'. But we have discussed it only happening
+      // when the the live query has it's offset/limit changed, and that triggers the
+      // subscription to request a snapshot. This will require more work to implement,
+      // and builds on https://github.com/TanStack/db/pull/663 which this PR
+      // does not yet depend on.
+      if (event.status === `loadingSubset`) {
+        // Guard against duplicate transitions
+        if (!this.subscriptionLoadingPromises.has(subscription)) {
+          let resolve: () => void
+          const promise = new Promise<void>((res) => {
+            resolve = res
+          })
+
+          this.subscriptionLoadingPromises.set(subscription, {
+            resolve: resolve!,
+          })
+          this.collectionConfigBuilder.liveQueryCollection!._sync.trackLoadPromise(
+            promise
+          )
+        }
+      } else {
+        // status is 'ready'
+        const deferred = this.subscriptionLoadingPromises.get(subscription)
+        if (deferred) {
+          // Clear the map entry FIRST (before resolving)
+          this.subscriptionLoadingPromises.delete(subscription)
+          deferred.resolve()
+        }
+      }
+    })
+
     const unsubscribe = () => {
+      // If subscription has a pending promise, resolve it before unsubscribing
+      const deferred = this.subscriptionLoadingPromises.get(subscription)
+      if (deferred) {
+        // Clear the map entry FIRST (before resolving)
+        this.subscriptionLoadingPromises.delete(subscription)
+        deferred.resolve()
+      }
+
+      statusUnsubscribe()
       subscription.unsubscribe()
     }
     // currentSyncState is always defined when subscribe() is called

package/src/query/live-query-collection.ts

@@ -20,16 +20,20 @@ import type { Context, GetResult } from "./builder/types.js"
 type CollectionConfigForContext<
   TContext extends Context,
   TResult extends object,
+  TUtils extends UtilsRecord = {},
 > = TContext extends SingleResult
-  ? CollectionConfigSingleRowOption<TResult> & SingleResult
-  : CollectionConfigSingleRowOption<TResult> & NonSingleResult
+  ? CollectionConfigSingleRowOption<TResult, string | number, never, TUtils> &
+      SingleResult
+  : CollectionConfigSingleRowOption<TResult, string | number, never, TUtils> &
+      NonSingleResult
 
 type CollectionForContext<
   TContext extends Context,
   TResult extends object,
+  TUtils extends UtilsRecord = {},
 > = TContext extends SingleResult
-  ? Collection<TResult> & SingleResult
-  : Collection<TResult> & NonSingleResult
+  ? Collection<TResult, string | number, TUtils> & SingleResult
+  : Collection<TResult, string | number, TUtils> & NonSingleResult
 
 /**
  * Creates live query collection options for use with createCollection

package/src/types.ts

@@ -3,6 +3,7 @@ import type { Collection } from "./collection/index.js"
 import type { StandardSchemaV1 } from "@standard-schema/spec"
 import type { Transaction } from "./transactions"
 import type { BasicExpression, OrderBy } from "./query/ir.js"
+import type { EventEmitter } from "./event-emitter.js"
 
 /**
  * Helper type to extract the output type from a standard schema
@@ -150,17 +151,83 @@ 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>,
@@ -242,7 +309,7 @@ export interface InsertConfig {
 export type UpdateMutationFnParams<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
-  TUtils extends UtilsRecord = Record<string, Fn>,
+  TUtils extends UtilsRecord = UtilsRecord,
 > = {
   transaction: TransactionWithMutations<T, `update`>
   collection: Collection<T, TKey, TUtils>
@@ -251,7 +318,7 @@ export type UpdateMutationFnParams<
 export type InsertMutationFnParams<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
-  TUtils extends UtilsRecord = Record<string, Fn>,
+  TUtils extends UtilsRecord = UtilsRecord,
 > = {
   transaction: TransactionWithMutations<T, `insert`>
   collection: Collection<T, TKey, TUtils>
@@ -259,7 +326,7 @@ export type InsertMutationFnParams<
 export type DeleteMutationFnParams<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
-  TUtils extends UtilsRecord = Record<string, Fn>,
+  TUtils extends UtilsRecord = UtilsRecord,
 > = {
   transaction: TransactionWithMutations<T, `delete`>
   collection: Collection<T, TKey, TUtils>
@@ -268,21 +335,21 @@ export type DeleteMutationFnParams<
 export type InsertMutationFn<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
-  TUtils extends UtilsRecord = Record<string, Fn>,
+  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 = Record<string, Fn>,
+  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 = Record<string, Fn>,
+  TUtils extends UtilsRecord = UtilsRecord,
   TReturn = any,
 > = (params: DeleteMutationFnParams<T, TKey, TUtils>) => Promise<TReturn>
 
@@ -313,6 +380,8 @@ export type CollectionStatus =
   /** Collection has been cleaned up and resources freed */
   | `cleaned-up`
 
+export type SyncMode = `eager` | `on-demand`
+
 export interface BaseCollectionConfig<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
@@ -321,7 +390,7 @@ export interface BaseCollectionConfig<
   // then it would conflict with the overloads of createCollection which
   // requires either T to be provided or a schema to be provided but not both!
   TSchema extends StandardSchemaV1 = never,
-  TUtils extends UtilsRecord = Record<string, Fn>,
+  TUtils extends UtilsRecord = UtilsRecord,
   TReturn = any,
 > {
   // If an id isn't passed in, a UUID will be
@@ -374,6 +443,15 @@ export interface BaseCollectionConfig<
    * 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
@@ -503,13 +581,16 @@ export interface BaseCollectionConfig<
    * }
    */
   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> {
+  TUtils extends UtilsRecord = UtilsRecord,
+> extends BaseCollectionConfig<T, TKey, TSchema, TUtils> {
   sync: SyncConfig<T, TKey>
 }
 
@@ -533,7 +614,8 @@ export type CollectionConfigSingleRowOption<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
   TSchema extends StandardSchemaV1 = never,
-> = CollectionConfig<T, TKey, TSchema> & MaybeSingleResult
+  TUtils extends UtilsRecord = {},
+> = CollectionConfig<T, TKey, TSchema, TUtils> & MaybeSingleResult
 
 export type ChangesPayload<T extends object = Record<string, unknown>> = Array<
   ChangeMessage<T>