@tanstack/db 0.3.0 → 0.3.2

package/dist/cjs/collection.d.cts

@@ -1,6 +1,7 @@
 import { SortedMap } from './SortedMap.cjs';
 import { BTreeIndex } from './indexes/btree-index.js';
 import { IndexProxy } from './indexes/lazy-index.js';
+import { AllCollectionEvents, CollectionEventHandler } from './collection-events.js';
 import { Transaction } from './transactions.cjs';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { SingleRowRefProxy } from './query/builder/ref-proxy.cjs';
@@ -131,6 +132,7 @@ export declare class CollectionImpl<TOutput extends object = Record<string, unkn
     private gcTimeoutId;
     private preloadPromise;
     private syncCleanupFn;
+    private events;
     /**
      * Register a callback to be executed when the collection first becomes ready
      * Useful for preloading collections
@@ -167,6 +169,10 @@ export declare class CollectionImpl<TOutput extends object = Record<string, unkn
      * Gets the current status of the collection
      */
     get status(): CollectionStatus;
+    /**
+     * Get the number of subscribers to the collection
+     */
+    get subscriberCount(): number;
     /**
      * Validates that the collection is in a usable state for data operations
      * @private
@@ -575,5 +581,21 @@ export declare class CollectionImpl<TOutput extends object = Record<string, unkn
      * This method should be called by the Transaction class when state changes
      */
     onTransactionStateChange(): void;
+    /**
+     * Subscribe to a collection event
+     */
+    on<T extends keyof AllCollectionEvents>(event: T, callback: CollectionEventHandler<T>): () => void;
+    /**
+     * Subscribe to a collection event once
+     */
+    once<T extends keyof AllCollectionEvents>(event: T, callback: CollectionEventHandler<T>): () => void;
+    /**
+     * Unsubscribe from a collection event
+     */
+    off<T extends keyof AllCollectionEvents>(event: T, callback: CollectionEventHandler<T>): void;
+    /**
+     * Wait for a collection event
+     */
+    waitFor<T extends keyof AllCollectionEvents>(event: T, timeout?: number): Promise<AllCollectionEvents[T]>;
 }
 export {};

package/dist/esm/collection-events.d.ts

@@ -0,0 +1,50 @@
+import { Collection } from './collection.js';
+import { CollectionStatus } from './types.js';
+/**
+ * Event emitted when the collection status changes
+ */
+export interface CollectionStatusChangeEvent {
+    type: `status:change`;
+    collection: Collection;
+    previousStatus: CollectionStatus;
+    status: CollectionStatus;
+}
+/**
+ * Event emitted when the collection status changes to a specific status
+ */
+export interface CollectionStatusEvent<T extends CollectionStatus> {
+    type: `status:${T}`;
+    collection: Collection;
+    previousStatus: CollectionStatus;
+    status: T;
+}
+/**
+ * Event emitted when the number of subscribers to the collection changes
+ */
+export interface CollectionSubscribersChangeEvent {
+    type: `subscribers:change`;
+    collection: Collection;
+    previousSubscriberCount: number;
+    subscriberCount: number;
+}
+export type AllCollectionEvents = {
+    "status:change": CollectionStatusChangeEvent;
+    "subscribers:change": CollectionSubscribersChangeEvent;
+} & {
+    [K in CollectionStatus as `status:${K}`]: CollectionStatusEvent<K>;
+};
+export type CollectionEvent = AllCollectionEvents[keyof AllCollectionEvents] | CollectionStatusChangeEvent | CollectionSubscribersChangeEvent;
+export type CollectionEventHandler<T extends keyof AllCollectionEvents> = (event: AllCollectionEvents[T]) => void;
+export declare class CollectionEvents {
+    private collection;
+    private listeners;
+    constructor(collection: Collection<any, any, any, any, any>);
+    on<T extends keyof AllCollectionEvents>(event: T, callback: CollectionEventHandler<T>): () => void;
+    once<T extends keyof AllCollectionEvents>(event: T, callback: CollectionEventHandler<T>): () => void;
+    off<T extends keyof AllCollectionEvents>(event: T, callback: CollectionEventHandler<T>): void;
+    waitFor<T extends keyof AllCollectionEvents>(event: T, timeout?: number): Promise<AllCollectionEvents[T]>;
+    emit<T extends keyof AllCollectionEvents>(event: T, eventPayload: AllCollectionEvents[T]): void;
+    emitStatusChange<T extends CollectionStatus>(status: T, previousStatus: CollectionStatus): void;
+    emitSubscribersChange(subscriberCount: number, previousSubscriberCount: number): void;
+    cleanup(): void;
+}

