@signaldb/sync 2.0.0-beta.5 → 2.0.0-beta.7

package/dist/core/src/Collection/types.d.ts

@@ -0,0 +1,28 @@
+import type { QueryOptions } from '../DataAdapter';
+import type ReactivityAdapter from '../types/ReactivityAdapter';
+export type BaseItem<I = any> = {
+    id: I;
+} & Record<string, any>;
+export type Transform<T, U = T> = ((document: T) => U) | null | undefined;
+export type TransformAll<T extends BaseItem, O extends BaseItem = T> = ((items: T[], fields: FieldSpecifier<O> | undefined) => O[]) | null | undefined;
+export type SortSpecifier<T> = {
+    [P in keyof T]?: -1 | 1;
+} & Record<string, -1 | 1>;
+export type FieldSpecifier<T> = {
+    [P in keyof T]?: 0 | 1;
+} & Record<string, 0 | 1>;
+export interface FindOptions<T extends BaseItem, Async extends boolean> extends QueryOptions<T> {
+    /** pass `false` to disable reactivity */
+    reactive?: ReactivityAdapter | false;
+    /** pass `true` to enable automatic field-level reactitivy */
+    fieldTracking?: boolean;
+    /** pass `true` to execute the query asynchronously */
+    async?: Async;
+}
+export type AsyncFindOptions<T extends BaseItem> = Omit<FindOptions<T, true>, 'async'> & {
+    async: true;
+};
+export type SyncFindOptions<T extends BaseItem> = Omit<FindOptions<T, false>, 'async'> & {
+    async?: false;
+};
+export type AnyFindOptions<T extends BaseItem> = AsyncFindOptions<T> | SyncFindOptions<T>;

package/dist/core/src/DataAdapter.d.ts

@@ -0,0 +1,35 @@
+import type { BaseItem, FieldSpecifier, SortSpecifier } from './Collection';
+import type Collection from './Collection';
+import type Modifier from './types/Modifier';
+import type Selector from './types/Selector';
+export interface QueryOptions<T extends BaseItem> {
+    /** Sort order (default: natural order) */
+    sort?: SortSpecifier<T> | undefined;
+    /** Number of results to skip at the beginning */
+    skip?: number | undefined;
+    /** Maximum number of results to return */
+    limit?: number | undefined;
+    /** Dictionary of fields to return or exclude. */
+    fields?: FieldSpecifier<T> | undefined;
+}
+export type StateChangeCallback = (state: 'active' | 'complete' | 'error') => void;
+export interface CollectionBackend<T extends BaseItem<I>, I> {
+    insert(item: T): Promise<T>;
+    updateOne(selector: Selector<T>, modifier: Modifier<T>): Promise<T[]>;
+    updateMany(selector: Selector<T>, modifier: Modifier<T>): Promise<T[]>;
+    replaceOne(selector: Selector<T>, replacement: Omit<T, 'id'> & Partial<Pick<T, 'id'>>): Promise<T[]>;
+    removeOne(selector: Selector<T>): Promise<T[]>;
+    removeMany(selector: Selector<T>): Promise<T[]>;
+    registerQuery<O extends QueryOptions<T>>(selector: Selector<T>, options: O): void;
+    unregisterQuery<O extends QueryOptions<T>>(selector: Selector<T>, options: O): void;
+    getQueryState<O extends QueryOptions<T>>(selector: Selector<T>, options: O): 'active' | 'complete' | 'error';
+    getQueryError<O extends QueryOptions<T>>(selector: Selector<T>, options: O): Error | null;
+    getQueryResult<O extends QueryOptions<T>>(selector: Selector<T>, options: O): T[];
+    executeQuery<O extends QueryOptions<T>>(selector: Selector<T>, options: O): Promise<T[]>;
+    onQueryStateChange<O extends QueryOptions<T>>(selector: Selector<T>, options: O, callback: StateChangeCallback): () => void;
+    dispose(): Promise<void>;
+    isReady(): Promise<void>;
+}
+export default interface DataAdapter {
+    createCollectionBackend<T extends BaseItem<I>, I = any, E extends BaseItem = T, U = E>(collection: Collection<T, I, E, U>, indices: string[]): CollectionBackend<T, I>;
+}

