@signaldb/core 1.7.0 → 2.0.0-beta.0

package/dist/.vite/manifest.json

@@ -1,11 +1,34 @@
 {
-  "src/AutoFetchCollection.ts": {
-    "file": "index.cjs4.js",
-    "name": "AutoFetchCollection",
-    "src": "src/AutoFetchCollection.ts",
+  "src/AsyncDataAdapter.ts": {
+    "file": "index.cjs13.js",
+    "name": "AsyncDataAdapter",
+    "src": "src/AsyncDataAdapter.ts",
     "imports": [
-      "src/ReplicatedCollection.ts",
-      "src/utils/createSignal.ts"
+      "src/utils/deepClone.ts",
+      "src/utils/match.ts",
+      "src/utils/modify.ts",
+      "src/utils/queryId.ts",
+      "src/utils/isEqual.ts",
+      "src/getIndexInfo.ts",
+      "src/utils/getMatchingKeys.ts",
+      "src/utils/sortItems.ts",
+      "src/utils/project.ts"
+    ]
+  },
+  "src/AutoFetchDataAdapter.ts": {
+    "file": "index.cjs16.js",
+    "name": "AutoFetchDataAdapter",
+    "src": "src/AutoFetchDataAdapter.ts",
+    "imports": [
+      "src/utils/deepClone.ts",
+      "src/utils/match.ts",
+      "src/utils/modify.ts",
+      "src/utils/queryId.ts",
+      "src/utils/isEqual.ts",
+      "src/getIndexInfo.ts",
+      "src/utils/getMatchingKeys.ts",
+      "src/utils/sortItems.ts",
+      "src/utils/project.ts"
     ]
   },
   "src/Collection/Cursor.ts": {
@@ -13,8 +36,6 @@
     "name": "Collection/Cursor",
     "src": "src/Collection/Cursor.ts",
     "imports": [
-      "src/utils/sortItems.ts",
-      "src/utils/project.ts",
       "src/Collection/Observer.ts"
     ]
   },
@@ -27,69 +48,97 @@
       "src/utils/uniqueBy.ts"
     ]
   },