package/dist/esm/collection-events.js

@@ -0,0 +1,88 @@
+class CollectionEvents {
+  constructor(collection) {
+    this.listeners = /* @__PURE__ */ new Map();
+    this.collection = collection;
+  }
+  on(event, callback) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(callback);
+    return () => {
+      this.listeners.get(event).delete(callback);
+    };
+  }
+  once(event, callback) {
+    const unsubscribe = this.on(event, (eventPayload) => {
+      callback(eventPayload);
+      unsubscribe();
+    });
+    return unsubscribe;
+  }
+  off(event, callback) {
+    var _a;
+    (_a = this.listeners.get(event)) == null ? void 0 : _a.delete(callback);
+  }
+  waitFor(event, timeout) {
+    return new Promise((resolve, reject) => {
+      let timeoutId;
+      const unsubscribe = this.on(event, (eventPayload) => {
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+          timeoutId = void 0;
+        }
+        resolve(eventPayload);
+        unsubscribe();
+      });
+      if (timeout) {
+        timeoutId = setTimeout(() => {
+          timeoutId = void 0;
+          unsubscribe();
+          reject(new Error(`Timeout waiting for event ${event}`));
+        }, timeout);
+      }
+    });
+  }
+  emit(event, eventPayload) {
+    var _a;
+    (_a = this.listeners.get(event)) == null ? void 0 : _a.forEach((listener) => {
+      try {
+        listener(eventPayload);
+      } catch (error) {
+        queueMicrotask(() => {
+          throw error;
+        });
+      }
+    });
+  }
+  emitStatusChange(status, previousStatus) {
+    this.emit(`status:change`, {
+      type: `status:change`,
+      collection: this.collection,
+      previousStatus,
+      status
+    });
+    const eventKey = `status:${status}`;
+    this.emit(eventKey, {
+      type: eventKey,
+      collection: this.collection,
+      previousStatus,
+      status
+    });
+  }
+  emitSubscribersChange(subscriberCount, previousSubscriberCount) {
+    this.emit(`subscribers:change`, {
+      type: `subscribers:change`,
+      collection: this.collection,
+      previousSubscriberCount,
+      subscriberCount
+    });
+  }
+  cleanup() {
+    this.listeners.clear();
+  }
+}
+export {
+  CollectionEvents
+};
+//# sourceMappingURL=collection-events.js.map

