@signaldb/localstorage 2.0.0-beta.6 → 2.0.0-beta.7

package/dist/base/core/src/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, E extends BaseItem = T, U = E>(collection: Collection<T, I, E, 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 affectedItems - item states before and/or after the mutation
+     */
+    private checkQueryUpdates;
+    private insert;
+    private updateOne;
+    private updateMany;
+    private replaceOne;
+    private removeOne;
+    private removeMany;
+}

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'])
+ */

package/dist/base/core/src/Collection/Cursor.d.ts

@@ -0,0 +1,113 @@
+import type ReactivityAdapter from '../types/ReactivityAdapter';
+import type { BaseItem, FindOptions, Transform } from './types';
+import type { ObserveCallbacks } from './Observer';
+/**
+ * Checks if the current scope is reactive, considering the provided reactivity adapter.
+ * @param reactivity - The reactivity adapter or a boolean indicating whether reactivity is enabled.
+ * @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, Async extends boolean = false> extends FindOptions<T, Async> {
+    transform?: Transform<T, U>;
+    bindEvents?: (requery: () => void) => () => void;
+}
+/**
+ * Represents a cursor for querying and observing a filtered, sorted, and transformed
+ * subset of items from a collection. Supports reactivity and field tracking.
+ * @template T - The type of the items in the collection.
+ * @template U - The transformed item type after applying transform (default is T).
+ */
+export default class Cursor<T extends BaseItem, U = T, Async extends boolean = false> {
+    private observer;
+    private getItems;
+    private options;
+    private onCleanupCallbacks;
+    /**
+     * Creates a new instance of the `Cursor` class.
+     * Provides utilities for querying, observing, and transforming items from a collection.
+     * @template T - The type of the items in the collection.
+     * @template U - The transformed item type after applying transformations (default is T).
+     * @param getItems - A function that retrieves the filtered list of items.
+     * @param options - Optional configuration for the cursor.
+     * @param options.transform - A transformation function to apply to each item when retrieving them.
+     * @param options.bindEvents - A function to bind reactivity events for the cursor, which should return a cleanup function.
+     * @param options.fields - A projection object defining which fields of the item should be included or excluded.
+     * @param options.sort - A sort specifier to determine the order of the items.
+     * @param options.skip - The number of items to skip from the beginning of the result set.
+     * @param options.limit - The maximum number of items to return in the result set.
+     * @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.
+     * @param options.transformAll - A function that will be able to solve the n+1 problem
+     */
+    constructor(getItems: Async extends true ? () => Promise<T[]> : () => T[], options?: CursorOptions<T, U, Async>);
+    private addGetters;
+    private transform;
+    private depend;
+    private ensureObserver;
+    private observeRawChanges;
+    /**
+     * Cleans up all resources associated with the cursor, such as reactive bindings
+     * and event listeners. This method should be called when the cursor is no longer needed
+     * to prevent memory leaks.
+     */
+    cleanup(): void;
+    /**
+     * Registers a cleanup callback to be executed when the `cleanup` method is called.
+     * Useful for managing resources and ensuring proper cleanup of bindings or listeners.
+     * @param callback - A function to be executed during cleanup.
+     */
+    onCleanup(callback: () => void): void;
+    /**
+     * Iterates over each item in the cursor's result set, applying the provided callback
+     * function to each transformed item.
+     * ⚡️ 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): 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.
+     * ⚡️ this function is reactive!
+     * @template V - The type of the items in the resulting array.
+     * @param callback - A function to execute for each item in the result set.
+     * @param callback.item - The transformed item.
+     * @returns An array of results after applying the callback to each item.
+     */
+    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(): 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(): 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.
+     * @param callbacks - An object containing the callback functions to handle different change events.
+     * @param callbacks.added - Triggered when an item is added to the result set.
+     * @param callbacks.removed - Triggered when an item is removed from the result set.
+     * @param callbacks.changed - Triggered when an item in the result set is modified.
+     * @param callbacks.addedBefore - Triggered when an item is added before another item in the result set.
+     * @param callbacks.movedBefore - Triggered when an item is moved before another item in the result set.
+     * @param callbacks.changedField - Triggered when a specific field of an item changes.
+     * @param skipInitial - A boolean indicating whether to skip the initial notification of the current result set.
+     * @returns A function to stop observing changes.
+     */
+    observeChanges(callbacks: ObserveCallbacks<T>, skipInitial?: boolean): () => void;
+    /**
+     * Forces the cursor to re-evaluate its result set by re-fetching items
+     * from the collection. This is useful when the underlying data or query
+     * criteria have changed, and you want to ensure the cursor reflects the latest state.
+     */
+    requery(): void;
+}