package/dist/core/src/DefaultDataAdapter.d.ts

@@ -0,0 +1,35 @@
+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';
+interface DefaultDataAdapterOptions {
+    storage?: (name: string) => StorageAdapter<any, any> | undefined;
+    onError?: (name: string, error: Error) => void;
+}
+export default class DefaultDataAdapter implements DataAdapter {
+    private items;
+    private options;
+    private storageAdapters;
+    private collections;
+    private indices;
+    private activeQueries;
+    private queryEmitters;
+    private queuedQueryUpdates;
+    private cachedQueryResults;
+    constructor(options?: DefaultDataAdapterOptions);
+    private ensureStorageAdapter;
+    private rebuildIndices;
+    private setupStorageAdapter;
+    private getIndexInfo;
+    private applyIndexDeltas;
+    private getItem;
+    private queryItems;
+    private executeQuery;
+    private flushQueuedQueryUpdates;
+    private executeAndCacheQuery;
+    private updateQueries;
+    createCollectionBackend<T extends BaseItem<I>, I = any, E extends BaseItem = T, U = E>(collection: Collection<T, I, E, U>, indices: string[]): CollectionBackend<T, I>;
+    fetchItemsFromStorage<T extends BaseItem<I>, I = any, E extends BaseItem = T, U = E>(collection?: Collection<T, I, E, U>): Promise<void>;
+}
+export {};

package/dist/core/src/WorkerDataAdapter.d.ts

@@ -0,0 +1,25 @@
+import type { BaseItem } from './Collection';
+import type Collection from './Collection';
+import type DataAdapter from './DataAdapter';
+import type { CollectionBackend } from './DataAdapter';
+interface WorkerDataAdapterOptions {
+    id?: string;
+    log?: (message: string, ...args: any[]) => void;
+}
+export default class WorkerDataAdapter implements DataAdapter {
+    private worker;
+    private options;
+    private id;
+    private isDisposed;
+    private workerReady;
+    private log;
+    private collectionReady;
+    private batchExecutionHelpers;
+    private queries;
+    constructor(worker: Worker, options: WorkerDataAdapterOptions);
+    private exec;
+    private enqueueBatched;
+    private updateQuery;
+    createCollectionBackend<T extends BaseItem<I>, I = any, E extends BaseItem = T, U = E>(collection: Collection<T, I, E, U>, indices: string[]): CollectionBackend<T, I>;
+}
+export {};

package/dist/core/src/WorkerDataAdapterHost.d.ts