package/dist/esm/collection-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection-events.js","sources":["../../src/collection-events.ts"],"sourcesContent":["import type { Collection } from \"./collection\"\nimport type { CollectionStatus } from \"./types\"\n\n/**\n * Event emitted when the collection status changes\n */\nexport interface CollectionStatusChangeEvent {\n  type: `status:change`\n  collection: Collection\n  previousStatus: CollectionStatus\n  status: CollectionStatus\n}\n\n/**\n * Event emitted when the collection status changes to a specific status\n */\nexport interface CollectionStatusEvent<T extends CollectionStatus> {\n  type: `status:${T}`\n  collection: Collection\n  previousStatus: CollectionStatus\n  status: T\n}\n\n/**\n * Event emitted when the number of subscribers to the collection changes\n */\nexport interface CollectionSubscribersChangeEvent {\n  type: `subscribers:change`\n  collection: Collection\n  previousSubscriberCount: number\n  subscriberCount: number\n}\n\nexport type AllCollectionEvents = {\n  \"status:change\": CollectionStatusChangeEvent\n  \"subscribers:change\": CollectionSubscribersChangeEvent\n} & {\n  [K in CollectionStatus as `status:${K}`]: CollectionStatusEvent<K>\n}\n\nexport type CollectionEvent =\n  | AllCollectionEvents[keyof AllCollectionEvents]\n  | CollectionStatusChangeEvent\n  | CollectionSubscribersChangeEvent\n\nexport type CollectionEventHandler<T extends keyof AllCollectionEvents> = (\n  event: AllCollectionEvents[T]\n) => void\n\nexport class CollectionEvents {\n  private collection: Collection<any, any, any, any, any>\n  private listeners = new Map<\n    keyof AllCollectionEvents,\n    Set<CollectionEventHandler<any>>\n  >()\n\n  constructor(collection: Collection<any, any, any, any, any>) {\n    this.collection = collection\n  }\n\n  on<T extends keyof AllCollectionEvents>(\n    event: T,\n    callback: CollectionEventHandler<T>\n  ) {\n    if (!this.listeners.has(event)) {\n      this.listeners.set(event, new Set())\n    }\n    this.listeners.get(event)!.add(callback)\n\n    return () => {\n      this.listeners.get(event)!.delete(callback)\n    }\n  }\n\n  once<T extends keyof AllCollectionEvents>(\n    event: T,\n    callback: CollectionEventHandler<T>\n  ) {\n    const unsubscribe = this.on(event, (eventPayload) => {\n      callback(eventPayload)\n      unsubscribe()\n    })\n    return unsubscribe\n  }\n\n  off<T extends keyof AllCollectionEvents>(\n    event: T,\n    callback: CollectionEventHandler<T>\n  ) {\n    this.listeners.get(event)?.delete(callback)\n  }\n\n  waitFor<T extends keyof AllCollectionEvents>(\n    event: T,\n    timeout?: number\n  ): Promise<AllCollectionEvents[T]> {\n    return new Promise((resolve, reject) => {\n      let timeoutId: NodeJS.Timeout | undefined\n      const unsubscribe = this.on(event, (eventPayload) => {\n        if (timeoutId) {\n          clearTimeout(timeoutId)\n          timeoutId = undefined\n        }\n        resolve(eventPayload)\n        unsubscribe()\n      })\n      if (timeout) {\n        timeoutId = setTimeout(() => {\n          timeoutId = undefined\n          unsubscribe()\n          reject(new Error(`Timeout waiting for event ${event}`))\n        }, timeout)\n      }\n    })\n  }\n\n  emit<T extends keyof AllCollectionEvents>(\n    event: T,\n    eventPayload: AllCollectionEvents[T]\n  ) {\n    this.listeners.get(event)?.forEach((listener) => {\n      try {\n        listener(eventPayload)\n      } catch (error) {\n        // Re-throw in a microtask to surface the error\n        queueMicrotask(() => {\n          throw error\n        })\n      }\n    })\n  }\n\n  emitStatusChange<T extends CollectionStatus>(\n    status: T,\n    previousStatus: CollectionStatus\n  ) {\n    this.emit(`status:change`, {\n      type: `status:change`,\n      collection: this.collection,\n      previousStatus,\n      status,\n    })\n\n    // Emit specific status event using type assertion\n    const eventKey: `status:${T}` = `status:${status}`\n    this.emit(eventKey, {\n      type: eventKey,\n      collection: this.collection,\n      previousStatus,\n      status,\n    } as AllCollectionEvents[`status:${T}`])\n  }\n\n  emitSubscribersChange(\n    subscriberCount: number,\n    previousSubscriberCount: number\n  ) {\n    this.emit(`subscribers:change`, {\n      type: `subscribers:change`,\n      collection: this.collection,\n      previousSubscriberCount,\n      subscriberCount,\n    })\n  }\n\n  cleanup() {\n    this.listeners.clear()\n  }\n}\n"],"names":[],"mappings":"AAiDO,MAAM,iBAAiB;AAAA,EAO5B,YAAY,YAAiD;AAL7D,SAAQ,gCAAgB,IAAA;AAMtB,SAAK,aAAa;AAAA,EACpB;AAAA,EAEA,GACE,OACA,UACA;AACA,QAAI,CAAC,KAAK,UAAU,IAAI,KAAK,GAAG;AAC9B,WAAK,UAAU,IAAI,OAAO,oBAAI,KAAK;AAAA,IACrC;AACA,SAAK,UAAU,IAAI,KAAK,EAAG,IAAI,QAAQ;AAEvC,WAAO,MAAM;AACX,WAAK,UAAU,IAAI,KAAK,EAAG,OAAO,QAAQ;AAAA,IAC5C;AAAA,EACF;AAAA,EAEA,KACE,OACA,UACA;AACA,UAAM,cAAc,KAAK,GAAG,OAAO,CAAC,iBAAiB;AACnD,eAAS,YAAY;AACrB,kBAAA;AAAA,IACF,CAAC;AACD,WAAO;AAAA,EACT;AAAA,EAEA,IACE,OACA,UACA;AAvCG;AAwCH,eAAK,UAAU,IAAI,KAAK,MAAxB,mBAA2B,OAAO;AAAA,EACpC;AAAA,EAEA,QACE,OACA,SACiC;AACjC,WAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AACtC,UAAI;AACJ,YAAM,cAAc,KAAK,GAAG,OAAO,CAAC,iBAAiB;AACnD,YAAI,WAAW;AACb,uBAAa,SAAS;AACtB,sBAAY;AAAA,QACd;AACA,gBAAQ,YAAY;AACpB,oBAAA;AAAA,MACF,CAAC;AACD,UAAI,SAAS;AACX,oBAAY,WAAW,MAAM;AAC3B,sBAAY;AACZ,sBAAA;AACA,iBAAO,IAAI,MAAM,6BAA6B,KAAK,EAAE,CAAC;AAAA,QACxD,GAAG,OAAO;AAAA,MACZ;AAAA,IACF,CAAC;AAAA,EACH;AAAA,EAEA,KACE,OACA,cACA;AAtEG;AAuEH,eAAK,UAAU,IAAI,KAAK,MAAxB,mBAA2B,QAAQ,CAAC,aAAa;AAC/C,UAAI;AACF,iBAAS,YAAY;AAAA,MACvB,SAAS,OAAO;AAEd,uBAAe,MAAM;AACnB,gBAAM;AAAA,QACR,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF;AAAA,EAEA,iBACE,QACA,gBACA;AACA,SAAK,KAAK,iBAAiB;AAAA,MACzB,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,MACA;AAAA,IAAA,CACD;AAGD,UAAM,WAA0B,UAAU,MAAM;AAChD,SAAK,KAAK,UAAU;AAAA,MAClB,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,MACA;AAAA,IAAA,CACqC;AAAA,EACzC;AAAA,EAEA,sBACE,iBACA,yBACA;AACA,SAAK,KAAK,sBAAsB;AAAA,MAC9B,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,MACA;AAAA,IAAA,CACD;AAAA,EACH;AAAA,EAEA,UAAU;AACR,SAAK,UAAU,MAAA;AAAA,EACjB;AACF;"}

