@tanstack/db 0.4.0 → 0.4.1

package/dist/cjs/collection/lifecycle.cjs

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const errors = require("../errors.cjs");
+const browserPolyfills = require("../utils/browser-polyfills.cjs");
 class CollectionLifecycleManager {
   /**
    * Creates a new CollectionLifecycleManager instance
@@ -11,6 +12,7 @@ class CollectionLifecycleManager {
     this.hasReceivedFirstCommit = false;
     this.onFirstReadyCallbacks = [];
     this.gcTimeoutId = null;
+    this.idleCallbackId = null;
     this.config = config;
     this.id = id;
   }
@@ -105,7 +107,7 @@ class CollectionLifecycleManager {
     }
     this.gcTimeoutId = setTimeout(() => {
       if (this.changes.activeSubscribersCount === 0) {
-        this.cleanup();
+        this.scheduleIdleCleanup();
       }
     }, gcTime);
   }
@@ -118,6 +120,57 @@ class CollectionLifecycleManager {
       clearTimeout(this.gcTimeoutId);
       this.gcTimeoutId = null;
     }
+    if (this.idleCallbackId !== null) {
+      browserPolyfills.safeCancelIdleCallback(this.idleCallbackId);
+      this.idleCallbackId = null;
+    }
+  }
+  /**
+   * Schedule cleanup to run during browser idle time
+   * This prevents blocking the UI thread during cleanup operations
+   */
+  scheduleIdleCleanup() {
+    if (this.idleCallbackId !== null) {
+      browserPolyfills.safeCancelIdleCallback(this.idleCallbackId);
+    }
+    this.idleCallbackId = browserPolyfills.safeRequestIdleCallback(
+      (deadline) => {
+        if (this.changes.activeSubscribersCount === 0) {
+          const cleanupCompleted = this.performCleanup(deadline);
+          if (cleanupCompleted) {
+            this.idleCallbackId = null;
+          }
+        } else {
+          this.idleCallbackId = null;
+        }
+      },
+      { timeout: 1e3 }
+    );
+  }
+  /**
+   * Perform cleanup operations, optionally in chunks during idle time
+   * @returns true if cleanup was completed, false if it was rescheduled
+   */
+  performCleanup(deadline) {
+    const hasTime = !deadline || deadline.timeRemaining() > 0 || deadline.didTimeout;
+    if (hasTime) {
+      this.events.cleanup();
+      this.sync.cleanup();
+      this.state.cleanup();
+      this.changes.cleanup();
+      this.indexes.cleanup();
+      if (this.gcTimeoutId) {
+        clearTimeout(this.gcTimeoutId);
+        this.gcTimeoutId = null;
+      }
+      this.hasBeenReady = false;
+      this.onFirstReadyCallbacks = [];
+      this.setStatus(`cleaned-up`);
+      return true;
+    } else {
+      this.scheduleIdleCleanup();
+      return false;
+    }
   }
   /**
    * Register a callback to be executed when the collection first becomes ready
@@ -132,18 +185,11 @@ class CollectionLifecycleManager {
     this.onFirstReadyCallbacks.push(callback);
   }
   cleanup() {
-    this.events.cleanup();
-    this.sync.cleanup();
-    this.state.cleanup();
-    this.changes.cleanup();
-    this.indexes.cleanup();
-    if (this.gcTimeoutId) {
-      clearTimeout(this.gcTimeoutId);
-      this.gcTimeoutId = null;
+    if (this.idleCallbackId !== null) {
+      browserPolyfills.safeCancelIdleCallback(this.idleCallbackId);
+      this.idleCallbackId = null;
     }
-    this.hasBeenReady = false;
-    this.onFirstReadyCallbacks = [];
-    this.setStatus(`cleaned-up`);
+    this.performCleanup();
   }
 }
 exports.CollectionLifecycleManager = CollectionLifecycleManager;

package/dist/cjs/collection/lifecycle.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle.cjs","sources":["../../../src/collection/lifecycle.ts"],"sourcesContent":["import {\n  CollectionInErrorStateError,\n  InvalidCollectionStatusTransitionError,\n} from \"../errors\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\nimport type { CollectionConfig, CollectionStatus } from \"../types\"\nimport type { CollectionEventsManager } from \"./events\"\nimport type { CollectionIndexesManager } from \"./indexes\"\nimport type { CollectionChangesManager } from \"./changes\"\nimport type { CollectionSyncManager } from \"./sync\"\nimport type { CollectionStateManager } from \"./state\"\n\nexport class CollectionLifecycleManager<\n  TOutput extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n  TSchema extends StandardSchemaV1 = StandardSchemaV1,\n  TInput extends object = TOutput,\n> {\n  private config: CollectionConfig<TOutput, TKey, TSchema>\n  private id: string\n  private indexes!: CollectionIndexesManager<TOutput, TKey, TSchema, TInput>\n  private events!: CollectionEventsManager\n  private changes!: CollectionChangesManager<TOutput, TKey, TSchema, TInput>\n  private sync!: CollectionSyncManager<TOutput, TKey, TSchema, TInput>\n  private state!: CollectionStateManager<TOutput, TKey, TSchema, TInput>\n\n  public status: CollectionStatus = `idle`\n  public hasBeenReady = false\n  public hasReceivedFirstCommit = false\n  public onFirstReadyCallbacks: Array<() => void> = []\n  public gcTimeoutId: ReturnType<typeof setTimeout> | null = null\n\n  /**\n   * Creates a new CollectionLifecycleManager instance\n   */\n  constructor(config: CollectionConfig<TOutput, TKey, TSchema>, id: string) {\n    this.config = config\n    this.id = id\n  }\n\n  setDeps(deps: {\n    indexes: CollectionIndexesManager<TOutput, TKey, TSchema, TInput>\n    events: CollectionEventsManager\n    changes: CollectionChangesManager<TOutput, TKey, TSchema, TInput>\n    sync: CollectionSyncManager<TOutput, TKey, TSchema, TInput>\n    state: CollectionStateManager<TOutput, TKey, TSchema, TInput>\n  }) {\n    this.indexes = deps.indexes\n    this.events = deps.events\n    this.changes = deps.changes\n    this.sync = deps.sync\n    this.state = deps.state\n  }\n\n  /**\n   * Validates state transitions to prevent invalid status changes\n   */\n  public validateStatusTransition(\n    from: CollectionStatus,\n    to: CollectionStatus\n  ): void {\n    if (from === to) {\n      // Allow same state transitions\n      return\n    }\n    const validTransitions: Record<\n      CollectionStatus,\n      Array<CollectionStatus>\n    > = {\n      idle: [`loading`, `error`, `cleaned-up`],\n      loading: [`initialCommit`, `ready`, `error`, `cleaned-up`],\n      initialCommit: [`ready`, `error`, `cleaned-up`],\n      ready: [`cleaned-up`, `error`],\n      error: [`cleaned-up`, `idle`],\n      \"cleaned-up\": [`loading`, `error`],\n    }\n\n    if (!validTransitions[from].includes(to)) {\n      throw new InvalidCollectionStatusTransitionError(from, to, this.id)\n    }\n  }\n\n  /**\n   * Safely update the collection status with validation\n   * @private\n   */\n  public setStatus(newStatus: CollectionStatus): void {\n    this.validateStatusTransition(this.status, newStatus)\n    const previousStatus = this.status\n    this.status = newStatus\n\n    // Resolve indexes when collection becomes ready\n    if (newStatus === `ready` && !this.indexes.isIndexesResolved) {\n      // Resolve indexes asynchronously without blocking\n      this.indexes.resolveAllIndexes().catch((error) => {\n        console.warn(`Failed to resolve indexes:`, error)\n      })\n    }\n\n    // Emit event\n    this.events.emitStatusChange(newStatus, previousStatus)\n  }\n\n  /**\n   * Validates that the collection is in a usable state for data operations\n   * @private\n   */\n  public validateCollectionUsable(operation: string): void {\n    switch (this.status) {\n      case `error`:\n        throw new CollectionInErrorStateError(operation, this.id)\n      case `cleaned-up`:\n        // Automatically restart the collection when operations are called on cleaned-up collections\n        this.sync.startSync()\n        break\n    }\n  }\n\n  /**\n   * Mark the collection as ready for use\n   * This is called by sync implementations to explicitly signal that the collection is ready,\n   * providing a more intuitive alternative to using commits for readiness signaling\n   * @private - Should only be called by sync implementations\n   */\n  public markReady(): void {\n    // Can transition to ready from loading or initialCommit states\n    if (this.status === `loading` || this.status === `initialCommit`) {\n      this.setStatus(`ready`)\n\n      // Call any registered first ready callbacks (only on first time becoming ready)\n      if (!this.hasBeenReady) {\n        this.hasBeenReady = true\n\n        // Also mark as having received first commit for backwards compatibility\n        if (!this.hasReceivedFirstCommit) {\n          this.hasReceivedFirstCommit = true\n        }\n\n        const callbacks = [...this.onFirstReadyCallbacks]\n        this.onFirstReadyCallbacks = []\n        callbacks.forEach((callback) => callback())\n      }\n    }\n\n    // Always notify dependents when markReady is called, after status is set\n    // This ensures live queries get notified when their dependencies become ready\n    if (this.changes.changeSubscriptions.size > 0) {\n      this.changes.emitEmptyReadyEvent()\n    }\n  }\n\n  /**\n   * Start the garbage collection timer\n   * Called when the collection becomes inactive (no subscribers)\n   */\n  public startGCTimer(): void {\n    if (this.gcTimeoutId) {\n      clearTimeout(this.gcTimeoutId)\n    }\n\n    const gcTime = this.config.gcTime ?? 300000 // 5 minutes default\n\n    // If gcTime is 0, GC is disabled\n    if (gcTime === 0) {\n      return\n    }\n\n    this.gcTimeoutId = setTimeout(() => {\n      if (this.changes.activeSubscribersCount === 0) {\n        // We call the main collection cleanup, not just the one for the\n        // lifecycle manager\n        this.cleanup()\n      }\n    }, gcTime)\n  }\n\n  /**\n   * Cancel the garbage collection timer\n   * Called when the collection becomes active again\n   */\n  public cancelGCTimer(): void {\n    if (this.gcTimeoutId) {\n      clearTimeout(this.gcTimeoutId)\n      this.gcTimeoutId = null\n    }\n  }\n\n  /**\n   * Register a callback to be executed when the collection first becomes ready\n   * Useful for preloading collections\n   * @param callback Function to call when the collection first becomes ready\n   */\n  public onFirstReady(callback: () => void): void {\n    // If already ready, call immediately\n    if (this.hasBeenReady) {\n      callback()\n      return\n    }\n\n    this.onFirstReadyCallbacks.push(callback)\n  }\n\n  public cleanup(): void {\n    this.events.cleanup()\n    this.sync.cleanup()\n    this.state.cleanup()\n    this.changes.cleanup()\n    this.indexes.cleanup()\n\n    if (this.gcTimeoutId) {\n      clearTimeout(this.gcTimeoutId)\n      this.gcTimeoutId = null\n    }\n\n    this.hasBeenReady = false\n    this.onFirstReadyCallbacks = []\n\n    // Set status to cleaned-up\n    this.setStatus(`cleaned-up`)\n  }\n}\n"],"names":["InvalidCollectionStatusTransitionError","CollectionInErrorStateError"],"mappings":"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"}
+{"version":3,"file":"lifecycle.cjs","sources":["../../../src/collection/lifecycle.ts"],"sourcesContent":["import {\n  CollectionInErrorStateError,\n  InvalidCollectionStatusTransitionError,\n} from \"../errors\"\nimport {\n  safeCancelIdleCallback,\n  safeRequestIdleCallback,\n} from \"../utils/browser-polyfills\"\nimport type { IdleCallbackDeadline } from \"../utils/browser-polyfills\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\nimport type { CollectionConfig, CollectionStatus } from \"../types\"\nimport type { CollectionEventsManager } from \"./events\"\nimport type { CollectionIndexesManager } from \"./indexes\"\nimport type { CollectionChangesManager } from \"./changes\"\nimport type { CollectionSyncManager } from \"./sync\"\nimport type { CollectionStateManager } from \"./state\"\n\nexport class CollectionLifecycleManager<\n  TOutput extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n  TSchema extends StandardSchemaV1 = StandardSchemaV1,\n  TInput extends object = TOutput,\n> {\n  private config: CollectionConfig<TOutput, TKey, TSchema>\n  private id: string\n  private indexes!: CollectionIndexesManager<TOutput, TKey, TSchema, TInput>\n  private events!: CollectionEventsManager\n  private changes!: CollectionChangesManager<TOutput, TKey, TSchema, TInput>\n  private sync!: CollectionSyncManager<TOutput, TKey, TSchema, TInput>\n  private state!: CollectionStateManager<TOutput, TKey, TSchema, TInput>\n\n  public status: CollectionStatus = `idle`\n  public hasBeenReady = false\n  public hasReceivedFirstCommit = false\n  public onFirstReadyCallbacks: Array<() => void> = []\n  public gcTimeoutId: ReturnType<typeof setTimeout> | null = null\n  private idleCallbackId: number | null = null\n\n  /**\n   * Creates a new CollectionLifecycleManager instance\n   */\n  constructor(config: CollectionConfig<TOutput, TKey, TSchema>, id: string) {\n    this.config = config\n    this.id = id\n  }\n\n  setDeps(deps: {\n    indexes: CollectionIndexesManager<TOutput, TKey, TSchema, TInput>\n    events: CollectionEventsManager\n    changes: CollectionChangesManager<TOutput, TKey, TSchema, TInput>\n    sync: CollectionSyncManager<TOutput, TKey, TSchema, TInput>\n    state: CollectionStateManager<TOutput, TKey, TSchema, TInput>\n  }) {\n    this.indexes = deps.indexes\n    this.events = deps.events\n    this.changes = deps.changes\n    this.sync = deps.sync\n    this.state = deps.state\n  }\n\n  /**\n   * Validates state transitions to prevent invalid status changes\n   */\n  public validateStatusTransition(\n    from: CollectionStatus,\n    to: CollectionStatus\n  ): void {\n    if (from === to) {\n      // Allow same state transitions\n      return\n    }\n    const validTransitions: Record<\n      CollectionStatus,\n      Array<CollectionStatus>\n    > = {\n      idle: [`loading`, `error`, `cleaned-up`],\n      loading: [`initialCommit`, `ready`, `error`, `cleaned-up`],\n      initialCommit: [`ready`, `error`, `cleaned-up`],\n      ready: [`cleaned-up`, `error`],\n      error: [`cleaned-up`, `idle`],\n      \"cleaned-up\": [`loading`, `error`],\n    }\n\n    if (!validTransitions[from].includes(to)) {\n      throw new InvalidCollectionStatusTransitionError(from, to, this.id)\n    }\n  }\n\n  /**\n   * Safely update the collection status with validation\n   * @private\n   */\n  public setStatus(newStatus: CollectionStatus): void {\n    this.validateStatusTransition(this.status, newStatus)\n    const previousStatus = this.status\n    this.status = newStatus\n\n    // Resolve indexes when collection becomes ready\n    if (newStatus === `ready` && !this.indexes.isIndexesResolved) {\n      // Resolve indexes asynchronously without blocking\n      this.indexes.resolveAllIndexes().catch((error) => {\n        console.warn(`Failed to resolve indexes:`, error)\n      })\n    }\n\n    // Emit event\n    this.events.emitStatusChange(newStatus, previousStatus)\n  }\n\n  /**\n   * Validates that the collection is in a usable state for data operations\n   * @private\n   */\n  public validateCollectionUsable(operation: string): void {\n    switch (this.status) {\n      case `error`:\n        throw new CollectionInErrorStateError(operation, this.id)\n      case `cleaned-up`:\n        // Automatically restart the collection when operations are called on cleaned-up collections\n        this.sync.startSync()\n        break\n    }\n  }\n\n  /**\n   * Mark the collection as ready for use\n   * This is called by sync implementations to explicitly signal that the collection is ready,\n   * providing a more intuitive alternative to using commits for readiness signaling\n   * @private - Should only be called by sync implementations\n   */\n  public markReady(): void {\n    // Can transition to ready from loading or initialCommit states\n    if (this.status === `loading` || this.status === `initialCommit`) {\n      this.setStatus(`ready`)\n\n      // Call any registered first ready callbacks (only on first time becoming ready)\n      if (!this.hasBeenReady) {\n        this.hasBeenReady = true\n\n        // Also mark as having received first commit for backwards compatibility\n        if (!this.hasReceivedFirstCommit) {\n          this.hasReceivedFirstCommit = true\n        }\n\n        const callbacks = [...this.onFirstReadyCallbacks]\n        this.onFirstReadyCallbacks = []\n        callbacks.forEach((callback) => callback())\n      }\n    }\n\n    // Always notify dependents when markReady is called, after status is set\n    // This ensures live queries get notified when their dependencies become ready\n    if (this.changes.changeSubscriptions.size > 0) {\n      this.changes.emitEmptyReadyEvent()\n    }\n  }\n\n  /**\n   * Start the garbage collection timer\n   * Called when the collection becomes inactive (no subscribers)\n   */\n  public startGCTimer(): void {\n    if (this.gcTimeoutId) {\n      clearTimeout(this.gcTimeoutId)\n    }\n\n    const gcTime = this.config.gcTime ?? 300000 // 5 minutes default\n\n    // If gcTime is 0, GC is disabled\n    if (gcTime === 0) {\n      return\n    }\n\n    this.gcTimeoutId = setTimeout(() => {\n      if (this.changes.activeSubscribersCount === 0) {\n        // Schedule cleanup during idle time to avoid blocking the UI thread\n        this.scheduleIdleCleanup()\n      }\n    }, gcTime)\n  }\n\n  /**\n   * Cancel the garbage collection timer\n   * Called when the collection becomes active again\n   */\n  public cancelGCTimer(): void {\n    if (this.gcTimeoutId) {\n      clearTimeout(this.gcTimeoutId)\n      this.gcTimeoutId = null\n    }\n    // Also cancel any pending idle cleanup\n    if (this.idleCallbackId !== null) {\n      safeCancelIdleCallback(this.idleCallbackId)\n      this.idleCallbackId = null\n    }\n  }\n\n  /**\n   * Schedule cleanup to run during browser idle time\n   * This prevents blocking the UI thread during cleanup operations\n   */\n  private scheduleIdleCleanup(): void {\n    // Cancel any existing idle callback\n    if (this.idleCallbackId !== null) {\n      safeCancelIdleCallback(this.idleCallbackId)\n    }\n\n    // Schedule cleanup with a timeout of 1 second\n    // This ensures cleanup happens even if the browser is busy\n    this.idleCallbackId = safeRequestIdleCallback(\n      (deadline) => {\n        // Perform cleanup if we still have no subscribers\n        if (this.changes.activeSubscribersCount === 0) {\n          const cleanupCompleted = this.performCleanup(deadline)\n          // Only clear the callback ID if cleanup actually completed\n          if (cleanupCompleted) {\n            this.idleCallbackId = null\n          }\n        } else {\n          // No need to cleanup, clear the callback ID\n          this.idleCallbackId = null\n        }\n      },\n      { timeout: 1000 }\n    )\n  }\n\n  /**\n   * Perform cleanup operations, optionally in chunks during idle time\n   * @returns true if cleanup was completed, false if it was rescheduled\n   */\n  private performCleanup(deadline?: IdleCallbackDeadline): boolean {\n    // If we have a deadline, we can potentially split cleanup into chunks\n    // For now, we'll do all cleanup at once but check if we have time\n    const hasTime =\n      !deadline || deadline.timeRemaining() > 0 || deadline.didTimeout\n\n    if (hasTime) {\n      // Perform all cleanup operations\n      this.events.cleanup()\n      this.sync.cleanup()\n      this.state.cleanup()\n      this.changes.cleanup()\n      this.indexes.cleanup()\n\n      if (this.gcTimeoutId) {\n        clearTimeout(this.gcTimeoutId)\n        this.gcTimeoutId = null\n      }\n\n      this.hasBeenReady = false\n      this.onFirstReadyCallbacks = []\n\n      // Set status to cleaned-up\n      this.setStatus(`cleaned-up`)\n      return true\n    } else {\n      // If we don't have time, reschedule for the next idle period\n      this.scheduleIdleCleanup()\n      return false\n    }\n  }\n\n  /**\n   * Register a callback to be executed when the collection first becomes ready\n   * Useful for preloading collections\n   * @param callback Function to call when the collection first becomes ready\n   */\n  public onFirstReady(callback: () => void): void {\n    // If already ready, call immediately\n    if (this.hasBeenReady) {\n      callback()\n      return\n    }\n\n    this.onFirstReadyCallbacks.push(callback)\n  }\n\n  public cleanup(): void {\n    // Cancel any pending idle cleanup\n    if (this.idleCallbackId !== null) {\n      safeCancelIdleCallback(this.idleCallbackId)\n      this.idleCallbackId = null\n    }\n\n    // Perform cleanup immediately (used when explicitly called)\n    this.performCleanup()\n  }\n}\n"],"names":["InvalidCollectionStatusTransitionError","CollectionInErrorStateError","safeCancelIdleCallback","safeRequestIdleCallback"],"mappings":"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"}

package/dist/cjs/collection/lifecycle.d.cts

@@ -18,6 +18,7 @@ export declare class CollectionLifecycleManager<TOutput extends object = Record<
     hasReceivedFirstCommit: boolean;
     onFirstReadyCallbacks: Array<() => void>;
     gcTimeoutId: ReturnType<typeof setTimeout> | null;
+    private idleCallbackId;
     /**
      * Creates a new CollectionLifecycleManager instance
      */
@@ -60,6 +61,16 @@ export declare class CollectionLifecycleManager<TOutput extends object = Record<
      * Called when the collection becomes active again
      */
     cancelGCTimer(): void;
+    /**
+     * Schedule cleanup to run during browser idle time
+     * This prevents blocking the UI thread during cleanup operations
+     */
+    private scheduleIdleCleanup;
+    /**
+     * Perform cleanup operations, optionally in chunks during idle time
+     * @returns true if cleanup was completed, false if it was rescheduled
+     */
+    private performCleanup;
     /**
      * Register a callback to be executed when the collection first becomes ready
      * Useful for preloading collections

package/dist/cjs/utils/browser-polyfills.cjs

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const requestIdleCallbackPolyfill = (callback) => {
+  const timeout = 0;
+  const timeoutId = setTimeout(() => {
+    callback({
+      didTimeout: true,
+      // Always indicate timeout for the polyfill
+      timeRemaining: () => 50
+      // Return some time remaining for polyfill
+    });
+  }, timeout);
+  return timeoutId;
+};
+const cancelIdleCallbackPolyfill = (id) => {
+  clearTimeout(id);
+};
+const safeRequestIdleCallback = typeof window !== `undefined` && `requestIdleCallback` in window ? (callback, options) => window.requestIdleCallback(callback, options) : (callback, _options) => requestIdleCallbackPolyfill(callback);
+const safeCancelIdleCallback = typeof window !== `undefined` && `cancelIdleCallback` in window ? (id) => window.cancelIdleCallback(id) : cancelIdleCallbackPolyfill;
+exports.safeCancelIdleCallback = safeCancelIdleCallback;
+exports.safeRequestIdleCallback = safeRequestIdleCallback;
+//# sourceMappingURL=browser-polyfills.cjs.map

package/dist/cjs/utils/browser-polyfills.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-polyfills.cjs","sources":["../../../src/utils/browser-polyfills.ts"],"sourcesContent":["// Type definitions for requestIdleCallback - compatible with existing browser types\nexport type IdleCallbackDeadline = {\n  didTimeout: boolean\n  timeRemaining: () => number\n}\n\nexport type IdleCallbackFunction = (deadline: IdleCallbackDeadline) => void\n\nconst requestIdleCallbackPolyfill = (\n  callback: IdleCallbackFunction\n): number => {\n  // Use a very small timeout for the polyfill to simulate idle time\n  const timeout = 0\n  const timeoutId = setTimeout(() => {\n    callback({\n      didTimeout: true, // Always indicate timeout for the polyfill\n      timeRemaining: () => 50, // Return some time remaining for polyfill\n    })\n  }, timeout)\n  return timeoutId as unknown as number\n}\n\nconst cancelIdleCallbackPolyfill = (id: number): void => {\n  clearTimeout(id as unknown as ReturnType<typeof setTimeout>)\n}\n\nexport const safeRequestIdleCallback: (\n  callback: IdleCallbackFunction,\n  options?: { timeout?: number }\n) => number =\n  typeof window !== `undefined` && `requestIdleCallback` in window\n    ? (callback, options) =>\n        (window as any).requestIdleCallback(callback, options)\n    : (callback, _options) => requestIdleCallbackPolyfill(callback)\n\nexport const safeCancelIdleCallback: (id: number) => void =\n  typeof window !== `undefined` && `cancelIdleCallback` in window\n    ? (id) => (window as any).cancelIdleCallback(id)\n    : cancelIdleCallbackPolyfill\n"],"names":[],"mappings":";;AAQA,MAAM,8BAA8B,CAClC,aACW;AAEX,QAAM,UAAU;AAChB,QAAM,YAAY,WAAW,MAAM;AACjC,aAAS;AAAA,MACP,YAAY;AAAA;AAAA,MACZ,eAAe,MAAM;AAAA;AAAA,IAAA,CACtB;AAAA,EACH,GAAG,OAAO;AACV,SAAO;AACT;AAEA,MAAM,6BAA6B,CAAC,OAAqB;AACvD,eAAa,EAA8C;AAC7D;AAEO,MAAM,0BAIX,OAAO,WAAW,eAAe,yBAAyB,SACtD,CAAC,UAAU,YACR,OAAe,oBAAoB,UAAU,OAAO,IACvD,CAAC,UAAU,aAAa,4BAA4B,QAAQ;AAE3D,MAAM,yBACX,OAAO,WAAW,eAAe,wBAAwB,SACrD,CAAC,OAAQ,OAAe,mBAAmB,EAAE,IAC7C;;;"}

package/dist/cjs/utils/browser-polyfills.d.cts

@@ -0,0 +1,9 @@
+export type IdleCallbackDeadline = {
+    didTimeout: boolean;
+    timeRemaining: () => number;
+};
+export type IdleCallbackFunction = (deadline: IdleCallbackDeadline) => void;
+export declare const safeRequestIdleCallback: (callback: IdleCallbackFunction, options?: {
+    timeout?: number;
+}) => number;
+export declare const safeCancelIdleCallback: (id: number) => void;

package/dist/esm/collection/lifecycle.d.ts

@@ -18,6 +18,7 @@ export declare class CollectionLifecycleManager<TOutput extends object = Record<
     hasReceivedFirstCommit: boolean;
     onFirstReadyCallbacks: Array<() => void>;
     gcTimeoutId: ReturnType<typeof setTimeout> | null;
+    private idleCallbackId;
     /**
      * Creates a new CollectionLifecycleManager instance
      */
@@ -60,6 +61,16 @@ export declare class CollectionLifecycleManager<TOutput extends object = Record<
      * Called when the collection becomes active again
      */
     cancelGCTimer(): void;
+    /**
+     * Schedule cleanup to run during browser idle time
+     * This prevents blocking the UI thread during cleanup operations
+     */
+    private scheduleIdleCleanup;
+    /**
+     * Perform cleanup operations, optionally in chunks during idle time
+     * @returns true if cleanup was completed, false if it was rescheduled
+     */
+    private performCleanup;
     /**
      * Register a callback to be executed when the collection first becomes ready
      * Useful for preloading collections

package/dist/esm/collection/lifecycle.js

@@ -1,4 +1,5 @@
 import { InvalidCollectionStatusTransitionError, CollectionInErrorStateError } from "../errors.js";
+import { safeCancelIdleCallback, safeRequestIdleCallback } from "../utils/browser-polyfills.js";
 class CollectionLifecycleManager {
   /**
    * Creates a new CollectionLifecycleManager instance
@@ -9,6 +10,7 @@ class CollectionLifecycleManager {
     this.hasReceivedFirstCommit = false;
     this.onFirstReadyCallbacks = [];
     this.gcTimeoutId = null;
+    this.idleCallbackId = null;
     this.config = config;
     this.id = id;
   }
@@ -103,7 +105,7 @@ class CollectionLifecycleManager {
     }
     this.gcTimeoutId = setTimeout(() => {
       if (this.changes.activeSubscribersCount === 0) {
-        this.cleanup();
+        this.scheduleIdleCleanup();
       }
     }, gcTime);
   }
@@ -116,6 +118,57 @@ class CollectionLifecycleManager {
       clearTimeout(this.gcTimeoutId);
       this.gcTimeoutId = null;
     }
+    if (this.idleCallbackId !== null) {
+      safeCancelIdleCallback(this.idleCallbackId);
+      this.idleCallbackId = null;
+    }
+  }
+  /**
+   * Schedule cleanup to run during browser idle time
+   * This prevents blocking the UI thread during cleanup operations
+   */
+  scheduleIdleCleanup() {
+    if (this.idleCallbackId !== null) {
+      safeCancelIdleCallback(this.idleCallbackId);
+    }
+    this.idleCallbackId = safeRequestIdleCallback(
+      (deadline) => {
+        if (this.changes.activeSubscribersCount === 0) {
+          const cleanupCompleted = this.performCleanup(deadline);
+          if (cleanupCompleted) {
+            this.idleCallbackId = null;
+          }
+        } else {
+          this.idleCallbackId = null;
+        }
+      },
+      { timeout: 1e3 }
+    );
+  }
+  /**
+   * Perform cleanup operations, optionally in chunks during idle time
+   * @returns true if cleanup was completed, false if it was rescheduled
+   */
+  performCleanup(deadline) {
+    const hasTime = !deadline || deadline.timeRemaining() > 0 || deadline.didTimeout;
+    if (hasTime) {
+      this.events.cleanup();
+      this.sync.cleanup();
+      this.state.cleanup();
+      this.changes.cleanup();
+      this.indexes.cleanup();
+      if (this.gcTimeoutId) {
+        clearTimeout(this.gcTimeoutId);
+        this.gcTimeoutId = null;
+      }
+      this.hasBeenReady = false;
+      this.onFirstReadyCallbacks = [];
+      this.setStatus(`cleaned-up`);
+      return true;
+    } else {
+      this.scheduleIdleCleanup();
+      return false;
+    }
   }
   /**
    * Register a callback to be executed when the collection first becomes ready
@@ -130,18 +183,11 @@ class CollectionLifecycleManager {
     this.onFirstReadyCallbacks.push(callback);
   }
   cleanup() {
-    this.events.cleanup();
-    this.sync.cleanup();
-    this.state.cleanup();
-    this.changes.cleanup();
-    this.indexes.cleanup();
-    if (this.gcTimeoutId) {
-      clearTimeout(this.gcTimeoutId);
-      this.gcTimeoutId = null;
+    if (this.idleCallbackId !== null) {
+      safeCancelIdleCallback(this.idleCallbackId);
+      this.idleCallbackId = null;
     }
-    this.hasBeenReady = false;
-    this.onFirstReadyCallbacks = [];
-    this.setStatus(`cleaned-up`);
+    this.performCleanup();
   }
 }
 export {

package/dist/esm/collection/lifecycle.js.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle.js","sources":["../../../src/collection/lifecycle.ts"],"sourcesContent":["import {\n  CollectionInErrorStateError,\n  InvalidCollectionStatusTransitionError,\n} from \"../errors\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\nimport type { CollectionConfig, CollectionStatus } from \"../types\"\nimport type { CollectionEventsManager } from \"./events\"\nimport type { CollectionIndexesManager } from \"./indexes\"\nimport type { CollectionChangesManager } from \"./changes\"\nimport type { CollectionSyncManager } from \"./sync\"\nimport type { CollectionStateManager } from \"./state\"\n\nexport class CollectionLifecycleManager<\n  TOutput extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n  TSchema extends StandardSchemaV1 = StandardSchemaV1,\n  TInput extends object = TOutput,\n> {\n  private config: CollectionConfig<TOutput, TKey, TSchema>\n  private id: string\n  private indexes!: CollectionIndexesManager<TOutput, TKey, TSchema, TInput>\n  private events!: CollectionEventsManager\n  private changes!: CollectionChangesManager<TOutput, TKey, TSchema, TInput>\n  private sync!: CollectionSyncManager<TOutput, TKey, TSchema, TInput>\n  private state!: CollectionStateManager<TOutput, TKey, TSchema, TInput>\n\n  public status: CollectionStatus = `idle`\n  public hasBeenReady = false\n  public hasReceivedFirstCommit = false\n  public onFirstReadyCallbacks: Array<() => void> = []\n  public gcTimeoutId: ReturnType<typeof setTimeout> | null = null\n\n  /**\n   * Creates a new CollectionLifecycleManager instance\n   */\n  constructor(config: CollectionConfig<TOutput, TKey, TSchema>, id: string) {\n    this.config = config\n    this.id = id\n  }\n\n  setDeps(deps: {\n    indexes: CollectionIndexesManager<TOutput, TKey, TSchema, TInput>\n    events: CollectionEventsManager\n    changes: CollectionChangesManager<TOutput, TKey, TSchema, TInput>\n    sync: CollectionSyncManager<TOutput, TKey, TSchema, TInput>\n    state: CollectionStateManager<TOutput, TKey, TSchema, TInput>\n  }) {\n    this.indexes = deps.indexes\n    this.events = deps.events\n    this.changes = deps.changes\n    this.sync = deps.sync\n    this.state = deps.state\n  }\n\n  /**\n   * Validates state transitions to prevent invalid status changes\n   */\n  public validateStatusTransition(\n    from: CollectionStatus,\n    to: CollectionStatus\n  ): void {\n    if (from === to) {\n      // Allow same state transitions\n      return\n    }\n    const validTransitions: Record<\n      CollectionStatus,\n      Array<CollectionStatus>\n    > = {\n      idle: [`loading`, `error`, `cleaned-up`],\n      loading: [`initialCommit`, `ready`, `error`, `cleaned-up`],\n      initialCommit: [`ready`, `error`, `cleaned-up`],\n      ready: [`cleaned-up`, `error`],\n      error: [`cleaned-up`, `idle`],\n      \"cleaned-up\": [`loading`, `error`],\n    }\n\n    if (!validTransitions[from].includes(to)) {\n      throw new InvalidCollectionStatusTransitionError(from, to, this.id)\n    }\n  }\n\n  /**\n   * Safely update the collection status with validation\n   * @private\n   */\n  public setStatus(newStatus: CollectionStatus): void {\n    this.validateStatusTransition(this.status, newStatus)\n    const previousStatus = this.status\n    this.status = newStatus\n\n    // Resolve indexes when collection becomes ready\n    if (newStatus === `ready` && !this.indexes.isIndexesResolved) {\n      // Resolve indexes asynchronously without blocking\n      this.indexes.resolveAllIndexes().catch((error) => {\n        console.warn(`Failed to resolve indexes:`, error)\n      })\n    }\n\n    // Emit event\n    this.events.emitStatusChange(newStatus, previousStatus)\n  }\n\n  /**\n   * Validates that the collection is in a usable state for data operations\n   * @private\n   */\n  public validateCollectionUsable(operation: string): void {\n    switch (this.status) {\n      case `error`:\n        throw new CollectionInErrorStateError(operation, this.id)\n      case `cleaned-up`:\n        // Automatically restart the collection when operations are called on cleaned-up collections\n        this.sync.startSync()\n        break\n    }\n  }\n\n  /**\n   * Mark the collection as ready for use\n   * This is called by sync implementations to explicitly signal that the collection is ready,\n   * providing a more intuitive alternative to using commits for readiness signaling\n   * @private - Should only be called by sync implementations\n   */\n  public markReady(): void {\n    // Can transition to ready from loading or initialCommit states\n    if (this.status === `loading` || this.status === `initialCommit`) {\n      this.setStatus(`ready`)\n\n      // Call any registered first ready callbacks (only on first time becoming ready)\n      if (!this.hasBeenReady) {\n        this.hasBeenReady = true\n\n        // Also mark as having received first commit for backwards compatibility\n        if (!this.hasReceivedFirstCommit) {\n          this.hasReceivedFirstCommit = true\n        }\n\n        const callbacks = [...this.onFirstReadyCallbacks]\n        this.onFirstReadyCallbacks = []\n        callbacks.forEach((callback) => callback())\n      }\n    }\n\n    // Always notify dependents when markReady is called, after status is set\n    // This ensures live queries get notified when their dependencies become ready\n    if (this.changes.changeSubscriptions.size > 0) {\n      this.changes.emitEmptyReadyEvent()\n    }\n  }\n\n  /**\n   * Start the garbage collection timer\n   * Called when the collection becomes inactive (no subscribers)\n   */\n  public startGCTimer(): void {\n    if (this.gcTimeoutId) {\n      clearTimeout(this.gcTimeoutId)\n    }\n\n    const gcTime = this.config.gcTime ?? 300000 // 5 minutes default\n\n    // If gcTime is 0, GC is disabled\n    if (gcTime === 0) {\n      return\n    }\n\n    this.gcTimeoutId = setTimeout(() => {\n      if (this.changes.activeSubscribersCount === 0) {\n        // We call the main collection cleanup, not just the one for the\n        // lifecycle manager\n        this.cleanup()\n      }\n    }, gcTime)\n  }\n\n  /**\n   * Cancel the garbage collection timer\n   * Called when the collection becomes active again\n   */\n  public cancelGCTimer(): void {\n    if (this.gcTimeoutId) {\n      clearTimeout(this.gcTimeoutId)\n      this.gcTimeoutId = null\n    }\n  }\n\n  /**\n   * Register a callback to be executed when the collection first becomes ready\n   * Useful for preloading collections\n   * @param callback Function to call when the collection first becomes ready\n   */\n  public onFirstReady(callback: () => void): void {\n    // If already ready, call immediately\n    if (this.hasBeenReady) {\n      callback()\n      return\n    }\n\n    this.onFirstReadyCallbacks.push(callback)\n  }\n\n  public cleanup(): void {\n    this.events.cleanup()\n    this.sync.cleanup()\n    this.state.cleanup()\n    this.changes.cleanup()\n    this.indexes.cleanup()\n\n    if (this.gcTimeoutId) {\n      clearTimeout(this.gcTimeoutId)\n      this.gcTimeoutId = null\n    }\n\n    this.hasBeenReady = false\n    this.onFirstReadyCallbacks = []\n\n    // Set status to cleaned-up\n    this.setStatus(`cleaned-up`)\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"lifecycle.js","sources":["../../../src/collection/lifecycle.ts"],"sourcesContent":["import {\n  CollectionInErrorStateError,\n  InvalidCollectionStatusTransitionError,\n} from \"../errors\"\nimport {\n  safeCancelIdleCallback,\n  safeRequestIdleCallback,\n} from \"../utils/browser-polyfills\"\nimport type { IdleCallbackDeadline } from \"../utils/browser-polyfills\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\nimport type { CollectionConfig, CollectionStatus } from \"../types\"\nimport type { CollectionEventsManager } from \"./events\"\nimport type { CollectionIndexesManager } from \"./indexes\"\nimport type { CollectionChangesManager } from \"./changes\"\nimport type { CollectionSyncManager } from \"./sync\"\nimport type { CollectionStateManager } from \"./state\"\n\nexport class CollectionLifecycleManager<\n  TOutput extends object = Record<string, unknown>,\n  TKey extends string | number = string | number,\n  TSchema extends StandardSchemaV1 = StandardSchemaV1,\n  TInput extends object = TOutput,\n> {\n  private config: CollectionConfig<TOutput, TKey, TSchema>\n  private id: string\n  private indexes!: CollectionIndexesManager<TOutput, TKey, TSchema, TInput>\n  private events!: CollectionEventsManager\n  private changes!: CollectionChangesManager<TOutput, TKey, TSchema, TInput>\n  private sync!: CollectionSyncManager<TOutput, TKey, TSchema, TInput>\n  private state!: CollectionStateManager<TOutput, TKey, TSchema, TInput>\n\n  public status: CollectionStatus = `idle`\n  public hasBeenReady = false\n  public hasReceivedFirstCommit = false\n  public onFirstReadyCallbacks: Array<() => void> = []\n  public gcTimeoutId: ReturnType<typeof setTimeout> | null = null\n  private idleCallbackId: number | null = null\n\n  /**\n   * Creates a new CollectionLifecycleManager instance\n   */\n  constructor(config: CollectionConfig<TOutput, TKey, TSchema>, id: string) {\n    this.config = config\n    this.id = id\n  }\n\n  setDeps(deps: {\n    indexes: CollectionIndexesManager<TOutput, TKey, TSchema, TInput>\n    events: CollectionEventsManager\n    changes: CollectionChangesManager<TOutput, TKey, TSchema, TInput>\n    sync: CollectionSyncManager<TOutput, TKey, TSchema, TInput>\n    state: CollectionStateManager<TOutput, TKey, TSchema, TInput>\n  }) {\n    this.indexes = deps.indexes\n    this.events = deps.events\n    this.changes = deps.changes\n    this.sync = deps.sync\n    this.state = deps.state\n  }\n\n  /**\n   * Validates state transitions to prevent invalid status changes\n   */\n  public validateStatusTransition(\n    from: CollectionStatus,\n    to: CollectionStatus\n  ): void {\n    if (from === to) {\n      // Allow same state transitions\n      return\n    }\n    const validTransitions: Record<\n      CollectionStatus,\n      Array<CollectionStatus>\n    > = {\n      idle: [`loading`, `error`, `cleaned-up`],\n      loading: [`initialCommit`, `ready`, `error`, `cleaned-up`],\n      initialCommit: [`ready`, `error`, `cleaned-up`],\n      ready: [`cleaned-up`, `error`],\n      error: [`cleaned-up`, `idle`],\n      \"cleaned-up\": [`loading`, `error`],\n    }\n\n    if (!validTransitions[from].includes(to)) {\n      throw new InvalidCollectionStatusTransitionError(from, to, this.id)\n    }\n  }\n\n  /**\n   * Safely update the collection status with validation\n   * @private\n   */\n  public setStatus(newStatus: CollectionStatus): void {\n    this.validateStatusTransition(this.status, newStatus)\n    const previousStatus = this.status\n    this.status = newStatus\n\n    // Resolve indexes when collection becomes ready\n    if (newStatus === `ready` && !this.indexes.isIndexesResolved) {\n      // Resolve indexes asynchronously without blocking\n      this.indexes.resolveAllIndexes().catch((error) => {\n        console.warn(`Failed to resolve indexes:`, error)\n      })\n    }\n\n    // Emit event\n    this.events.emitStatusChange(newStatus, previousStatus)\n  }\n\n  /**\n   * Validates that the collection is in a usable state for data operations\n   * @private\n   */\n  public validateCollectionUsable(operation: string): void {\n    switch (this.status) {\n      case `error`:\n        throw new CollectionInErrorStateError(operation, this.id)\n      case `cleaned-up`:\n        // Automatically restart the collection when operations are called on cleaned-up collections\n        this.sync.startSync()\n        break\n    }\n  }\n\n  /**\n   * Mark the collection as ready for use\n   * This is called by sync implementations to explicitly signal that the collection is ready,\n   * providing a more intuitive alternative to using commits for readiness signaling\n   * @private - Should only be called by sync implementations\n   */\n  public markReady(): void {\n    // Can transition to ready from loading or initialCommit states\n    if (this.status === `loading` || this.status === `initialCommit`) {\n      this.setStatus(`ready`)\n\n      // Call any registered first ready callbacks (only on first time becoming ready)\n      if (!this.hasBeenReady) {\n        this.hasBeenReady = true\n\n        // Also mark as having received first commit for backwards compatibility\n        if (!this.hasReceivedFirstCommit) {\n          this.hasReceivedFirstCommit = true\n        }\n\n        const callbacks = [...this.onFirstReadyCallbacks]\n        this.onFirstReadyCallbacks = []\n        callbacks.forEach((callback) => callback())\n      }\n    }\n\n    // Always notify dependents when markReady is called, after status is set\n    // This ensures live queries get notified when their dependencies become ready\n    if (this.changes.changeSubscriptions.size > 0) {\n      this.changes.emitEmptyReadyEvent()\n    }\n  }\n\n  /**\n   * Start the garbage collection timer\n   * Called when the collection becomes inactive (no subscribers)\n   */\n  public startGCTimer(): void {\n    if (this.gcTimeoutId) {\n      clearTimeout(this.gcTimeoutId)\n    }\n\n    const gcTime = this.config.gcTime ?? 300000 // 5 minutes default\n\n    // If gcTime is 0, GC is disabled\n    if (gcTime === 0) {\n      return\n    }\n\n    this.gcTimeoutId = setTimeout(() => {\n      if (this.changes.activeSubscribersCount === 0) {\n        // Schedule cleanup during idle time to avoid blocking the UI thread\n        this.scheduleIdleCleanup()\n      }\n    }, gcTime)\n  }\n\n  /**\n   * Cancel the garbage collection timer\n   * Called when the collection becomes active again\n   */\n  public cancelGCTimer(): void {\n    if (this.gcTimeoutId) {\n      clearTimeout(this.gcTimeoutId)\n      this.gcTimeoutId = null\n    }\n    // Also cancel any pending idle cleanup\n    if (this.idleCallbackId !== null) {\n      safeCancelIdleCallback(this.idleCallbackId)\n      this.idleCallbackId = null\n    }\n  }\n\n  /**\n   * Schedule cleanup to run during browser idle time\n   * This prevents blocking the UI thread during cleanup operations\n   */\n  private scheduleIdleCleanup(): void {\n    // Cancel any existing idle callback\n    if (this.idleCallbackId !== null) {\n      safeCancelIdleCallback(this.idleCallbackId)\n    }\n\n    // Schedule cleanup with a timeout of 1 second\n    // This ensures cleanup happens even if the browser is busy\n    this.idleCallbackId = safeRequestIdleCallback(\n      (deadline) => {\n        // Perform cleanup if we still have no subscribers\n        if (this.changes.activeSubscribersCount === 0) {\n          const cleanupCompleted = this.performCleanup(deadline)\n          // Only clear the callback ID if cleanup actually completed\n          if (cleanupCompleted) {\n            this.idleCallbackId = null\n          }\n        } else {\n          // No need to cleanup, clear the callback ID\n          this.idleCallbackId = null\n        }\n      },\n      { timeout: 1000 }\n    )\n  }\n\n  /**\n   * Perform cleanup operations, optionally in chunks during idle time\n   * @returns true if cleanup was completed, false if it was rescheduled\n   */\n  private performCleanup(deadline?: IdleCallbackDeadline): boolean {\n    // If we have a deadline, we can potentially split cleanup into chunks\n    // For now, we'll do all cleanup at once but check if we have time\n    const hasTime =\n      !deadline || deadline.timeRemaining() > 0 || deadline.didTimeout\n\n    if (hasTime) {\n      // Perform all cleanup operations\n      this.events.cleanup()\n      this.sync.cleanup()\n      this.state.cleanup()\n      this.changes.cleanup()\n      this.indexes.cleanup()\n\n      if (this.gcTimeoutId) {\n        clearTimeout(this.gcTimeoutId)\n        this.gcTimeoutId = null\n      }\n\n      this.hasBeenReady = false\n      this.onFirstReadyCallbacks = []\n\n      // Set status to cleaned-up\n      this.setStatus(`cleaned-up`)\n      return true\n    } else {\n      // If we don't have time, reschedule for the next idle period\n      this.scheduleIdleCleanup()\n      return false\n    }\n  }\n\n  /**\n   * Register a callback to be executed when the collection first becomes ready\n   * Useful for preloading collections\n   * @param callback Function to call when the collection first becomes ready\n   */\n  public onFirstReady(callback: () => void): void {\n    // If already ready, call immediately\n    if (this.hasBeenReady) {\n      callback()\n      return\n    }\n\n    this.onFirstReadyCallbacks.push(callback)\n  }\n\n  public cleanup(): void {\n    // Cancel any pending idle cleanup\n    if (this.idleCallbackId !== null) {\n      safeCancelIdleCallback(this.idleCallbackId)\n      this.idleCallbackId = null\n    }\n\n    // Perform cleanup immediately (used when explicitly called)\n    this.performCleanup()\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/utils/browser-polyfills.d.ts

@@ -0,0 +1,9 @@
+export type IdleCallbackDeadline = {
+    didTimeout: boolean;
+    timeRemaining: () => number;
+};
+export type IdleCallbackFunction = (deadline: IdleCallbackDeadline) => void;
+export declare const safeRequestIdleCallback: (callback: IdleCallbackFunction, options?: {
+    timeout?: number;
+}) => number;
+export declare const safeCancelIdleCallback: (id: number) => void;

package/dist/esm/utils/browser-polyfills.js

@@ -0,0 +1,22 @@
+const requestIdleCallbackPolyfill = (callback) => {
+  const timeout = 0;
+  const timeoutId = setTimeout(() => {
+    callback({
+      didTimeout: true,
+      // Always indicate timeout for the polyfill
+      timeRemaining: () => 50
+      // Return some time remaining for polyfill
+    });
+  }, timeout);
+  return timeoutId;
+};
+const cancelIdleCallbackPolyfill = (id) => {
+  clearTimeout(id);
+};
+const safeRequestIdleCallback = typeof window !== `undefined` && `requestIdleCallback` in window ? (callback, options) => window.requestIdleCallback(callback, options) : (callback, _options) => requestIdleCallbackPolyfill(callback);
+const safeCancelIdleCallback = typeof window !== `undefined` && `cancelIdleCallback` in window ? (id) => window.cancelIdleCallback(id) : cancelIdleCallbackPolyfill;
+export {
+  safeCancelIdleCallback,
+  safeRequestIdleCallback
+};
+//# sourceMappingURL=browser-polyfills.js.map

package/dist/esm/utils/browser-polyfills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-polyfills.js","sources":["../../../src/utils/browser-polyfills.ts"],"sourcesContent":["// Type definitions for requestIdleCallback - compatible with existing browser types\nexport type IdleCallbackDeadline = {\n  didTimeout: boolean\n  timeRemaining: () => number\n}\n\nexport type IdleCallbackFunction = (deadline: IdleCallbackDeadline) => void\n\nconst requestIdleCallbackPolyfill = (\n  callback: IdleCallbackFunction\n): number => {\n  // Use a very small timeout for the polyfill to simulate idle time\n  const timeout = 0\n  const timeoutId = setTimeout(() => {\n    callback({\n      didTimeout: true, // Always indicate timeout for the polyfill\n      timeRemaining: () => 50, // Return some time remaining for polyfill\n    })\n  }, timeout)\n  return timeoutId as unknown as number\n}\n\nconst cancelIdleCallbackPolyfill = (id: number): void => {\n  clearTimeout(id as unknown as ReturnType<typeof setTimeout>)\n}\n\nexport const safeRequestIdleCallback: (\n  callback: IdleCallbackFunction,\n  options?: { timeout?: number }\n) => number =\n  typeof window !== `undefined` && `requestIdleCallback` in window\n    ? (callback, options) =>\n        (window as any).requestIdleCallback(callback, options)\n    : (callback, _options) => requestIdleCallbackPolyfill(callback)\n\nexport const safeCancelIdleCallback: (id: number) => void =\n  typeof window !== `undefined` && `cancelIdleCallback` in window\n    ? (id) => (window as any).cancelIdleCallback(id)\n    : cancelIdleCallbackPolyfill\n"],"names":[],"mappings":"AAQA,MAAM,8BAA8B,CAClC,aACW;AAEX,QAAM,UAAU;AAChB,QAAM,YAAY,WAAW,MAAM;AACjC,aAAS;AAAA,MACP,YAAY;AAAA;AAAA,MACZ,eAAe,MAAM;AAAA;AAAA,IAAA,CACtB;AAAA,EACH,GAAG,OAAO;AACV,SAAO;AACT;AAEA,MAAM,6BAA6B,CAAC,OAAqB;AACvD,eAAa,EAA8C;AAC7D;AAEO,MAAM,0BAIX,OAAO,WAAW,eAAe,yBAAyB,SACtD,CAAC,UAAU,YACR,OAAe,oBAAoB,UAAU,OAAO,IACvD,CAAC,UAAU,aAAa,4BAA4B,QAAQ;AAE3D,MAAM,yBACX,OAAO,WAAW,eAAe,wBAAwB,SACrD,CAAC,OAAQ,OAAe,mBAAmB,EAAE,IAC7C;"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tanstack/db",
   "description": "A reactive client store for building super fast apps on sync",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "dependencies": {
     "@standard-schema/spec": "^1.0.0",
     "@tanstack/db-ivm": "0.1.8"

package/src/collection/lifecycle.ts

@@ -2,6 +2,11 @@ import {
   CollectionInErrorStateError,
   InvalidCollectionStatusTransitionError,
 } from "../errors"
+import {
+  safeCancelIdleCallback,
+  safeRequestIdleCallback,
+} from "../utils/browser-polyfills"
+import type { IdleCallbackDeadline } from "../utils/browser-polyfills"
 import type { StandardSchemaV1 } from "@standard-schema/spec"
 import type { CollectionConfig, CollectionStatus } from "../types"
 import type { CollectionEventsManager } from "./events"
@@ -29,6 +34,7 @@ export class CollectionLifecycleManager<
   public hasReceivedFirstCommit = false
   public onFirstReadyCallbacks: Array<() => void> = []
   public gcTimeoutId: ReturnType<typeof setTimeout> | null = null
+  private idleCallbackId: number | null = null
 
   /**
    * Creates a new CollectionLifecycleManager instance
@@ -167,9 +173,8 @@ export class CollectionLifecycleManager<
 
     this.gcTimeoutId = setTimeout(() => {
       if (this.changes.activeSubscribersCount === 0) {
-        // We call the main collection cleanup, not just the one for the
-        // lifecycle manager
-        this.cleanup()
+        // Schedule cleanup during idle time to avoid blocking the UI thread
+        this.scheduleIdleCleanup()
       }
     }, gcTime)
   }
@@ -183,6 +188,77 @@ export class CollectionLifecycleManager<
       clearTimeout(this.gcTimeoutId)
       this.gcTimeoutId = null
     }
+    // Also cancel any pending idle cleanup
+    if (this.idleCallbackId !== null) {
+      safeCancelIdleCallback(this.idleCallbackId)
+      this.idleCallbackId = null
+    }
+  }
+
+  /**
+   * Schedule cleanup to run during browser idle time
+   * This prevents blocking the UI thread during cleanup operations
+   */
+  private scheduleIdleCleanup(): void {
+    // Cancel any existing idle callback
+    if (this.idleCallbackId !== null) {
+      safeCancelIdleCallback(this.idleCallbackId)
+    }
+
+    // Schedule cleanup with a timeout of 1 second
+    // This ensures cleanup happens even if the browser is busy
+    this.idleCallbackId = safeRequestIdleCallback(
+      (deadline) => {
+        // Perform cleanup if we still have no subscribers
+        if (this.changes.activeSubscribersCount === 0) {
+          const cleanupCompleted = this.performCleanup(deadline)
+          // Only clear the callback ID if cleanup actually completed
+          if (cleanupCompleted) {
+            this.idleCallbackId = null
+          }
+        } else {
+          // No need to cleanup, clear the callback ID
+          this.idleCallbackId = null
+        }
+      },
+      { timeout: 1000 }
+    )
+  }
+
+  /**
+   * Perform cleanup operations, optionally in chunks during idle time
+   * @returns true if cleanup was completed, false if it was rescheduled
+   */
+  private performCleanup(deadline?: IdleCallbackDeadline): boolean {
+    // If we have a deadline, we can potentially split cleanup into chunks
+    // For now, we'll do all cleanup at once but check if we have time
+    const hasTime =
+      !deadline || deadline.timeRemaining() > 0 || deadline.didTimeout
+
+    if (hasTime) {
+      // Perform all cleanup operations
+      this.events.cleanup()
+      this.sync.cleanup()
+      this.state.cleanup()
+      this.changes.cleanup()
+      this.indexes.cleanup()
+
+      if (this.gcTimeoutId) {
+        clearTimeout(this.gcTimeoutId)
+        this.gcTimeoutId = null
+      }
+
+      this.hasBeenReady = false
+      this.onFirstReadyCallbacks = []
+
+      // Set status to cleaned-up
+      this.setStatus(`cleaned-up`)
+      return true
+    } else {
+      // If we don't have time, reschedule for the next idle period
+      this.scheduleIdleCleanup()
+      return false
+    }
   }
 
   /**
@@ -201,21 +277,13 @@ export class CollectionLifecycleManager<
   }
 
   public cleanup(): void {
-    this.events.cleanup()
-    this.sync.cleanup()
-    this.state.cleanup()
-    this.changes.cleanup()
-    this.indexes.cleanup()
-
-    if (this.gcTimeoutId) {
-      clearTimeout(this.gcTimeoutId)
-      this.gcTimeoutId = null
+    // Cancel any pending idle cleanup
+    if (this.idleCallbackId !== null) {
+      safeCancelIdleCallback(this.idleCallbackId)
+      this.idleCallbackId = null
     }
 
-    this.hasBeenReady = false
-    this.onFirstReadyCallbacks = []
-
-    // Set status to cleaned-up
-    this.setStatus(`cleaned-up`)
+    // Perform cleanup immediately (used when explicitly called)
+    this.performCleanup()
   }
 }

package/src/utils/browser-polyfills.ts

@@ -0,0 +1,39 @@
+// Type definitions for requestIdleCallback - compatible with existing browser types
+export type IdleCallbackDeadline = {
+  didTimeout: boolean
+  timeRemaining: () => number
+}
+
+export type IdleCallbackFunction = (deadline: IdleCallbackDeadline) => void
+
+const requestIdleCallbackPolyfill = (
+  callback: IdleCallbackFunction
+): number => {
+  // Use a very small timeout for the polyfill to simulate idle time
+  const timeout = 0
+  const timeoutId = setTimeout(() => {
+    callback({
+      didTimeout: true, // Always indicate timeout for the polyfill
+      timeRemaining: () => 50, // Return some time remaining for polyfill
+    })
+  }, timeout)
+  return timeoutId as unknown as number
+}
+
+const cancelIdleCallbackPolyfill = (id: number): void => {
+  clearTimeout(id as unknown as ReturnType<typeof setTimeout>)
+}
+
+export const safeRequestIdleCallback: (
+  callback: IdleCallbackFunction,
+  options?: { timeout?: number }
+) => number =
+  typeof window !== `undefined` && `requestIdleCallback` in window
+    ? (callback, options) =>
+        (window as any).requestIdleCallback(callback, options)
+    : (callback, _options) => requestIdleCallbackPolyfill(callback)
+
+export const safeCancelIdleCallback: (id: number) => void =
+  typeof window !== `undefined` && `cancelIdleCallback` in window
+    ? (id) => (window as any).cancelIdleCallback(id)
+    : cancelIdleCallbackPolyfill