@@ -0,0 +1,62 @@
+import type { BaseItem } from './Collection';
+import type { QueryOptions } from './DataAdapter';
+import type Modifier from './types/Modifier';
+import type StorageAdapter from './types/StorageAdapter';
+import type Selector from './types/Selector';
+interface WorkerContext {
+    addEventListener: (type: 'message', listener: (event: MessageEvent) => any) => void;
+    postMessage: (message: any) => void;
+}
+interface WorkerDataAdapterHostOptions {
+    id?: string;
+    storage: (name: string) => StorageAdapter<any, any>;
+    onError?: (error: Error) => void;
+    log?: (message: string, ...args: any[]) => void;
+}
+type CollectionMethods<T extends BaseItem<I>, I = any> = {
+    registerCollection: (collectionName: string, indices: string[]) => Promise<void>;
+    unregisterCollection: (collectionName: string) => Promise<void>;
+    registerQuery: <O extends QueryOptions<T>>(collectionName: string, selector: Selector<T>, options?: O) => Promise<void>;
+    unregisterQuery: <O extends QueryOptions<T>>(collectionName: string, selector: Selector<T>, options?: O) => Promise<void>;
+    executeQuery: <O extends QueryOptions<T>>(collectionName: string, selector: Selector<T>, options?: O) => Promise<T[]>;
+    insert: (collectionName: string, items: [T][]) => Promise<(T | Error)[]>;
+    updateOne: (collectionName: string, args: [Selector<T>, Modifier<T>][]) => Promise<(T[] | Error)[]>;
+    updateMany: (collectionName: string, args: [Selector<T>, Modifier<T>][]) => Promise<(T[] | Error)[]>;
+    replaceOne: (collectionName: string, args: [Selector<T>, Omit<T, 'id'> & Partial<Pick<T, 'id'>>][]) => Promise<(T[] | Error)[]>;
+    removeOne: (collectionName: string, selectors: [Selector<T>][]) => Promise<(T[] | Error)[]>;
+    removeMany: (collectionName: string, selectors: [Selector<T>][]) => Promise<(T[] | Error)[]>;
+    isReady: (collectionName: string) => Promise<void>;
+};
+export default class WorkerDataAdapterHost<T extends BaseItem<I>, I = any> {
+    private workerContext;
+    private options;
+    private id;
+    private log;
+    private storageAdapters;
+    private storageAdapterReady;
+    private collectionIndices;
+    private queries;
+    private onError;
+    constructor(workerContext: WorkerContext, options: WorkerDataAdapterHostOptions);
+    private respond;
+    private handleMessage;
+    private getIndexInfo;
+    private queryItems;
+    private executeQuery;
+    private ensureQuery;
+    private emitQueryUpdate;
+    private ensureStorageAdapter;
+    private checkQueryUpdates;
+    protected registerCollection: CollectionMethods<T, I>['registerCollection'];
+    protected unregisterCollection: CollectionMethods<T, I>['unregisterCollection'];
+    protected registerQuery: CollectionMethods<T, I>['registerQuery'];
+    protected unregisterQuery: CollectionMethods<T, I>['unregisterQuery'];
+    protected insert: CollectionMethods<T, I>['insert'];
+    protected updateOne: CollectionMethods<T, I>['updateOne'];
+    protected updateMany: CollectionMethods<T, I>['updateMany'];
+    protected replaceOne: CollectionMethods<T, I>['replaceOne'];
+    protected removeOne: CollectionMethods<T, I>['removeOne'];
+    protected removeMany: CollectionMethods<T, I>['removeMany'];
+    protected isReady: CollectionMethods<T, I>['isReady'];
+}
+export {};

package/dist/core/src/createIndex.d.ts

@@ -0,0 +1,7 @@
+import type { BaseItem } from './Collection/types';
+/**
+ * creates an index for a specific field
+ * @param field name of the field
+ * @returns an index provider to pass to the `indices` option of the collection constructor
+ */
+export default function createIndex<T extends BaseItem<I> = BaseItem, I = any>(field: string): import("./types/IndexProvider").default<T, I>;

package/dist/core/src/createIndexProvider.d.ts

@@ -0,0 +1,8 @@
+import type { BaseItem } from './Collection';
+import type IndexProvider from './types/IndexProvider';
+/**
+ * Creates an IndexProvider based on the given definition.
+ * @param definition - The definition of the IndexProvider.
+ * @returns The created IndexProvider.
+ */
+export default function createIndexProvider<T extends BaseItem<I> = BaseItem, I = any>(definition: IndexProvider<T, I>): IndexProvider<T, I>;

package/dist/core/src/createReactivityAdapter.d.ts

@@ -0,0 +1,8 @@
+import type Dependency from './types/Dependency';
+import type ReactivityAdapter from './types/ReactivityAdapter';
+/**
+ * Creates an ReactivityAdapter based on the given definition.
+ * @param definition - The definition of the ReactivityAdapter.
+ * @returns The created ReactivityAdapter.
+ */
+export default function createReactivityAdapter<T extends Dependency = Dependency>(definition: ReactivityAdapter<T>): ReactivityAdapter<T>;

package/dist/core/src/createStorageAdapter.d.ts

@@ -0,0 +1,9 @@
+import type StorageAdapter from './types/StorageAdapter';
+/**
+ * Creates an StorageAdapter based on the given definition.
+ * @param definition - The definition of the StorageAdapter.
+ * @returns The created StorageAdapter.
+ */
+export default function createStorageAdapter<T extends {
+    id: I;
+} & Record<string, any>, I>(definition: StorageAdapter<T, I>): StorageAdapter<T, I>;

package/dist/core/src/getIndexInfo.d.ts