package/dist/esm/collection.d.ts

@@ -1,6 +1,7 @@
 import { SortedMap } from './SortedMap.js';
 import { BTreeIndex } from './indexes/btree-index.js';
 import { IndexProxy } from './indexes/lazy-index.js';
+import { AllCollectionEvents, CollectionEventHandler } from './collection-events.js';
 import { Transaction } from './transactions.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { SingleRowRefProxy } from './query/builder/ref-proxy.js';
@@ -131,6 +132,7 @@ export declare class CollectionImpl<TOutput extends object = Record<string, unkn
     private gcTimeoutId;
     private preloadPromise;
     private syncCleanupFn;
+    private events;
     /**
      * Register a callback to be executed when the collection first becomes ready
      * Useful for preloading collections
@@ -167,6 +169,10 @@ export declare class CollectionImpl<TOutput extends object = Record<string, unkn
      * Gets the current status of the collection
      */
     get status(): CollectionStatus;
+    /**
+     * Get the number of subscribers to the collection
+     */
+    get subscriberCount(): number;
     /**
      * Validates that the collection is in a usable state for data operations
      * @private
@@ -575,5 +581,21 @@ export declare class CollectionImpl<TOutput extends object = Record<string, unkn
      * This method should be called by the Transaction class when state changes
      */
     onTransactionStateChange(): void;
+    /**
+     * Subscribe to a collection event
+     */
+    on<T extends keyof AllCollectionEvents>(event: T, callback: CollectionEventHandler<T>): () => void;
+    /**
+     * Subscribe to a collection event once
+     */
+    once<T extends keyof AllCollectionEvents>(event: T, callback: CollectionEventHandler<T>): () => void;
+    /**
+     * Unsubscribe from a collection event
+     */
+    off<T extends keyof AllCollectionEvents>(event: T, callback: CollectionEventHandler<T>): void;
+    /**
+     * Wait for a collection event
+     */
+    waitFor<T extends keyof AllCollectionEvents>(event: T, timeout?: number): Promise<AllCollectionEvents[T]>;
 }
 export {};

package/dist/esm/collection.js

@@ -8,6 +8,7 @@ import { ensureIndexForExpression } from "./indexes/auto-index.js";
 import { getActiveTransaction, createTransaction } from "./transactions.js";
 import { MissingInsertHandlerError, DuplicateKeyError, MissingDeleteHandlerError, NoKeysPassedToDeleteError, DeleteKeyNotFoundError, CollectionRequiresConfigError, CollectionRequiresSyncConfigError, CollectionInErrorStateError, InvalidCollectionStatusTransitionError, NoPendingSyncTransactionWriteError, SyncTransactionAlreadyCommittedWriteError, NoPendingSyncTransactionCommitError, SyncTransactionAlreadyCommittedError, DuplicateKeySyncError, CollectionIsInErrorStateError, SyncCleanupError, NegativeActiveSubscribersError, InvalidSchemaError, UndefinedKeyError, SchemaMustBeSynchronousError, SchemaValidationError, MissingUpdateArgumentError, MissingUpdateHandlerError, NoKeysPassedToUpdateError, UpdateKeyNotFoundError, KeyUpdateNotAllowedError } from "./errors.js";
 import { currentStateAsChanges, createFilteredCallback } from "./change-events.js";