-  "src/Collection/createIndex.ts": {
-    "file": "index.cjs14.js",
-    "name": "Collection/createIndex",
-    "src": "src/Collection/createIndex.ts",
+  "src/Collection/index.ts": {
+    "file": "index.cjs3.js",
+    "name": "Collection/index",
+    "src": "src/Collection/index.ts",
     "imports": [
-      "src/createIndexProvider.ts",
-      "src/utils/get.ts",
-      "src/utils/getMatchingKeys.ts",
-      "src/utils/serializeValue.ts"
+      "src/utils/EventEmitter.ts",
+      "src/utils/createSignal.ts",
+      "src/utils/randomId.ts",
+      "src/DefaultDataAdapter.ts",
+      "src/utils/modify.ts",
+      "src/utils/deepClone.ts",
+      "src/Collection/Cursor.ts"
     ]
   },
-  "src/Collection/getIndexInfo.ts": {
-    "file": "index.cjs22.js",
-    "name": "Collection/getIndexInfo",
-    "src": "src/Collection/getIndexInfo.ts",
+  "src/DefaultDataAdapter.ts": {
+    "file": "index.cjs12.js",
+    "name": "DefaultDataAdapter",
+    "src": "src/DefaultDataAdapter.ts",
     "imports": [
-      "src/utils/intersection.ts"
+      "src/createIndex.ts",
+      "src/getIndexInfo.ts",
+      "src/utils/deepClone.ts",
+      "src/utils/EventEmitter.ts",
+      "src/utils/isEqual.ts",
+      "src/utils/match.ts",
+      "src/utils/modify.ts",
+      "src/utils/project.ts",
+      "src/utils/queryId.ts",
+      "src/utils/serializeValue.ts",
+      "src/utils/sortItems.ts"
     ]
   },
-  "src/Collection/index.ts": {
-    "file": "index.cjs3.js",
-    "name": "Collection/index",
-    "src": "src/Collection/index.ts",
+  "src/WorkerDataAdapter.ts": {
+    "file": "index.cjs14.js",
+    "name": "WorkerDataAdapter",
+    "src": "src/WorkerDataAdapter.ts",
     "imports": [
-      "src/utils/EventEmitter.ts",
+      "src/utils/queryId.ts",
+      "src/utils/randomId.ts"
+    ]
+  },
+  "src/WorkerDataAdapterHost.ts": {
+    "file": "index.cjs15.js",
+    "name": "WorkerDataAdapterHost",
+    "src": "src/WorkerDataAdapterHost.ts",
+    "imports": [
+      "src/utils/deepClone.ts",
       "src/utils/match.ts",
       "src/utils/modify.ts",
+      "src/utils/queryId.ts",
       "src/utils/isEqual.ts",
-      "src/utils/randomId.ts",
-      "src/utils/deepClone.ts",
-      "src/utils/serializeValue.ts",
-      "src/utils/createSignal.ts",
-      "src/Collection/Cursor.ts",
-      "src/Collection/getIndexInfo.ts",
-      "src/Collection/createIndex.ts"
+      "src/getIndexInfo.ts",
+      "src/utils/getMatchingKeys.ts",
+      "src/utils/sortItems.ts",
+      "src/utils/project.ts"
     ]
   },
-  "src/ReplicatedCollection.ts": {
-    "file": "index.cjs23.js",
-    "name": "ReplicatedCollection",
-    "src": "src/ReplicatedCollection.ts",
+  "src/createIndex.ts": {
+    "file": "index.cjs20.js",
+    "name": "createIndex",
+    "src": "src/createIndex.ts",
     "imports": [
-      "src/Collection/index.ts",
-      "src/persistence/combinePersistenceAdapters.ts",
-      "src/persistence/createPersistenceAdapter.ts",
-      "src/utils/createSignal.ts"
+      "src/createIndexProvider.ts",
+      "src/utils/get.ts",
+      "src/utils/getMatchingKeys.ts",
+      "src/utils/serializeValue.ts"
     ]
   },
   "src/createIndexProvider.ts": {
-    "file": "index.cjs6.js",
+    "file": "index.cjs27.js",
     "name": "createIndexProvider",
     "src": "src/createIndexProvider.ts"
   },
-  "src/createMemoryAdapter.ts": {
-    "file": "index.cjs7.js",
-    "name": "createMemoryAdapter",
-    "src": "src/createMemoryAdapter.ts"
-  },
   "src/createReactivityAdapter.ts": {
-    "file": "index.cjs9.js",
+    "file": "index.cjs5.js",
     "name": "createReactivityAdapter",
     "src": "src/createReactivityAdapter.ts"
   },
+  "src/createStorageAdapter.ts": {
+    "file": "index.cjs4.js",
+    "name": "createStorageAdapter",
+    "src": "src/createStorageAdapter.ts"
+  },
+  "src/getIndexInfo.ts": {
+    "file": "index.cjs21.js",
+    "name": "getIndexInfo",
+    "src": "src/getIndexInfo.ts",
+    "imports": [
+      "src/utils/intersection.ts"
+    ]
+  },
   "src/index.ts": {
     "file": "index.cjs.js",
     "name": "index",
@@ -98,39 +147,28 @@
     "imports": [
       "src/Collection/Cursor.ts",
       "src/Collection/index.ts",
-      "src/AutoFetchCollection.ts",
-      "src/persistence/combinePersistenceAdapters.ts",
-      "src/createIndexProvider.ts",
-      "src/createMemoryAdapter.ts",
-      "src/persistence/createPersistenceAdapter.ts",
+      "src/createStorageAdapter.ts",
       "src/createReactivityAdapter.ts",
       "src/utils/isEqual.ts",
       "src/utils/modify.ts",
       "src/utils/randomId.ts",
       "src/utils/EventEmitter.ts",
-      "src/Collection/createIndex.ts"
-    ]
-  },
-  "src/persistence/combinePersistenceAdapters.ts": {
-    "file": "index.cjs5.js",
-    "name": "persistence/combinePersistenceAdapters",
-    "src": "src/persistence/combinePersistenceAdapters.ts",
-    "imports": [
-      "src/persistence/createPersistenceAdapter.ts"
+      "src/utils/get.ts",
+      "src/utils/serializeValue.ts",
+      "src/DefaultDataAdapter.ts",
+      "src/AsyncDataAdapter.ts",
+      "src/WorkerDataAdapter.ts",
+      "src/WorkerDataAdapterHost.ts",
+      "src/AutoFetchDataAdapter.ts"
     ]
   },
-  "src/persistence/createPersistenceAdapter.ts": {
-    "file": "index.cjs8.js",
-    "name": "persistence/createPersistenceAdapter",
-    "src": "src/persistence/createPersistenceAdapter.ts"
-  },
   "src/utils/EventEmitter.ts": {
-    "file": "index.cjs13.js",
+    "file": "index.cjs9.js",
     "name": "utils/EventEmitter",
     "src": "src/utils/EventEmitter.ts"
   },
   "src/utils/createSignal.ts": {
-    "file": "index.cjs21.js",
+    "file": "index.cjs18.js",
     "name": "utils/createSignal",
     "src": "src/utils/createSignal.ts"
   },
@@ -140,12 +178,12 @@
     "src": "src/utils/deepClone.ts"
   },
   "src/utils/get.ts": {
-    "file": "index.cjs24.js",
+    "file": "index.cjs10.js",
     "name": "utils/get",
     "src": "src/utils/get.ts"
   },
   "src/utils/getMatchingKeys.ts": {
-    "file": "index.cjs28.js",
+    "file": "index.cjs26.js",
     "name": "utils/getMatchingKeys",
     "src": "src/utils/getMatchingKeys.ts",
     "imports": [
@@ -154,27 +192,27 @@
     ]
   },
   "src/utils/intersection.ts": {
-    "file": "index.cjs27.js",
+    "file": "index.cjs28.js",
     "name": "utils/intersection",
     "src": "src/utils/intersection.ts"
   },
   "src/utils/isEqual.ts": {
-    "file": "index.cjs10.js",
+    "file": "index.cjs6.js",
     "name": "utils/isEqual",
     "src": "src/utils/isEqual.ts"
   },
   "src/utils/isFieldExpression.ts": {
-    "file": "index.cjs29.js",
+    "file": "index.cjs30.js",
     "name": "utils/isFieldExpression",
     "src": "src/utils/isFieldExpression.ts"
   },
   "src/utils/match.ts": {
-    "file": "index.cjs18.js",
+    "file": "index.cjs22.js",
     "name": "utils/match",
     "src": "src/utils/match.ts"
   },
   "src/utils/modify.ts": {
-    "file": "index.cjs11.js",
+    "file": "index.cjs7.js",
     "name": "utils/modify",
     "src": "src/utils/modify.ts",
     "imports": [
@@ -182,7 +220,7 @@
     ]
   },
   "src/utils/project.ts": {
-    "file": "index.cjs16.js",
+    "file": "index.cjs23.js",
     "name": "utils/project",
     "src": "src/utils/project.ts",
     "imports": [
@@ -190,23 +228,28 @@
       "src/utils/set.ts"
     ]
   },
+  "src/utils/queryId.ts": {
+    "file": "index.cjs24.js",
+    "name": "utils/queryId",
+    "src": "src/utils/queryId.ts"
+  },
   "src/utils/randomId.ts": {
-    "file": "index.cjs12.js",
+    "file": "index.cjs8.js",
     "name": "utils/randomId",
     "src": "src/utils/randomId.ts"
   },
   "src/utils/serializeValue.ts": {
-    "file": "index.cjs20.js",
+    "file": "index.cjs11.js",
     "name": "utils/serializeValue",
     "src": "src/utils/serializeValue.ts"
   },
   "src/utils/set.ts": {
-    "file": "index.cjs25.js",
+    "file": "index.cjs29.js",
     "name": "utils/set",
     "src": "src/utils/set.ts"
   },
   "src/utils/sortItems.ts": {
-    "file": "index.cjs15.js",
+    "file": "index.cjs25.js",
     "name": "utils/sortItems",
     "src": "src/utils/sortItems.ts",
     "imports": [
@@ -214,7 +257,7 @@
     ]
   },
   "src/utils/uniqueBy.ts": {
-    "file": "index.cjs26.js",
+    "file": "index.cjs31.js",
     "name": "utils/uniqueBy",
     "src": "src/utils/uniqueBy.ts"
   }

package/dist/AsyncDataAdapter.d.ts

@@ -0,0 +1,64 @@
+import type { BaseItem } from './Collection';
+import type Collection from './Collection';
+import type DataAdapter from './DataAdapter';
+import type { CollectionBackend } from './DataAdapter';
+import type StorageAdapter from './types/StorageAdapter';
+export interface AsyncDataAdapterOptions {
+    /** Factory to obtain a StorageAdapter per collection name */
+    storage: (name: string) => StorageAdapter<any, any>;
+    /** Optional logical id (handy if you run multiple adapters side-by-side) */
+    id?: string;
+    /** Optional error hook (mirrors WorkerDataAdapterHost) */
+    onError?: (error: Error) => void;
+}
+/**
+ * AsyncDataAdapter
+ * Combines WorkerDataAdapter + WorkerDataAdapterHost into a single, transport-free adapter.
+ * - Keeps the DataAdapter/CollectionBackend surface identical to the Worker version.
+ * - Executes queries and mutations directly against the provided StorageAdapter.
+ * - Preserves index-aware query optimization and push-style query updates to listeners.
+ */
+export default class AsyncDataAdapter implements DataAdapter {
+    private options;
+    private id;
+    private onError;
+    private storageAdapters;
+    private storageAdapterReady;
+    private collectionIndices;
+    private queries;
+    constructor(options: AsyncDataAdapterOptions);
+    createCollectionBackend<T extends BaseItem<I>, I = any, U = T>(collection: Collection<T, I, U>, indices: string[]): CollectionBackend<T, I>;
+    private setupStorage;
+    private ensureStorageAdapter;
+    /**
+     * Compute and publish the result for a specific query
+     * @param collectionName - name of the collection
+     * @param selector - query selector
+     * @param options - query options
+     */
+    private fulfillQuery;
+    /**
+     * Notify listeners about state changes and keep the cache updated
+     * @param collectionName - name of the collection
+     * @param qid - query id
+     * @param state - new state
+     * @param error - error if state is 'error', null otherwise
+     */
+    private publishState;
+    private publishResult;
+    private getIndexInfo;
+    private queryItems;
+    private executeQuery;
+    /**
+     * After mutations, recompute and push updates for affected active queries
+     * @param collectionName - name of the collection
+     * @param changedItems - items that were inserted/updated/replaced/removed
+     */
+    private checkQueryUpdates;
+    private insert;
+    private updateOne;
+    private updateMany;
+    private replaceOne;
+    private removeOne;
+    private removeMany;
+}

package/dist/AutoFetchDataAdapter.d.ts

@@ -0,0 +1,113 @@
+import type { BaseItem } from './Collection';
+import type Collection from './Collection';
+import type DataAdapter from './DataAdapter';
+import type { CollectionBackend } from './DataAdapter';
+import type StorageAdapter from './types/StorageAdapter';
+import type Selector from './types/Selector';
+/**
+ * AutoFetchDataAdapterOptions
+ *
+ * Merges the core options required to talk to a per-collection StorageAdapter with
+ * the auto-fetch behavior inspired by AutoFetchCollection.
+ */
+export interface AutoFetchDataAdapterOptions {
+    /** Factory to obtain a StorageAdapter per collection name */
+    storage?: (name: string) => StorageAdapter<any, any>;
+    /** Optional logical id (handy if you run multiple adapters side-by-side) */
+    id?: string;
+    /** Optional error hook */
+    onError?: (error: Error) => void;
+    /**
+     * Fetch hook: given a selector, retrieve items from a remote source.
+     * Must resolve to an object with an `items` array. Items MUST include an `id`.
+     */
+    fetchQueryItems: (collectionName: string, selector: Selector<BaseItem>) => Promise<BaseItem[] | undefined>;
+    /**
+     * Optional: called once at adapter construction to subscribe to remote changes.
+     * When invoked, call the provided callback whenever the remote source changed
+     * and all active queries should be re-fetched.
+     */
+    registerRemoteChange?: (onChange: () => Promise<void>) => Promise<void>;
+    /**
+     * Merge strategy for ingesting freshly fetched items with existing ones.
+     * Default is shallow spread (right wins).
+     */
+    mergeItems?: <T extends BaseItem<any>>(a: T, b: T) => T;
+    /**
+     * Delay (ms) before purging auto-fetched items for a query after the query
+     * becomes inactive. Set to 0 to purge immediately. Default: 10s.
+     */
+    purgeDelay?: number;
+}
+/**
+ * AutoFetchDataAdapter
+ *
+ * A DataAdapter that:
+ * - Mirrors the CollectionBackend surface (CRUD + query registry + lifecycle)
+ * - Executes queries against a provided StorageAdapter (local cache)
+ * - On first registration of a selector, auto-fetches from a remote source and
+ *   ingests the result into storage (upsert), then pushes query result updates
+ * - Optionally purges auto-fetched items for a selector once no observers remain
+ * - Can subscribe to remote change notifications to re-fetch active selectors
+ *
+ * IMPORTANT: Purging only ever deletes items that were introduced via the
+ * auto-fetch path and are no longer referenced by any active selector. Items
+ * inserted through CRUD calls are never purged.
+ */
+export default class AutoFetchDataAdapter implements DataAdapter {
+    private options;
+    private id;
+    private onError;
+    private fetchQueryItems;
+    private mergeItems;
+    private purgeDelay;
+    private storageAdapters;
+    private storageAdapterReady;
+    private collectionIndices;
+    private queries;
+    private activeObservers;
+    private observerTimeouts;
+    private selectorIds;
+    private idRefCounts;
+    private autoloadIds;
+    constructor(options: AutoFetchDataAdapterOptions);
+    createCollectionBackend<T extends BaseItem<I>, I = any, U = T>(collection: Collection<T, I, U>, indices: string[]): CollectionBackend<T, I>;
+    private selectorKey;
+    private forceRefetchAll;
+    private fetchAndIngest;
+    private purgeSelector;
+    private setupStorage;
+    private ensureStorageAdapter;
+    private publishForSelector;
+    private publishState;
+    private publishResult;
+    private fulfillQuery;
+    private getIndexInfo;
+    private queryItems;
+    private executeQuery;
+    private checkQueryUpdates;
+    private insert;
+    private updateOne;
+    private updateMany;
+    private replaceOne;
+    private removeOne;
+    private removeMany;
+    private upsertMerged;
+}
+/**
+ * Usage (example):
+ *
+ * const adapter = new AutoFetchDataAdapter({
+ *   storage: (name) => new IndexedDBStorage(name),
+ *   fetchQueryItems: async (collectionName, selector) => {
+ *     const res = await fetch(`/api/${collectionName}?q=${encodeURIComponent(JSON.stringify(selector||{}))}`)
+ *     const items = await res.json()
+ *     return { items }
+ *   },
+ *   registerRemoteChange: (onChange) => subscribeToWS(onChange),
+ *   mergeItems: (a, b) => ({ ...a, ...b }),
+ *   purgeDelay: 10_000,
+ * })
+ *
+ * const backend = adapter.createCollectionBackend(myCollection, ['status', 'projectId'])
+ */

package/dist/Collection/Cursor.d.ts

@@ -7,7 +7,7 @@ import type { ObserveCallbacks } from './Observer';
  * @returns A boolean indicating if the current scope is reactive.
  */
 export declare function isInReactiveScope(reactivity: ReactivityAdapter | undefined | false): boolean;
-export interface CursorOptions<T extends BaseItem, U = T> extends FindOptions<T> {
+export interface CursorOptions<T extends BaseItem, U = T, Async extends boolean = false> extends FindOptions<T, Async> {
     transform?: Transform<T, U>;
     bindEvents?: (requery: () => void) => () => void;
 }
@@ -17,9 +17,9 @@ export interface CursorOptions<T extends BaseItem, U = T> extends FindOptions<T>
  * @template T - The type of the items in the collection.
  * @template U - The transformed item type after applying transformations (default is T).
  */
-export default class Cursor<T extends BaseItem, U = T> {
+export default class Cursor<T extends BaseItem, U = T, Async extends boolean = false> {
     private observer;
-    private getFilteredItems;
+    private getItems;
     private options;
     private onCleanupCallbacks;
     /**
@@ -38,10 +38,9 @@ export default class Cursor<T extends BaseItem, U = T> {
      * @param options.reactive - A reactivity adapter to enable observing changes in the cursor's result set.
      * @param options.fieldTracking - A boolean to enable fine-grained field tracking for reactivity.
      */
-    constructor(getItems: () => T[], options?: CursorOptions<T, U>);
+    constructor(getItems: Async extends true ? () => Promise<T[]> : () => T[], options?: CursorOptions<T, U, Async>);
     private addGetters;
     private transform;
-    private getItems;
     private depend;
     private ensureObserver;
     private observeRawChanges;
@@ -63,8 +62,9 @@ export default class Cursor<T extends BaseItem, U = T> {
      * ⚡️ this function is reactive!
      * @param callback - A function to execute for each item in the result set.
      * @param callback.item - The transformed item.
+     * @returns A promise that resolves when all items have been processed, or void if not in async mode.
      */
-    forEach(callback: (item: U) => void): void;
+    forEach(callback: (item: U) => void): Async extends true ? Promise<void> : void;
     /**
      * Creates a new array populated with the results of applying the provided callback
      * function to each transformed item in the cursor's result set.
@@ -74,21 +74,21 @@ export default class Cursor<T extends BaseItem, U = T> {
      * @param callback.item - The transformed item.
      * @returns An array of results after applying the callback to each item.
      */
-    map<V>(callback: (item: U) => V): V[];
+    map<V>(callback: (item: U) => V): Async extends true ? Promise<V[]> : V[];
     /**
      * Fetches all transformed items from the cursor's result set as an array.
      * Automatically applies filtering, sorting, and limiting as per the cursor's options.
      * ⚡️ this function is reactive!
      * @returns An array of transformed items in the result set.
      */
-    fetch(): U[];
+    fetch(): Async extends true ? Promise<U[]> : U[];
     /**
      * Counts the total number of items in the cursor's result set after applying
      * filtering and other criteria.
      * ⚡️ this function is reactive!
      * @returns The total number of items in the result set.
      */
-    count(): number;
+    count(): Async extends true ? Promise<number> : number;
     /**
      * Observes changes to the cursor's result set and triggers the specified callbacks
      * when items are added, removed, or updated. Supports reactivity and transformation.

package/dist/Collection/Observer.d.ts

@@ -39,9 +39,10 @@ export default class Observer<T extends {
     /**
      * Compares the previous state of items with the new state and triggers the appropriate callbacks
      * for events such as added, removed, changed, or moved items.
-     * @param newItems - The new list of items to compare against the previous state.
+     * @param getItems - A function that returns a promise resolving to the new items or the items themselves.
      */
-    runChecks(newItems: T[]): void;
+    runChecks(getItems: () => Promise<T[]> | T[]): void;
+    private checkItems;
     /**
      * Stops the observer by unbinding all events and cleaning up resources.
      */