@@ -0,0 +1,39 @@
+import type { AsynchronousQueryFunction, SynchronousQueryFunction } from './types/IndexProvider';
+import type { FlatSelector } from './types/Selector';
+import type Selector from './types/Selector';
+import type { BaseItem } from './Collection/types';
+type IndexInfo<T extends BaseItem<I> = BaseItem, I = any> = {
+    matched: boolean;
+    ids: I[];
+    optimizedSelector: FlatSelector<T>;
+};
+/**
+ * Retrieves merged index information for a given flat selector by querying multiple
+ * index providers. Combines results from all index providers to determine matched ids
+ * and an optimized selector.
+ * @template T - The type of the items in the collection.
+ * @template I - The type of the unique identifier for the items.
+ * @param queryFunctions - An array of index providers to query.
+ * @param selector - The flat selector used to filter items.
+ * @returns An object containing:
+ *   - `matched`: A boolean indicating if the selector matched any items.
+ *   - `ids`: An array of matched item ids.
+ *   - `optimizedSelector`: A flat selector optimized based on the index results.
+ */
+export declare function getMergedIndexInfo<T extends BaseItem<I> = BaseItem, I = any>(queryFunctions: (SynchronousQueryFunction<T, I> | AsynchronousQueryFunction<T, I>)[], selector: FlatSelector<T>): IndexInfo<T, I> | Promise<IndexInfo<T, I>>;
+/**
+ * Retrieves index information for a given complex selector by querying multiple
+ * index providers. Handles nested `$and` and `$or` conditions in the selector and
+ * optimizes the selector to minimize processing overhead.
+ * @template T - The type of the items in the collection.
+ * @template I - The type of the unique identifier for the items.
+ * @param queryFunctions - An array of index providers to query.
+ * @param selector - The complex selector used to filter items.
+ * @returns An object containing:
+ *   - `matched`: A boolean indicating if the selector matched any items.
+ *   - `ids`: An array of matched item ids.
+ *   - `optimizedSelector`: A selector optimized based on the index results, with unused
+ *     conditions removed.
+ */
+export default function getIndexInfo<QueryFunction extends SynchronousQueryFunction<T, I> | AsynchronousQueryFunction<T, I>, T extends BaseItem<I> = BaseItem, I = any>(queryFunctions: QueryFunction[], selector: Selector<T>): QueryFunction extends AsynchronousQueryFunction<T, I> ? Promise<IndexInfo<T, I>> : IndexInfo<T, I>;
+export {};

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

@@ -0,0 +1,22 @@
+export type { default as ReactivityAdapter } from './types/ReactivityAdapter';
+export type { default as StorageAdapter, Changeset, } from './types/StorageAdapter';
+export type { default as Selector } from './types/Selector';
+export type { default as Modifier } from './types/Modifier';
+export type { BaseItem, ObserveCallbacks, CursorOptions, Transform, TransformAll, SortSpecifier, FieldSpecifier, AnyFindOptions, AsyncFindOptions, FindOptions, SyncFindOptions, CollectionOptions, } from './Collection';
+export type { default as DataAdapter } from './DataAdapter';
+export { default as Cursor } from './Collection/Cursor';
+export { default as Collection } from './Collection';
+export { default as createStorageAdapter } from './createStorageAdapter';
+export { default as createReactivityAdapter } from './createReactivityAdapter';
+export { default as isEqual } from './utils/isEqual';
+export { default as modify } from './utils/modify';
+export { default as randomId } from './utils/randomId';
+export { default as EventEmitter } from './utils/EventEmitter';
+export { default as get } from './utils/get';
+export { default as serializeValue } from './utils/serializeValue';
+export { default as reactiveOrAsync, unwrap } from './utils/reactiveOrAsync';
+export { default as DefaultDataAdapter } from './DefaultDataAdapter';
+export { default as AsyncDataAdapter } from './AsyncDataAdapter';
+export { default as WorkerDataAdapter } from './WorkerDataAdapter';
+export { default as WorkerDataAdapterHost } from './WorkerDataAdapterHost';
+export { default as AutoFetchDataAdapter } from './AutoFetchDataAdapter';

package/dist/core/src/types/Dependency.d.ts