package/dist/base/core/src/Collection/Observer.d.ts

@@ -0,0 +1,64 @@
+type AddedCallback<T> = (item: T) => void;
+type AddedBeforeCallback<T> = (item: T, before: T) => void;
+type ChangedCallback<T> = (item: T) => void;
+type ChangedFieldCallback<T> = <Field extends keyof T>(item: T, field: Field, oldValue: T[Field], newValue: T[Field]) => void;
+type MovedBeforeCallback<T> = (item: T, before: T) => void;
+type RemovedCallback<T> = (item: T) => void;
+export interface ObserveCallbacks<T> {
+    added?: AddedCallback<T>;
+    addedBefore?: AddedBeforeCallback<T>;
+    changed?: ChangedCallback<T>;
+    changedField?: ChangedFieldCallback<T>;
+    movedBefore?: MovedBeforeCallback<T>;
+    removed?: RemovedCallback<T>;
+}
+/**
+ * Represents an observer that tracks changes in a collection of items and triggers
+ * callbacks for various events such as addition, removal, and modification of items.
+ * @template T - The type of the items being observed, which must include an `id` field.
+ */
+export default class Observer<T extends {
+    id: any;
+}> {
+    private previousItems;
+    private callbacks;
+    private unbindEvents;
+    /**
+     * Creates a new instance of the `Observer` class.
+     * Sets up event bindings and initializes the callbacks for tracking changes in a collection.
+     * @param bindEvents - A function to bind external events to the observer. Must return a cleanup function to unbind those events.
+     */
+    constructor(bindEvents: () => () => void);
+    private call;
+    private hasCallbacks;
+    /**
+     * Determines if the observer has no active callbacks registered for any events.
+     * @returns A boolean indicating whether the observer is empty (i.e., no callbacks are registered).
+     */
+    isEmpty(): boolean;
+    /**
+     * 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 getItems - A function that returns a promise resolving to the new items or the items themselves.
+     */
+    runChecks(getItems: () => Promise<T[]> | T[]): void;
+    private checkItems;
+    private stopped;
+    /**
+     * Stops the observer by unbinding all events and cleaning up resources.
+     * Safe to call multiple times - will only unbind once.
+     */
+    stop(): void;
+    /**
+     * Registers callbacks for specific events to observe changes in the collection.
+     * @param callbacks - An object containing the callbacks for various events (e.g., 'added', 'removed').
+     * @param skipInitial - A boolean indicating whether to skip invoking the callbacks for the initial state of the collection.
+     */
+    addCallbacks(callbacks: ObserveCallbacks<T>, skipInitial?: boolean): void;
+    /**
+     * Removes the specified callbacks for specific events, unregistering them from the observer.
+     * @param callbacks - An object containing the callbacks to be removed for various events.
+     */
+    removeCallbacks(callbacks: ObserveCallbacks<T>): void;
+}
+export {};

package/dist/base/core/src/Collection/index.d.ts

