@signaldb/core
Version:
SignalDB is a client-side database that provides a simple MongoDB-like interface to the data with first-class typescript support to achieve an optimistic UI. Data persistence can be achieved by using storage providers that store the data through a JSON in
113 lines (112 loc) • 6.14 kB
TypeScript
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> extends FindOptions<T> {
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 transformations (default is T).
*/
export default class Cursor<T extends BaseItem, U = T> {
private observer;
private getFilteredItems;
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.
*/
constructor(getItems: () => T[], options?: CursorOptions<T, U>);
private addGetters;
private transform;
private getItems;
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.
*/
forEach(callback: (item: U) => 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): 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[];
/**
* 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;
/**
* 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<U>, 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;
}