@@ -0,0 +1,4 @@
+export default interface Dependency {
+    depend(): void;
+    notify(): void;
+}

package/dist/core/src/types/IndexProvider.d.ts

@@ -0,0 +1,26 @@
+import type { BaseItem } from '../Collection';
+import type { FlatSelector } from './Selector';
+export type IndexResult<IdType> = {
+    ids: IdType[];
+    fields: string[];
+    keepSelector?: boolean;
+    matched: true;
+} | {
+    ids?: never;
+    fields?: never;
+    keepSelector?: never;
+    matched: false;
+};
+export type SynchronousQueryFunction<T extends BaseItem<I> = BaseItem, I = any> = (selector: FlatSelector<T>) => IndexResult<I>;
+export type AsynchronousQueryFunction<T extends BaseItem<I> = BaseItem, I = any> = (selector: FlatSelector<T>) => Promise<IndexResult<I>>;
+interface IndexProvider<T extends BaseItem<I> = BaseItem, I = any> {
+    query: SynchronousQueryFunction<T, I>;
+    rebuild(items: T[]): void;
+    insert(items: T[]): void;
+    remove(items: T[]): void;
+    update(pairs: {
+        oldItem: T;
+        newItem: T;
+    }[]): void;
+}
+export default IndexProvider;

package/dist/core/src/types/Modifier.d.ts

@@ -0,0 +1,46 @@
+import type { DotNotation, GetType } from './Selector';
+type Dictionary<T> = Record<string, T>;
+type PartialMapTo<T, M> = Partial<Record<DotNotation<T>, M>> & Dictionary<M>;
+type OnlyElementsOfArrays<T> = T extends any[] ? Partial<T[0]> : never;
+type ElementsOf<T> = {
+    [P in DotNotation<T>]?: OnlyElementsOfArrays<GetType<T, P>>;
+};
+type PushModifier<T> = {
+    [P in DotNotation<T>]?: OnlyElementsOfArrays<GetType<T, P>> | {
+        $each?: GetType<T, P> | undefined;
+        $position?: number | undefined;
+        $slice?: number | undefined;
+        $sort?: 1 | -1 | Dictionary<number> | undefined;
+    };
+};
+type ArraysOrEach<T> = {
+    [P in DotNotation<T>]?: OnlyElementsOfArrays<GetType<T, P>> | {
+        $each: GetType<T, P>;
+    };
+};
+type CurrentDateModifier = {
+    $type: 'timestamp' | 'date';
+} | true;
+type Modifier<T extends Dictionary<any> = Dictionary<any>> = {
+    $currentDate?: (Partial<Record<DotNotation<T>, CurrentDateModifier>> & Dictionary<CurrentDateModifier>) | undefined;
+    $inc?: (PartialMapTo<T, number> & Dictionary<number>) | undefined;
+    $min?: (PartialMapTo<T, Date | number> & Dictionary<Date | number>) | undefined;
+    $max?: (PartialMapTo<T, Date | number> & Dictionary<Date | number>) | undefined;
+    $mul?: (PartialMapTo<T, number> & Dictionary<number>) | undefined;
+    $rename?: (PartialMapTo<T, string> & Dictionary<string>) | undefined;
+    $set?: ({
+        [P in DotNotation<T>]?: GetType<T, P>;
+    } & Dictionary<any>) | undefined;
+    $setOnInsert?: ({
+        [P in DotNotation<T>]?: GetType<T, P>;
+    } & Dictionary<any>) | undefined;
+    $unset?: (PartialMapTo<T, string | boolean | 1 | 0> & Dictionary<any>) | undefined;
+    $addToSet?: (ArraysOrEach<T> & Dictionary<any>) | undefined;
+    $push?: (PushModifier<T> & Dictionary<any>) | undefined;
+    $pull?: (ElementsOf<T> & Dictionary<any>) | undefined;
+    $pullAll?: ({
+        [P in DotNotation<T>]?: GetType<T, P>;
+    } & Dictionary<any>) | undefined;
+    $pop?: (PartialMapTo<T, 1 | -1> & Dictionary<1 | -1>) | undefined;
+};
+export default Modifier;

package/dist/core/src/types/ReactivityAdapter.d.ts

