add sync mode to base colleciton

Author: samwillis

packages/db/src/collection/sync.ts

@@ -1,4 +1,5 @@
 import {
+  CollectionConfigurationError,
   CollectionIsInErrorStateError,
   DuplicateKeySyncError,
   NoPendingSyncTransactionCommitError,
@@ -33,6 +34,7 @@ export class CollectionSyncManager<
   private _events!: CollectionEventsManager
   private config!: CollectionConfig<TOutput, TKey, TSchema>
   private id: string
+  private syncMode: `eager` | `on-demand`
 
   public preloadPromise: Promise<void> | null = null
   public syncCleanupFn: (() => void) | null = null
@@ -48,6 +50,7 @@ export class CollectionSyncManager<
   constructor(config: CollectionConfig<TOutput, TKey, TSchema>, id: string) {
     this.config = config
     this.id = id
+    this.syncMode = config.syncMode ?? `eager`
   }
 
   setDeps(deps: {
@@ -197,6 +200,14 @@ export class CollectionSyncManager<
 
       // Store loadSubset function if provided
       this.syncLoadSubsetFn = syncRes?.loadSubset ?? null
+
+      // Validate: on-demand mode requires a loadSubset function
+      if (this.syncMode === `on-demand` && !this.syncLoadSubsetFn) {
+        throw new CollectionConfigurationError(
+          `Collection "${this.id}" is configured with syncMode "on-demand" but the sync function did not return a loadSubset handler. ` +
+            `Either provide a loadSubset handler or use syncMode "eager".`
+        )
+      }
     } catch (error) {
       this.lifecycle.setStatus(`error`)
       throw error
@@ -292,9 +303,14 @@ export class CollectionSyncManager<
    * @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.
-   *          Returns undefined if no sync function is configured.
+   *          Returns undefined if no sync function is configured or if syncMode is 'eager'.
    */
   public loadSubset(options: LoadSubsetOptions): Promise<void> | undefined {
+    // Bypass loadSubset when syncMode is 'eager'
+    if (this.syncMode === `eager`) {
+      return undefined
+    }
+
     if (this.syncLoadSubsetFn) {
       const result = this.syncLoadSubsetFn(options)
 

packages/db/src/types.ts

@@ -380,6 +380,16 @@ export type CollectionStatus =
   /** Collection has been cleaned up and resources freed */
   | `cleaned-up`
 
+/**
+ * @default `eager`
+ * @description
+ * Collections have two modes of sync: eager and on-demand.
+ * - 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.
+ */
+export type SyncMode = `eager` | `on-demand`
+
 export interface BaseCollectionConfig<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
@@ -441,6 +451,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

packages/db/tests/collection-subscription.test.ts

@@ -29,6 +29,7 @@ describe(`CollectionSubscription status tracking`, () => {
     const collection = createCollection<{ id: string; value: string }>({
       id: `test`,
       getKey: (item) => item.id,
+      syncMode: `on-demand`,
       sync: {
         sync: ({ markReady }) => {
           markReady()
@@ -70,6 +71,7 @@ describe(`CollectionSubscription status tracking`, () => {
     const collection = createCollection<{ id: string; value: string }>({
       id: `test`,
       getKey: (item) => item.id,
+      syncMode: `on-demand`,
       sync: {
         sync: ({ markReady }) => {
           markReady()
@@ -102,6 +104,7 @@ describe(`CollectionSubscription status tracking`, () => {
     const collection = createCollection<{ id: string; value: string }>({
       id: `test`,
       getKey: (item) => item.id,
+      syncMode: `on-demand`,
       sync: {
         sync: ({ markReady }) => {
           markReady()
@@ -160,6 +163,7 @@ describe(`CollectionSubscription status tracking`, () => {
     const collection = createCollection<{ id: string; value: string }>({
       id: `test`,
       getKey: (item) => item.id,
+      syncMode: `on-demand`,
       sync: {
         sync: ({ markReady }) => {
           markReady()
@@ -215,6 +219,7 @@ describe(`CollectionSubscription status tracking`, () => {
     const collection = createCollection<{ id: string; value: string }>({
       id: `test`,
       getKey: (item) => item.id,
+      syncMode: `on-demand`,
       sync: {
         sync: ({ markReady }) => {
           markReady()

packages/db/tests/collection.test.ts

@@ -1381,6 +1381,7 @@ describe(`Collection isLoadingMore property`, () => {
     const collection = createCollection<{ id: string; value: string }>({
       id: `test`,
       getKey: (item) => item.id,
+      syncMode: `on-demand`,
       startSync: true,
       sync: {
         sync: ({ markReady }) => {
@@ -1412,6 +1413,7 @@ describe(`Collection isLoadingMore property`, () => {
     const collection = createCollection<{ id: string; value: string }>({
       id: `test`,
       getKey: (item) => item.id,
+      syncMode: `on-demand`,
       startSync: true,
       sync: {
         sync: ({ markReady }) => {
@@ -1440,6 +1442,7 @@ describe(`Collection isLoadingMore property`, () => {
     const collection = createCollection<{ id: string; value: string }>({
       id: `test`,
       getKey: (item) => item.id,
+      syncMode: `on-demand`,
       startSync: true,
       sync: {
         sync: ({ markReady }) => {
@@ -1489,6 +1492,7 @@ describe(`Collection isLoadingMore property`, () => {
     const collection = createCollection<{ id: string; value: string }>({
       id: `test`,
       getKey: (item) => item.id,
+      syncMode: `on-demand`,
       startSync: true,
       sync: {
         sync: ({ markReady }) => {
@@ -1542,6 +1546,7 @@ describe(`Collection isLoadingMore property`, () => {
     const collection = createCollection<{ id: string; value: string }>({
       id: `test`,
       getKey: (item) => item.id,
+      syncMode: `on-demand`,
       startSync: true,
       sync: {
         sync: ({ markReady }) => {

packages/db/tests/query/live-query-collection.test.ts

@@ -990,6 +990,7 @@ describe(`createLiveQueryCollection`, () => {
       const sourceCollection = createCollection<{ id: string; value: number }>({
         id: `source`,
         getKey: (item) => item.id,
+        syncMode: `on-demand`,
         sync: {
           sync: ({ markReady, begin, write, commit }) => {
             begin()