+import { CollectionEvents } from "./collection-events.js";
 function createCollection(options) {
   const collection = new CollectionImpl(
     options
@@ -460,6 +461,7 @@ class CollectionImpl {
     } else {
       this.syncedData = /* @__PURE__ */ new Map();
     }
+    this.events = new CollectionEvents(this);
     if (config.startSync === true) {
       this.startSync();
     }
@@ -525,6 +527,12 @@ class CollectionImpl {
   get status() {
     return this._status;
   }
+  /**
+   * Get the number of subscribers to the collection
+   */
+  get subscriberCount() {
+    return this.activeSubscribersCount;
+  }
   /**
    * Validates that the collection is in a usable state for data operations
    * @private
@@ -564,12 +572,14 @@ class CollectionImpl {
    */
   setStatus(newStatus) {
     this.validateStatusTransition(this._status, newStatus);
+    const previousStatus = this._status;
     this._status = newStatus;
     if (newStatus === `ready` && !this.isIndexesResolved) {
       this.resolveAllIndexes().catch((error) => {
         console.warn(`Failed to resolve indexes:`, error);
       });
     }
+    this.events.emitStatusChange(newStatus, previousStatus);
   }
   /**
    * Start sync immediately - internal method for compiled queries
@@ -729,6 +739,7 @@ class CollectionImpl {
     this.preloadPromise = null;
     this.batchedEvents = [];
     this.shouldBatchEvents = false;
+    this.events.cleanup();
     this.setStatus(`cleaned-up`);
     return Promise.resolve();
   }
@@ -764,22 +775,32 @@ class CollectionImpl {
    * Increment the active subscribers count and start sync if needed
    */
   addSubscriber() {
+    const previousSubscriberCount = this.activeSubscribersCount;
     this.activeSubscribersCount++;
     this.cancelGCTimer();
     if (this._status === `cleaned-up` || this._status === `idle`) {
       this.startSync();
     }
+    this.events.emitSubscribersChange(
+      this.activeSubscribersCount,
+      previousSubscriberCount
+    );
   }
   /**
    * Decrement the active subscribers count and start GC timer if needed
    */
   removeSubscriber() {
+    const previousSubscriberCount = this.activeSubscribersCount;
     this.activeSubscribersCount--;
     if (this.activeSubscribersCount === 0) {
       this.startGCTimer();
     } else if (this.activeSubscribersCount < 0) {
       throw new NegativeActiveSubscribersError();
     }
+    this.events.emitSubscribersChange(
+      this.activeSubscribersCount,
+      previousSubscriberCount
+    );
   }
   /**
    * Recompute optimistic state from active transactions
@@ -1410,11 +1431,7 @@ class CollectionImpl {
     if (this.size > 0 || this.isReady()) {
       return Promise.resolve(this.state);
     }
-    return new Promise((resolve) => {
-      this.onFirstReady(() => {
-        resolve(this.state);
-      });
-    });
+    return this.preload().then(() => this.state);
   }
   /**
    * Gets the current state of the collection as an Array
@@ -1434,11 +1451,7 @@ class CollectionImpl {
     if (this.size > 0 || this.isReady()) {
       return Promise.resolve(this.toArray);
     }
-    return new Promise((resolve) => {
-      this.onFirstReady(() => {
-        resolve(this.toArray);
-      });
-    });
+    return this.preload().then(() => this.toArray);
   }
   /**
    * Returns the current state of the collection as an array of changes
@@ -1580,6 +1593,30 @@ class CollectionImpl {
     this.capturePreSyncVisibleState();
     this.recomputeOptimisticState(false);
   }
+  /**
+   * Subscribe to a collection event
+   */
+  on(event, callback) {
+    return this.events.on(event, callback);
+  }
+  /**
+   * Subscribe to a collection event once
+   */
+  once(event, callback) {
+    return this.events.once(event, callback);
+  }
+  /**
+   * Unsubscribe from a collection event
+   */
+  off(event, callback) {
+    this.events.off(event, callback);
+  }
+  /**
+   * Wait for a collection event
+   */
+  waitFor(event, timeout) {
+    return this.events.waitFor(event, timeout);
+  }
 }
 export {
   CollectionImpl,