@@ -0,0 +1,6 @@
+import type Dependency from './Dependency';
+export default interface ReactivityAdapter<T extends Dependency = Dependency> {
+    create(): T;
+    onDispose?(callback: () => void, Dependency: T): void;
+    isInScope?(): boolean;
+}

package/dist/core/src/types/Selector.d.ts

@@ -0,0 +1,46 @@
+export interface FieldExpression<T> {
+    $eq?: T;
+    $gt?: T;
+    $gte?: T;
+    $lt?: T;
+    $lte?: T;
+    $in?: T[] | undefined;
+    $nin?: T[];
+    $ne?: T;
+    $exists?: boolean;
+    $not?: FieldExpression<T>;
+    $expr?: FieldExpression<T>;
+    $jsonSchema?: any;
+    $mod?: number[];
+    $regex?: RegExp | string;
+    $options?: string;
+    $where?: string | ((this: T) => boolean);
+    $all?: T[];
+    $elemMatch?: T extends object ? Query<T> : FieldExpression<T>;
+    $size?: number;
+    $bitsAllClear?: any;
+    $bitsAllSet?: any;
+    $bitsAnyClear?: any;
+    $bitsAnySet?: any;
+}
+export type DotNotation<T> = {
+    [K in keyof T & string]: T[K] extends Array<infer U> ? `${K}` | `${K}.$` | `${K}.${DotNotation<U>}` : T[K] extends object ? `${K}` | `${K}.${DotNotation<T[K]>}` : `${K}`;
+}[keyof T & string];
+export type GetType<T, P extends string> = P extends `${infer H}.${infer R}` ? H extends keyof T ? T[H] extends Array<infer U> ? GetType<U, R> : GetType<T[H], R> : H extends '$' ? T extends Array<infer U> ? GetType<U, R> : never : never : P extends keyof T ? T[P] : never;
+type FlatQuery<T> = {
+    [P in DotNotation<T>]?: FlatQueryValue<T, P>;
+};
+type FieldValue<U> = U extends string ? string | RegExp | FieldExpression<string> : U | FieldExpression<U>;
+type FlatQueryValue<T, P extends string> = GetType<T, P> extends never ? never : GetType<T, P> extends Array<infer U> ? FieldValue<U> | FieldValue<U[]> : FieldValue<GetType<T, P>>;
+type Query<T> = FlatQuery<T> & {
+    $or?: Query<T>[];
+    $and?: Query<T>[];
+    $nor?: Query<T>[];
+};
+export type FlatSelector<T extends Record<string, any>> = FlatQuery<T> & {
+    $or?: never;
+    $and?: never;
+    $nor?: never;
+};
+type Selector<T extends Record<string, any>> = Query<T>;
+export default Selector;

package/dist/core/src/types/Signal.d.ts

@@ -0,0 +1,4 @@
+export default interface Signal<T> {
+    get(): T;
+    set(value: T): void;
+}

package/dist/core/src/types/StorageAdapter.d.ts

@@ -0,0 +1,20 @@
+export interface Changeset<T> {
+    added: T[];
+    modified: T[];
+    removed: T[];
+}
+export default interface StorageAdapter<T extends {
+    id: I;
+} & Record<string, any>, I> {
+    setup(): Promise<void>;
+    teardown(): Promise<void>;
+    readAll(): Promise<T[]>;
+    readIds(positions: I[]): Promise<T[]>;
+    createIndex(field: string): Promise<void>;
+    dropIndex(field: string): Promise<void>;
+    readIndex(field: string): Promise<Map<any, Set<I>>>;
+    insert(items: T[]): Promise<void>;
+    replace(items: T[]): Promise<void>;
+    remove(items: T[]): Promise<void>;
+    removeAll(): Promise<void>;
+}

package/dist/core/src/utils/EventEmitter.d.ts