@@ -0,0 +1,294 @@
+import type ReactivityAdapter from '../types/ReactivityAdapter';
+import EventEmitter from '../utils/EventEmitter';
+import type Selector from '../types/Selector';
+import type Modifier from '../types/Modifier';
+import type DataAdapter from '../DataAdapter';
+import type { QueryOptions } from '../DataAdapter';
+import type StorageAdapter from '../types/StorageAdapter';
+import Cursor from './Cursor';
+import type { AsyncFindOptions, BaseItem, FindOptions, SyncFindOptions, Transform, TransformAll } from './types';
+export type { AnyFindOptions, AsyncFindOptions, BaseItem, Transform, TransformAll, SortSpecifier, FieldSpecifier, FindOptions, SyncFindOptions, } from './types';
+export type { CursorOptions } from './Cursor';
+export type { ObserveCallbacks } from './Observer';
+export { default as createIndex } from '../createIndex';
+export interface CollectionOptions<T extends BaseItem<I>, I, E extends BaseItem = T, U = E> {
+    /**
+     * @deprecated Use new constructor parameters instead.
+     */
+    name?: string;
+    /**
+     * @deprecated Use `DataAdapter` options instead.
+     */
+    persistence?: StorageAdapter<T, I>;
+    primaryKeyGenerator?: (item: Omit<T, 'id'>) => I;
+    reactivity?: ReactivityAdapter;
+    transform?: Transform<E, U>;
+    transformAll?: TransformAll<T, E>;
+    indices?: string[];
+    enableDebugMode?: boolean;
+    fieldTracking?: boolean;
+}
+interface CollectionEvents<T extends BaseItem, E extends BaseItem = T, U = E> {
+    'added': (item: T) => void;
+    'changed': (item: T, modifier: Modifier<T>) => void;
+    'removed': (item: T) => void;
+    'observer.created': <O extends QueryOptions<T>>(selector?: Selector<T>, options?: O) => void;
+    'observer.disposed': <O extends QueryOptions<T>>(selector?: Selector<T>, options?: O) => void;
+    'getItems': (selector: Selector<T> | undefined) => void;
+    'find': <Async extends boolean, O extends FindOptions<T, Async>>(selector: Selector<T> | undefined, options: O | undefined, cursor: Cursor<E, U, Async>) => void;
+    'findOne': <O extends QueryOptions<T>>(selector: Selector<T>, options: O | undefined, item: U | undefined) => void;
+    'insert': (item: Omit<T, 'id'> & Partial<Pick<T, 'id'>>) => void;
+    'updateOne': (selector: Selector<T>, modifier: Modifier<T>) => void;
+    'updateMany': (selector: Selector<T>, modifier: Modifier<T>) => void;
+    'replaceOne': (selector: Selector<T>, item: Omit<T, 'id'> & Partial<Pick<T, 'id'>>) => void;
+    'removeOne': (selector: Selector<T>) => void;
+    'removeMany': (selector: Selector<T>) => void;
+    'validate': (item: T) => void;
+    '_debug.getItems': (callstack: string, selector: Selector<T> | undefined, measuredTime: number) => void;
+    '_debug.find': <Async extends boolean, O extends FindOptions<T, Async>>(callstack: string, selector: Selector<T> | undefined, options: O | undefined, cursor: Cursor<E, U, Async>) => void;
+    '_debug.findOne': <Async extends boolean, O extends FindOptions<T, Async>>(callstack: string, selector: Selector<T>, options: O | undefined, item: U | undefined) => void;
+    '_debug.insert': (callstack: string, item: Omit<T, 'id'> & Partial<Pick<T, 'id'>>) => void;
+    '_debug.updateOne': (callstack: string, selector: Selector<T>, modifier: Modifier<T>) => void;
+    '_debug.updateMany': (callstack: string, selector: Selector<T>, modifier: Modifier<T>) => void;
+    '_debug.replaceOne': (callstack: string, selector: Selector<T>, item: Omit<T, 'id'> & Partial<Pick<T, 'id'>>) => void;
+    '_debug.removeOne': (callstack: string, selector: Selector<T>) => void;
+    '_debug.removeMany': (callstack: string, selector: Selector<T>) => void;
+}
+/**
+ * Represents a collection of data items with support for in-memory operations,
+ * persistence, reactivity, and event-based notifications. The collection provides
+ * CRUD operations, observer patterns, and batch operations.
+ * @template T - The type of the items stored in the collection.
+ * @template I - The type of the unique identifier for the items.
+ * @template U - The transformed item type after applying transformations (default is T).
+ */
+export default class Collection<T extends BaseItem<I> = BaseItem, I = any, E extends BaseItem = T, U = E> extends EventEmitter<CollectionEvents<T, E, U>> {
+    private static collections;
+    private static debugMode;
+    private static batchOperationInProgress;
+    private static fieldTracking;
+    private static onCreationCallbacks;
+    private static onDisposeCallbacks;
+    static getCollections(): Collection<any, any, any, any>[];
+    static onCreation(callback: (collection: Collection<any>) => void): void;
+    static onDispose(callback: (collection: Collection<any>) => void): void;
+    /**
+     * Enables debug mode for all collections.
+     */
+    static enableDebugMode: () => void;
+    /**
+     * Enables field tracking for all collections.
+     * @param enable - A boolean indicating whether to enable field tracking.
+     */
+    static setFieldTracking: (enable: boolean) => void;
+    /**
+     * Executes a batch operation, allowing multiple modifications to the collection
+     * while deferring index rebuilding until all operations in the batch are completed.
+     * This improves performance by avoiding repetitive index recalculations and
+     * provides atomicity for the batch of operations.
+     * Supports both synchronous and asynchronous callbacks.
+     * @param callback - The batch operation to execute.
+     * @returns A promise if the callback returns a promise, otherwise `void`.
+     */
+    static batch<ReturnType>(callback: () => Promise<ReturnType>): Promise<void>;
+    static batch<ReturnType>(callback: () => ReturnType): void;
+    readonly name: string;
+    private backend;
+    private options;
+    private isPullingSignal;
+    private isPushingSignal;
+    private readySignal;
+    private debugMode;
+    private batchOperationInProgress;
+    private isDisposed;
+    private postBatchCallbacks;
+    private fieldTracking;
+    private queryListenersMap;
+    /**
+     * Initializes a new instance of the `Collection` class with optional configuration.
+     * Sets up memory, persistence, reactivity, and indices as specified in the options.
+     * @template T - The type of the items stored in the collection.
+     * @template I - The type of the unique identifier for the items.
+     * @template U - The transformed item type after applying transformations (default is T).
+     * @param name - The name of the collection.
+     * @param dataAdapter - The data adapter for creating the collection backend.
+     * @param options - Optional configuration for the collection.
+     * @param options.name - An optional name for the collection.
+     * @param options.memory - The in-memory adapter for storing items.
+     * @param options.reactivity - The reactivity adapter for observing changes in the collection.
+     * @param options.transform - A transformation function to apply to items when retrieving them.
+     * @param options.persistence - The persistence adapter for saving and loading items.
+     * @param options.indices - An array of index providers for optimized querying.
+     * @param options.enableDebugMode - A boolean to enable or disable debug mode.
+     * @param options.fieldTracking - A boolean to enable or disable field tracking by default.
+     * @param options.transformAll - A function that will be able to solve the n+1 problem
+     */
+    constructor(options?: CollectionOptions<T, I, E, U>);
+    constructor(name: string, dataAdapter: DataAdapter, options?: CollectionOptions<T, I, E, U>);
+    isBatchOperationInProgress(): boolean;
+    /**
+     * Checks whether the collection is currently performing a pull operation
+     * ⚡️ this function is reactive!
+     * (loading data from the persistence adapter).
+     * @returns A boolean indicating if the collection is in the process of pulling data.
+     */
+    isPulling(): boolean;
+    /**
+     * Checks whether the collection is currently performing a push operation
+     * ⚡️ this function is reactive!
+     * (saving data to the persistence adapter).
+     * @returns A boolean indicating if the collection is in the process of pushing data.
+     */
+    isPushing(): boolean;
+    /**
+     * Checks whether the collection is currently performing either a pull or push operation,
+     * ⚡️ this function is reactive!
+     * indicating that it is loading or saving data.
+     * @returns A boolean indicating if the collection is in the process of loading or saving data.
+     */
+    isLoading(): boolean;
+    /**
+     * Retrieves the current debug mode status of the collection.
+     * @returns A boolean indicating whether debug mode is enabled for the collection.
+     */
+    getDebugMode(): boolean;
+    /**
+     * Enables or disables debug mode for the collection.
+     * When debug mode is enabled, additional debugging information and events are emitted.
+     * @param enable - A boolean indicating whether to enable (`true`) or disable (`false`) debug mode.
+     */
+    setDebugMode(enable: boolean): void;
+    /**
+     * Enables or disables field tracking for the collection.
+     * @param enable - A boolean indicating whether to enable (`true`) or disable (`false`) field tracking.
+     */
+    setFieldTracking(enable: boolean): void;
+    /**
+     * Resolves when the persistence adapter finished initializing
+     * and the collection is ready to be used.
+     * @returns A promise that resolves when the collection is ready.
+     * @example
+     * ```ts
+     * const collection = new Collection({
+     *   persistence: // ...
+     * })
+     * await collection.isReady()
+     *
+     * collection.insert({ name: 'Item 1' })
+     */
+    ready(): Promise<void>;
+    /**
+     * Checks if the collection is ready.
+     * ⚡️ this function is reactive!
+     * @returns A boolean indicating whether the collection is ready.
+     */
+    isReady(): boolean;
+    private profile;
+    private executeInDebugMode;
+    private transform;
+    private transformAll;
+    private getItem;
+    private getItems;
+    private withPushState;
+    private queryListeners;
+    /**
+     * Disposes the collection, unregisters persistence adapters, clears memory, and
+     * cleans up all resources used by the collection.
+     * @returns A promise that resolves when the collection is disposed.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Finds multiple items in the collection based on a selector and optional options.
+     * Returns a cursor for reactive data queries.
+     * @param [selector] - The criteria to select items.
+     * @param [options] - Options for the find operation, such as limit and sort.
+     * @returns A cursor to fetch and observe the matching items.
+     */
+    find(selector?: Selector<T>, options?: SyncFindOptions<T>): Cursor<E, U, false>;
+    find(selector: Selector<T> | undefined, options: AsyncFindOptions<T>): Cursor<E, U, true>;
+    find(selector?: Selector<T>, options?: FindOptions<T, boolean>): Cursor<E, U, boolean>;
+    /**
+     * Finds a single item in the collection based on a selector and optional options.
+     * ⚡️ this function is reactive!
+     * Returns the found item or undefined if no item matches.
+     * @param selector - The criteria to select the item.
+     * @param [options] - Options for the find operation, such as projection.
+     * @returns The found item or `undefined`.
+     */
+    findOne(selector: Selector<T>, options?: Omit<SyncFindOptions<T>, 'limit'>): U | undefined;
+    findOne(selector: Selector<T>, options: Omit<AsyncFindOptions<T>, 'limit'>): Promise<U | undefined>;
+    findOne(selector: Selector<T>, options?: Omit<FindOptions<T, boolean>, 'limit'>): Promise<U | undefined> | U | undefined;
+    /**
+     * Performs a batch operation, deferring index rebuilds and allowing multiple
+     * modifications to be made atomically. Executes any post-batch callbacks afterwards.
+     * @param callback - The batch operation to execute.
+     * @returns A promise if the callback returns a promise, otherwise void.
+     */
+    batch<ReturnType>(callback: () => Promise<ReturnType>): Promise<void>;
+    batch<ReturnType>(callback: () => ReturnType): void;
+    onPostBatch(callback: () => void): void;
+    /**
+     * Inserts a single item into the collection. Generates a unique ID if not provided.
+     * @param item - The item to insert.
+     * @returns The ID of the inserted item.
+     * @throws {Error} If the collection is disposed or the item has an invalid ID.
+     */
+    insert(item: Omit<T, 'id'> & Partial<Pick<T, 'id'>>): Promise<I>;
+    /**
+     * Inserts multiple items into the collection. Generates unique IDs for items if not provided.
+     * @param items - The items to insert.
+     * @returns An array of IDs of the inserted items.
+     * @throws {Error} If the collection is disposed or the items are invalid.
+     */
+    insertMany(items: Array<Omit<T, 'id'> & Partial<Pick<T, 'id'>>>): Promise<I[]>;
+    /**
+     * Updates a single item in the collection that matches the given selector.
+     * @param selector - The criteria to select the item to update.
+     * @param modifier - The modifications to apply to the item.
+     * @param [options] - Optional settings for the update operation.
+     * @param [options.upsert] - If `true`, creates a new item if no item matches the selector.
+     * @returns The number of items updated (0 or 1).
+     * @throws {Error} If the collection is disposed or invalid arguments are provided.
+     */
+    updateOne(selector: Selector<T>, modifier: Modifier<T>, options?: {
+        upsert?: boolean;
+    }): Promise<number>;
+    /**
+     * Updates multiple items in the collection that match the given selector.
+     * @param selector - The criteria to select the items to update.
+     * @param modifier - The modifications to apply to the items.
+     * @param [options] - Optional settings for the update operation.
+     * @param [options.upsert] - If `true`, creates new items if no items match the selector.
+     * @returns The number of items updated.
+     * @throws {Error} If the collection is disposed or invalid arguments are provided.
+     */
+    updateMany(selector: Selector<T>, modifier: Modifier<T>, options?: {
+        upsert?: boolean;
+    }): Promise<number>;
+    /**
+     * Replaces a single item in the collection that matches the given selector.
+     * @param selector - The criteria to select the item to replace.
+     * @param replacement - The item to replace the selected item with.
+     * @param [options] - Optional settings for the replace operation.
+     * @param [options.upsert] - If `true`, creates a new item if no item matches the selector.
+     * @returns The number of items replaced (0 or 1).
+     * @throws {Error} If the collection is disposed or invalid arguments are provided.
+     */
+    replaceOne(selector: Selector<T>, replacement: Omit<T, 'id'> & Partial<Pick<T, 'id'>>, options?: {
+        upsert?: boolean;
+    }): Promise<number>;
+    /**
+     * Removes a single item from the collection that matches the given selector.
+     * @param selector - The criteria to select the item to remove.
+     * @returns The number of items removed (0 or 1).
+     * @throws {Error} If the collection is disposed or invalid arguments are provided.
+     */
+    removeOne(selector: Selector<T>): Promise<number>;
+    /**
+     * Removes multiple items from the collection that match the given selector.
+     * @param selector - The criteria to select the items to remove.
+     * @returns The number of items removed.
+     * @throws {Error} If the collection is disposed or invalid arguments are provided.
+     */
+    removeMany(selector: Selector<T>): Promise<number>;
+}