@tanstack/db 0.4.9 → 0.4.10

package/src/local-only.ts

@@ -1,15 +1,12 @@
 import type {
   BaseCollectionConfig,
   CollectionConfig,
-  DeleteMutationFn,
   DeleteMutationFnParams,
   InferSchemaOutput,
-  InsertMutationFn,
   InsertMutationFnParams,
   OperationType,
   PendingMutation,
   SyncConfig,
-  UpdateMutationFn,
   UpdateMutationFnParams,
   UtilsRecord,
 } from "./types"
@@ -67,13 +64,7 @@ type LocalOnlyCollectionOptionsResult<
   T extends object,
   TKey extends string | number,
   TSchema extends StandardSchemaV1 | never = never,
-> = Omit<
-  CollectionConfig<T, TKey, TSchema>,
-  `onInsert` | `onUpdate` | `onDelete`
-> & {
-  onInsert?: InsertMutationFn<T, TKey, LocalOnlyCollectionUtils>
-  onUpdate?: UpdateMutationFn<T, TKey, LocalOnlyCollectionUtils>
-  onDelete?: DeleteMutationFn<T, TKey, LocalOnlyCollectionUtils>
+> = CollectionConfig<T, TKey, TSchema> & {
   utils: LocalOnlyCollectionUtils
 }
 
@@ -191,7 +182,7 @@ export function localOnlyCollectionOptions<
   const { initialData, onInsert, onUpdate, onDelete, ...restConfig } = config
 
   // Create the sync configuration with transaction confirmation capability
-  const syncResult = createLocalOnlySync(initialData)
+  const syncResult = createLocalOnlySync<T, TKey>(initialData)
 
   /**
    * Create wrapper handlers that call user handlers first, then confirm transactions
@@ -279,9 +270,11 @@ export function localOnlyCollectionOptions<
     onDelete: wrappedOnDelete,
     utils: {
       acceptMutations,
-    } as LocalOnlyCollectionUtils,
+    },
     startSync: true,
     gcTime: 0,
+  } as LocalOnlyCollectionOptionsResult<T, TKey, TSchema> & {
+    schema?: StandardSchemaV1
   }
 }
 

package/src/query/compiler/index.ts

@@ -28,7 +28,9 @@ import type {
   NamespacedAndKeyedStream,
   ResultStream,
 } from "../../types.js"
-import type { QueryCache, QueryMapping } from "./types.js"
+import type { QueryCache, QueryMapping, WindowOptions } from "./types.js"
+
+export type { WindowOptions } from "./types.js"
 
 /**
  * Result of query compilation including both the pipeline and source-specific WHERE clauses
@@ -87,6 +89,7 @@ export function compileQuery(
   callbacks: Record<string, LazyCollectionCallbacks>,
   lazySources: Set<string>,
   optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,
+  setWindowFn: (windowFn: (options: WindowOptions) => void) => void,
   cache: QueryCache = new WeakMap(),
   queryMapping: QueryMapping = new WeakMap()
 ): CompilationResult {
@@ -134,6 +137,7 @@ export function compileQuery(
     callbacks,
     lazySources,
     optimizableOrderByCollections,
+    setWindowFn,
     cache,
     queryMapping,
     aliasToCollectionId,
@@ -169,6 +173,7 @@ export function compileQuery(
       callbacks,
       lazySources,
       optimizableOrderByCollections,
+      setWindowFn,
       rawQuery,
       compileQuery,
       aliasToCollectionId,
@@ -311,6 +316,7 @@ export function compileQuery(
       query.select || {},
       collections[mainCollectionId]!,
       optimizableOrderByCollections,
+      setWindowFn,
       query.limit,
       query.offset
     )
@@ -381,6 +387,7 @@ function processFrom(
   callbacks: Record<string, LazyCollectionCallbacks>,
   lazySources: Set<string>,
   optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,
+  setWindowFn: (windowFn: (options: WindowOptions) => void) => void,
   cache: QueryCache,
   queryMapping: QueryMapping,
   aliasToCollectionId: Record<string, string>,
@@ -412,6 +419,7 @@ function processFrom(
         callbacks,
         lazySources,
         optimizableOrderByCollections,
+        setWindowFn,
         cache,
         queryMapping
       )

package/src/query/compiler/joins.ts

@@ -31,7 +31,7 @@ import type {
   NamespacedAndKeyedStream,
   NamespacedRow,
 } from "../../types.js"
-import type { QueryCache, QueryMapping } from "./types.js"
+import type { QueryCache, QueryMapping, WindowOptions } from "./types.js"
 import type { CollectionSubscription } from "../../collection/subscription.js"
 
 /** Function type for loading specific keys into a lazy collection */
@@ -61,6 +61,7 @@ export function processJoins(
   callbacks: Record<string, LazyCollectionCallbacks>,
   lazySources: Set<string>,
   optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,
+  setWindowFn: (windowFn: (options: WindowOptions) => void) => void,
   rawQuery: QueryIR,
   onCompileSubquery: CompileQueryFn,
   aliasToCollectionId: Record<string, string>,
@@ -83,6 +84,7 @@ export function processJoins(
       callbacks,
       lazySources,
       optimizableOrderByCollections,
+      setWindowFn,
       rawQuery,
       onCompileSubquery,
       aliasToCollectionId,
@@ -111,6 +113,7 @@ function processJoin(
   callbacks: Record<string, LazyCollectionCallbacks>,
   lazySources: Set<string>,
   optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,
+  setWindowFn: (windowFn: (options: WindowOptions) => void) => void,
   rawQuery: QueryIR,
   onCompileSubquery: CompileQueryFn,
   aliasToCollectionId: Record<string, string>,
@@ -131,6 +134,7 @@ function processJoin(
     callbacks,
     lazySources,
     optimizableOrderByCollections,
+    setWindowFn,
     cache,
     queryMapping,
     onCompileSubquery,
@@ -421,6 +425,7 @@ function processJoinSource(
   callbacks: Record<string, LazyCollectionCallbacks>,
   lazySources: Set<string>,
   optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,
+  setWindowFn: (windowFn: (options: WindowOptions) => void) => void,
   cache: QueryCache,
   queryMapping: QueryMapping,
   onCompileSubquery: CompileQueryFn,
@@ -453,6 +458,7 @@ function processJoinSource(
         callbacks,
         lazySources,
         optimizableOrderByCollections,
+        setWindowFn,
         cache,
         queryMapping
       )

package/src/query/compiler/order-by.ts

@@ -5,6 +5,7 @@ import { ensureIndexForField } from "../../indexes/auto-index.js"
 import { findIndexForField } from "../../utils/index-optimization.js"
 import { compileExpression } from "./evaluators.js"
 import { replaceAggregatesByRefs } from "./group-by.js"
+import type { WindowOptions } from "./types.js"
 import type { CompiledSingleRowExpression } from "./evaluators.js"
 import type { OrderBy, OrderByClause, QueryIR, Select } from "../ir.js"
 import type { NamespacedAndKeyedStream, NamespacedRow } from "../../types.js"
@@ -38,6 +39,7 @@ export function processOrderBy(
   selectClause: Select,
   collection: Collection,
   optimizableOrderByCollections: Record<string, OrderByOptimizationInfo>,
+  setWindowFn: (windowFn: (options: WindowOptions) => void) => void,
   limit?: number,
   offset?: number
 ): IStreamBuilder<KeyValue<unknown, [NamespacedRow, string]>> {
@@ -107,6 +109,8 @@ export function processOrderBy(
 
   let setSizeCallback: ((getSize: () => number) => void) | undefined
 
+  let orderByOptimizationInfo: OrderByOptimizationInfo | undefined
+
   // Optimize the orderBy operator to lazily load elements
   // by using the range index of the collection.
   // Only for orderBy clause on a single column for now (no composite ordering)
@@ -161,7 +165,7 @@ export function processOrderBy(
             ? String(orderByExpression.path[0])
             : rawQuery.from.alias
 
-        const orderByOptimizationInfo = {
+        orderByOptimizationInfo = {
           alias: orderByAlias,
           offset: offset ?? 0,
           limit,
@@ -179,7 +183,7 @@ export function processOrderBy(
             ...optimizableOrderByCollections[followRefCollection.id]!,
             dataNeeded: () => {
               const size = getSize()
-              return Math.max(0, limit - size)
+              return Math.max(0, orderByOptimizationInfo!.limit - size)
             },
           }
         }
@@ -194,6 +198,23 @@ export function processOrderBy(
       offset,
       comparator: compare,
       setSizeCallback,
+      setWindowFn: (
+        windowFn: (options: { offset?: number; limit?: number }) => void
+      ) => {
+        setWindowFn(
+          // We wrap the move function such that we update the orderByOptimizationInfo
+          // because that is used by the `dataNeeded` callback to determine if we need to load more data
+          (options) => {
+            windowFn(options)
+            if (orderByOptimizationInfo) {
+              orderByOptimizationInfo.offset =
+                options.offset ?? orderByOptimizationInfo.offset
+              orderByOptimizationInfo.limit =
+                options.limit ?? orderByOptimizationInfo.limit
+            }
+          }
+        )
+      },
     })
     // orderByWithFractionalIndex returns [key, [value, index]] - we keep this format
   )

package/src/query/compiler/types.ts

@@ -10,3 +10,8 @@ export type QueryCache = WeakMap<QueryIR, CompilationResult>
  * Mapping from optimized queries back to their original queries for caching
  */
 export type QueryMapping = WeakMap<QueryIR, QueryIR>
+
+export type WindowOptions = {
+  offset?: number
+  limit?: number
+}

package/src/query/index.ts

@@ -56,3 +56,4 @@ export {
 } from "./live-query-collection.js"
 
 export { type LiveQueryCollectionConfig } from "./live/types.js"
+export { type LiveQueryCollectionUtils } from "./live/collection-config-builder.js"

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

@@ -1,11 +1,15 @@
 import { D2, output } from "@tanstack/db-ivm"
 import { compileQuery } from "../compiler/index.js"
 import { buildQuery, getQueryIR } from "../builder/index.js"
-import { MissingAliasInputsError } from "../../errors.js"
+import {
+  MissingAliasInputsError,
+  SetWindowRequiresOrderByError,
+} from "../../errors.js"
 import { transactionScopedScheduler } from "../../scheduler.js"
 import { getActiveTransaction } from "../../transactions.js"
 import { CollectionSubscriber } from "./collection-subscriber.js"
 import { getCollectionBuilder } from "./collection-registry.js"
+import type { WindowOptions } from "../compiler/index.js"
 import type { SchedulerContextId } from "../../scheduler.js"
 import type { CollectionSubscription } from "../../collection/subscription.js"
 import type { RootStreamBuilder } from "@tanstack/db-ivm"
@@ -32,6 +36,13 @@ import type { AllCollectionEvents } from "../../collection/events.js"
 export type LiveQueryCollectionUtils = UtilsRecord & {
   getRunCount: () => number
   getBuilder: () => CollectionConfigBuilder<any, any>
+  /**
+   * Sets the offset and limit of an ordered query.
+   * Is a no-op if the query is not ordered.
+   *
+   * @returns `true` if no subset loading was triggered, or `Promise<void>` that resolves when the subset has been loaded
+   */
+  setWindow: (options: WindowOptions) => true | Promise<void>
 }
 
 type PendingGraphRun = {
@@ -79,7 +90,11 @@ export class CollectionConfigBuilder<
   private isInErrorState = false
 
   // Reference to the live query collection for error state transitions
-  private liveQueryCollection?: Collection<TResult, any, any>
+  public liveQueryCollection?: Collection<TResult, any, any>
+
+  private windowFn: ((options: WindowOptions) => void) | undefined
+
+  private maybeRunGraphFn: (() => void) | undefined
 
   private readonly aliasDependencies: Record<
     string,
@@ -171,10 +186,39 @@ export class CollectionConfigBuilder<
       utils: {
         getRunCount: this.getRunCount.bind(this),
         getBuilder: () => this,
+        setWindow: this.setWindow.bind(this),
       },
     }
   }
 
+  setWindow(options: WindowOptions): true | Promise<void> {
+    if (!this.windowFn) {
+      throw new SetWindowRequiresOrderByError()
+    }
+
+    this.windowFn(options)
+    this.maybeRunGraphFn?.()
+
+    // Check if loading a subset was triggered
+    if (this.liveQueryCollection?.isLoadingSubset) {
+      // Loading was triggered, return a promise that resolves when it completes
+      return new Promise<void>((resolve) => {
+        const unsubscribe = this.liveQueryCollection!.on(
+          `loadingSubset:change`,
+          (event) => {
+            if (!event.isLoadingSubset) {
+              unsubscribe()
+              resolve()
+            }
+          }
+        )
+      })
+    }
+
+    // No loading was triggered
+    return true
+  }
+
   /**
    * Resolves a collection alias to its collection ID.
    *
@@ -452,13 +496,15 @@ export class CollectionConfigBuilder<
       }
     )
 
-    const loadMoreDataCallbacks = this.subscribeToAllCollections(
+    const loadSubsetDataCallbacks = this.subscribeToAllCollections(
       config,
       fullSyncState
     )
 
+    this.maybeRunGraphFn = () => this.scheduleGraphRun(loadSubsetDataCallbacks)
+
     // Initial run with callback to load more data if needed
-    this.scheduleGraphRun(loadMoreDataCallbacks)
+    this.scheduleGraphRun(loadSubsetDataCallbacks)
 
     // Return the unsubscribe function
     return () => {
@@ -517,7 +563,10 @@ export class CollectionConfigBuilder<
       this.subscriptions,
       this.lazySourcesCallbacks,
       this.lazySources,
-      this.optimizableOrderByCollections
+      this.optimizableOrderByCollections,
+      (windowFn: (options: WindowOptions) => void) => {
+        this.windowFn = windowFn
+      }
     )
 
     this.pipelineCache = compilation.pipeline
@@ -764,7 +813,7 @@ export class CollectionConfigBuilder<
     // Combine all loaders into a single callback that initiates loading more data
     // from any source that needs it. Returns true once all loaders have been called,
     // but the actual async loading may still be in progress.
-    const loadMoreDataCallback = () => {
+    const loadSubsetDataCallbacks = () => {
       loaders.map((loader) => loader())
       return true
     }
@@ -776,7 +825,7 @@ export class CollectionConfigBuilder<
     // Initial status check after all subscriptions are set up
     this.updateLiveQueryStatus(config)
 
-    return loadMoreDataCallback
+    return loadSubsetDataCallbacks
   }
 }
 

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>