@@ -0,0 +1,71 @@
+/**
+ * A strongly‑typed EventEmitter.
+ */
+export default class EventEmitter<Events extends Record<string | symbol, any>> {
+    private _maxListeners;
+    /**
+     * We store a set of the listeners for each event.
+     */
+    private _listenerStore;
+    setMaxListeners(max: number): this;
+    /**
+     * Subscribe to an event with a listener function.
+     * @param eventName The event name (key of E).
+     * @param listener  A function that receives the emitted arguments.
+     * @returns         The emitter instance (for chaining).
+     */
+    on<K extends keyof Events>(eventName: K, listener: Events[K]): this;
+    /**
+     * Subscribe to an event with a listener function.
+     * @param eventName The event name (key of E).
+     * @param listener  A function that receives the emitted arguments.
+     * @returns         The emitter instance (for chaining).
+     */
+    addListener<K extends keyof Events>(eventName: K, listener: Events[K]): this;
+    /**
+     * Subscribe to an event, handling it only once. Automatically removes
+     * the listener after it fires the first time.
+     * @param eventName The event name (key of E).
+     * @param listener  A function that receives the emitted arguments.
+     * @returns         The emitter instance (for chaining).
+     */
+    once<K extends keyof Events>(eventName: K, listener: Events[K]): this;
+    /**
+     * Unsubscribe a previously subscribed listener.
+     * @param eventName The event name (key of E).
+     * @param listener  The original function passed to `on` or `once`.
+     * @returns         The emitter instance (for chaining).
+     */
+    off<K extends keyof Events>(eventName: K, listener: Events[K]): this;
+    /**
+     * Unsubscribe a previously subscribed listener.
+     * @param eventName The event name (key of E).
+     * @param listener  The original function passed to `on` or `once`.
+     * @returns         The emitter instance (for chaining).
+     */
+    removeListener<K extends keyof Events>(eventName: K, listener: Events[K]): this;
+    /**
+     * Emit (dispatch) an event with a variable number of arguments.
+     * @param eventName The event name (key of E).
+     * @param args      The arguments to pass to subscribed listeners.
+     */
+    emit<K extends keyof Events>(eventName: K, ...args: Parameters<Events[K]>): void;
+    /**
+     * Returns the array of listener functions currently registered for a given event.
+     * @param eventName The event name (key of E).
+     * @returns         An array of listener functions.
+     */
+    listeners<K extends keyof Events>(eventName: K): Array<(...args: Parameters<Events[K]>) => void>;
+    /**
+     * Returns the number of listeners for a given event.
+     * @param eventName The event name (key of E).
+     * @returns         The number of listeners.
+     */
+    listenerCount<K extends keyof Events>(eventName: K): number;
+    /**
+     * Removes all listeners for a given event, or all events if none is specified.
+     * @param eventName Optional. If omitted, clears all events’ listeners.
+     * @returns         The emitter instance (for chaining).
+     */
+    removeAllListeners<K extends keyof Events>(eventName?: K): this;
+}

package/dist/core/src/utils/batchOnNextTick.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Groups multiple calls by key and flushes them on the next tick (macrotask).
+ * @param onFlush - Function that will be called with the key and all queued items when flushing.
+ * @returns An object with `enqueue` and `flush` methods.
+ * @example
+ *   const batcher = batchOnNextTick<string>(async (key, items) => {
+ *     // items is an array of { args, resolve, reject }
+ *     // do something once with all args...
+ *   })
+ *
+ *   batcher.enqueue("my-key", [arg1, arg2])
+ */
+export default function batchOnNextTick<TKey>(onFlush: (key: TKey, items: any[][]) => Promise<any[]>): {
+    enqueue: (key: TKey, args: any[]) => Promise<any>;
+    flush: (key: TKey) => Promise<void>;
+};

package/dist/core/src/utils/compact.d.ts

@@ -0,0 +1,9 @@
+type Truthy<T> = T extends false | '' | 0 | null | undefined ? never : T;
+/**
+ * Filters out falsy values (`false`, `''`, `0`, `null`, `undefined`) from an array.
+ * @template T - The type of the elements in the array.
+ * @param array - The array to filter.
+ * @returns A new array containing only the truthy values from the input array.
+ */
+export default function compact<T>(array: T[]): Truthy<T>[];
+export {};

package/dist/core/src/utils/createSignal.d.ts

