@signaldb/svelte 2.0.0-beta.2 → 2.0.0-beta.21

package/dist/base/core/src/AutoFetchDataAdapter.d.ts

@@ -0,0 +1,112 @@
+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, E extends BaseItem = T, U = E>(collection: Collection<T, I, E, U>, indices: string[]): CollectionBackend<T, I>;
+    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'])
+ */