@@ -0,0 +1,14 @@
+import type ReactivityAdapter from '../types/ReactivityAdapter';
+import type Signal from '../types/Signal';
+/**
+ * Creates a reactive signal for managing state and triggering dependencies.
+ * The signal holds a value and provides methods to get and set the value,
+ * with optional equality checks and dependency tracking.
+ * @template T - The type of the value held by the signal.
+ * @param reactivityAdapter - An optional reactivity adapter for managing dependencies.
+ * @param initialValue - The initial value of the signal.
+ * @param isEqual - A custom equality function to determine if the new value is different
+ *   from the current value (default is `Object.is`).
+ * @returns A signal object with `get` and `set` methods to manage the value.
+ */
+export default function createSignal<T>(reactivityAdapter: ReactivityAdapter | undefined, initialValue: T, isEqual?: (a: T, b: T) => boolean): Signal<T>;

package/dist/core/src/utils/deepClone.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Performs a deep clone of a value, supporting various types including arrays, objects,
+ * Maps, Sets, Dates, and RegExps. Functions are not supported and will throw an error.
+ * @template T - The type of the value to clone.
+ * @param value - The value to deep clone.
+ * @returns A deep copy of the provided value.
+ * @throws {Error} An error if the value is a function, as cloning functions is not supported.
+ */
+export declare function clone<T>(value: T): T;
+/**
+ * Creates a deep clone of an object. Uses the `structuredClone` function if available,
+ * otherwise falls back to a manual deep clone implementation.
+ * @template T - The type of the object to clone.
+ * @param object - The object to deep clone.
+ * @returns A deep copy of the provided object.
+ */
+export default function deepClone<T>(object: T): T;

package/dist/core/src/utils/get.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Retrieves the value at a specified path within an object.
+ * Supports dot and bracket notation for navigating nested properties.
+ * @template T - The type of the object to retrieve the value from.
+ * @param value - The object to navigate.
+ * @param path - The path (dot or bracket notation) to the desired value.
+ * @returns The value at the specified path, or `undefined` if the path does not exist.
+ */
+export default function get<T extends Record<string, any>>(value: T, path: string): any;

package/dist/core/src/utils/getMatchingKeys.d.ts

@@ -0,0 +1,19 @@
+import type { BaseItem } from '../Collection/types';
+import type { FlatSelector } from '../types/Selector';
+type KeyResult = {
+    include: (string | null)[] | null;
+    exclude: (string | null)[] | null;
+};
+/**
+ * Extracts the matching and excluded keys for a given field in a selector.
+ * Supports serialized values and `$in`/`$nin` field expressions for optimization.
+ * Returns `null` for include/exclude if the field cannot be optimized.
+ * @template T - The type of the items in the selector.
+ * @template I - The type of the unique identifier for the items.
+ * @param field - The name of the field to extract matching keys for.
+ * @param selector - The selector object containing query criteria.
+ * @returns An object containing arrays of serialized included and excluded keys,
+ *   or `null` if the field cannot be optimized.
+ */
+export default function getMatchingKeys<T extends BaseItem<I> = BaseItem, I = any>(field: string, selector: FlatSelector<T>): KeyResult;
+export {};

package/dist/core/src/utils/intersection.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Computes the intersection of multiple arrays, returning an array of unique elements
+ * that are present in all the input arrays.
+ * @template T - The type of elements in the arrays.
+ * @param arrays - A variable number of arrays to compute the intersection of.
+ * @returns An array containing the unique elements found in all the input arrays.
+ *   - If no arrays are provided, returns an empty array.
+ */
+export default function intersection<T>(...arrays: T[][]): T[];

package/dist/core/src/utils/isEqual.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Compares two values for deep equality.
+ * @param a - The first value to compare.
+ * @param b - The second value to compare.
+ * @returns - Returns `true` if the two values are deeply equal, otherwise `false`.
+ * @example
+ * isEqual({ a: 1 }, { a: 1 }); // true
+ * isEqual([1, 2], [1, 2]);     // true
+ * isEqual(new Date(0), new Date(0)); // true
+ * isEqual(/abc/, /abc/);       // true
+ * isEqual({ a: 1 }, { a: 2 }); // false
+ * isEqual(null, null);         // true
+ */
+export default function isEqual<T, K>(a: T, b: K): boolean;