@signaldb/core 1.0.0

package/dist/Collection/index.d.ts

@@ -0,0 +1,235 @@
+import type MemoryAdapter from '../types/MemoryAdapter';
+import type ReactivityAdapter from '../types/ReactivityAdapter';
+import type PersistenceAdapter from '../types/PersistenceAdapter';
+import EventEmitter from '../types/EventEmitter';
+import type Selector from '../types/Selector';
+import type Modifier from '../types/Modifier';
+import type IndexProvider from '../types/IndexProvider';
+import Cursor from './Cursor';
+import type { BaseItem, FindOptions, Transform } from './types';
+export type { BaseItem, Transform, SortSpecifier, FieldSpecifier, FindOptions } 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, U = T> {
+    memory?: MemoryAdapter;
+    reactivity?: ReactivityAdapter;
+    transform?: Transform<T, U>;
+    persistence?: PersistenceAdapter<T, I>;
+    indices?: IndexProvider<T, I>[];
+    enableDebugMode?: boolean;
+    fieldTracking?: boolean;
+}
+interface CollectionEvents<T extends BaseItem, U = T> {
+    added: (item: T) => void;
+    changed: (item: T, modifier: Modifier<T>) => void;
+    removed: (item: T) => void;
+    'persistence.init': () => void;
+    'persistence.error': (error: Error) => void;
+    'persistence.transmitted': () => void;
+    'persistence.received': () => void;
+    'persistence.pullStarted': () => void;
+    'persistence.pullCompleted': () => void;
+    'persistence.pushStarted': () => void;
+    'persistence.pushCompleted': () => void;
+    'observer.created': <O extends FindOptions<T>>(selector?: Selector<T>, options?: O) => void;
+    'observer.disposed': <O extends FindOptions<T>>(selector?: Selector<T>, options?: O) => void;
+    getItems: (selector: Selector<T> | undefined) => void;
+    find: <O extends FindOptions<T>>(selector: Selector<T> | undefined, options: O | undefined, cursor: Cursor<T, U>) => void;
+    findOne: <O extends FindOptions<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;
+    removeOne: (selector: Selector<T>) => void;
+    removeMany: (selector: Selector<T>) => void;
+    '_debug.getItems': (callstack: string, selector: Selector<T> | undefined, measuredTime: number) => void;
+    '_debug.find': <O extends FindOptions<T>>(callstack: string, selector: Selector<T> | undefined, options: O | undefined, cursor: Cursor<T, U>) => void;
+    '_debug.findOne': <O extends FindOptions<T>>(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.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, U = T> extends EventEmitter<CollectionEvents<T, U>> {
+    static collections: Collection<any, any>[];
+    static debugMode: boolean;
+    static batchOperationInProgress: boolean;
+    static fieldTracking: boolean;
+    /**
+     * 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.
+     * @param callback - The batch operation to execute.
+     */
+    static batch(callback: () => void): void;
+    private options;
+    private persistenceAdapter;
+    private isPullingSignal;
+    private isPushingSignal;
+    private indexProviders;
+    private indicesOutdated;
+    private idIndex;
+    private debugMode;
+    private batchOperationInProgress;
+    private isDisposed;
+    private postBatchCallbacks;
+    private fieldTracking;
+    /**
+     * 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 options - Optional configuration 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.
+     */
+    constructor(options?: CollectionOptions<T, I, U>);
+    /**
+     * 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;
+    private profile;
+    private executeInDebugMode;
+    private rebuildIndices;
+    private rebuildAllIndices;
+    private getIndexInfo;
+    private getItemAndIndex;
+    private deleteFromIdIndex;
+    private memory;
+    private memoryArray;
+    private transform;
+    private getItems;
+    /**
+     * 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.
+     * @template O - The options type for the find operation.
+     * @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<O extends FindOptions<T>>(selector?: Selector<T>, options?: O): Cursor<T, U>;
+    /**
+     * 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.
+     * @template O - The options type for the find operation.
+     * @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<O extends Omit<FindOptions<T>, 'limit'>>(selector: Selector<T>, options?: O): NonNullable<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.
+     */
+    batch(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'>>): 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'>>>): 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.
+     * @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>): 0 | 1;
+    /**
+     * 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.
+     * @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>): 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>): 0 | 1;
+    /**
+     * 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>): number;
+}

package/dist/Collection/types.d.ts

@@ -0,0 +1,25 @@
+import type ReactivityAdapter from '../types/ReactivityAdapter';
+export type BaseItem<I = any> = {
+    id: I;
+} & Record<string, any>;
+export type Transform<T, U = T> = ((doc: T) => U) | 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> {
+    /** 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;
+    /** pass `false` to disable reactivity */
+    reactive?: ReactivityAdapter | false;
+    /** pass `true` to enable automatic field-level reactitivy */
+    fieldTracking?: boolean;
+}

package/dist/ReplicatedCollection.d.ts

@@ -0,0 +1,60 @@
+import Collection from './Collection';
+import type { BaseItem, CollectionOptions } from './Collection';
+import type { Changeset, LoadResponse } from './types/PersistenceAdapter';
+interface ReplicationOptions<T extends {
+    id: I;
+} & Record<string, any>, I> {
+    pull: () => Promise<LoadResponse<T>>;
+    push?(changes: Changeset<T>, items: T[]): Promise<void>;
+    registerRemoteChange?: (onChange: (data?: LoadResponse<T>) => void | Promise<void>) => Promise<void>;
+}
+/**
+ * Creates a persistence adapter for replicating a collection, enabling pull and push
+ * operations for synchronizing with a remote source. Supports optional remote change registration.
+ * @template T - The type of the items being replicated.
+ * @template I - The type of the unique identifier for the items.
+ * @param options - The options for configuring the replication adapter.
+ * @param options.pull - A function to fetch data from the remote source.
+ * @param options.push - An optional function to send changes and items to the remote source.
+ * @param options.registerRemoteChange - An optional function to register a listener for remote changes.
+ * @returns A persistence adapter configured for replication.
+ */
+export declare function createReplicationAdapter<T extends {
+    id: I;
+} & Record<string, any>, I>(options: ReplicationOptions<T, I>): import("./types/PersistenceAdapter").default<T, unknown>;
+export type ReplicatedCollectionOptions<T extends BaseItem<I>, I, U = T> = CollectionOptions<T, I, U> & ReplicationOptions<T, I>;
+/**
+ * Extends the `Collection` class to support replication with remote sources.
+ * Handles pull and push operations, remote change registration, and enhanced loading states.
+ * @template T - The type of the items 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 ReplicatedCollection<T extends BaseItem<I> = BaseItem, I = any, U = T> extends Collection<T, I, U> {
+    private isPullingRemoteSignal;
+    private isPushingRemoteSignal;
+    /**
+     * Creates a new instance of the `ReplicatedCollection` class.
+     * Sets up the replication adapter, combining it with an optional persistence adapter, and
+     * initializes signals for tracking remote pull and push operations.
+     * @param options - The configuration options for the replicated collection.
+     * @param options.pull - A function to fetch data from the remote source.
+     * @param options.push - An optional function to send changes and items to the remote source.
+     * @param options.registerRemoteChange - An optional function to register a listener for remote changes.
+     * @param options.persistence - An optional persistence adapter to combine with replication.
+     * @param options.reactivity - A reactivity adapter for observing changes in the collection.
+     * @param options.transform - A transformation function to apply to items when retrieving them.
+     * @param options.indices - An array of index providers for optimized querying.
+     * @param options.enableDebugMode - A boolean to enable or disable debug mode.
+     */
+    constructor(options: ReplicatedCollectionOptions<T, I, U>);
+    /**
+     * Checks whether the collection is currently performing any loading operation,
+     * including pulling or pushing data from/to the remote source, or standard
+     * persistence adapter operations.
+     * ⚡️ this function is reactive!
+     * @returns A boolean indicating if the collection is currently loading or synchronizing.
+     */
+    isLoading(): boolean;
+}
+export {};

package/dist/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/createMemoryAdapter.d.ts

@@ -0,0 +1,7 @@
+import type MemoryAdapter from './types/MemoryAdapter';
+/**
+ * Creates an MemoryAdapter based on the given definition.
+ * @param definition - The definition of the MemoryAdapter.
+ * @returns The created MemoryAdapter.
+ */
+export default function createMemoryAdapter(definition: MemoryAdapter): MemoryAdapter<Record<string, any>>;

package/dist/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/index.cjs.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const index = require("./index.cjs2.js");
+const AutoFetchCollection = require("./index.cjs3.js");
+const combinePersistenceAdapters = require("./index.cjs4.js");
+const createIndexProvider = require("./index.cjs5.js");
+const createMemoryAdapter = require("./index.cjs6.js");
+const createPersistenceAdapter = require("./index.cjs7.js");
+const createReactivityAdapter = require("./index.cjs8.js");
+const isEqual = require("./index.cjs9.js");
+const modify = require("./index.cjs10.js");
+const randomId = require("./index.cjs11.js");
+const createIndex = require("./index.cjs12.js");
+exports.Collection = index.default;
+exports.AutoFetchCollection = AutoFetchCollection;
+exports.combinePersistenceAdapters = combinePersistenceAdapters.default;
+exports.createIndexProvider = createIndexProvider;
+exports.createMemoryAdapter = createMemoryAdapter;
+exports.createPersistenceAdapter = createPersistenceAdapter;
+exports.createReactivityAdapter = createReactivityAdapter;
+exports.isEqual = isEqual;
+exports.modify = modify;
+exports.randomId = randomId;
+exports.createIndex = createIndex.default;

package/dist/index.cjs10.js

@@ -0,0 +1,8 @@
+"use strict";
+const updater = require("mingo/updater");
+function modify(item, modifier) {
+  const clonedItem = Object.assign({}, item);
+  updater.updateObject(clonedItem, modifier);
+  return clonedItem;
+}
+module.exports = modify;

package/dist/index.cjs11.js

@@ -0,0 +1,5 @@
+"use strict";
+function randomId() {
+  return Math.floor(Math.random() * 1e17).toString(16);
+}
+module.exports = randomId;

package/dist/index.cjs12.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: "Module" } });
+const createIndexProvider = require("./index.cjs5.js");
+const get = require("./index.cjs26.js");
+const getMatchingKeys = require("./index.cjs27.js");
+const serializeValue = require("./index.cjs16.js");
+function createExternalIndex(field, index) {
+  return createIndexProvider({
+    query(selector) {
+      const keys = getMatchingKeys(field, selector);
+      if (keys == null)
+        return { matched: false };
+      const itemPositions = keys.reduce((memo, key) => [...memo, ...index.get(key) || []], []);
+      return {
+        matched: true,
+        positions: itemPositions,
+        fields: [field]
+      };
+    },
+    rebuild() {
+    }
+  });
+}
+function createIndex(field) {
+  const index = /* @__PURE__ */ new Map();
+  return Object.assign(Object.assign({}, createExternalIndex(field, index)), { rebuild(items) {
+    index.clear();
+    items.forEach((item, i) => {
+      const value = serializeValue(get(item, field));
+      const current = index.get(value) || /* @__PURE__ */ new Set();
+      current.add(i);
+      index.set(value, current);
+    });
+  } });
+}
+exports.createExternalIndex = createExternalIndex;
+exports.default = createIndex;

package/dist/index.cjs13.js

@@ -0,0 +1,26 @@
+"use strict";
+const events = require("events");
+class EventEmitter extends events.EventEmitter {
+  /**
+   * Registers a listener for the specified event.
+   * @template K - The key of the event in the `Events` record.
+   * @param event - The name of the event to listen for.
+   * @param listener - The listener function to execute when the event is emitted.
+   * @returns The `EventEmitter` instance, allowing for method chaining.
+   */
+  on(event, listener) {
+    super.on(event, listener);
+    return this;
+  }
+  /**
+   * Emits the specified event, triggering all registered listeners for that event.
+   * @template K - The key of the event in the `Events` record.
+   * @param event - The name of the event to emit.
+   * @param args - The arguments to pass to the event listeners.
+   * @returns A boolean indicating whether any listeners were triggered.
+   */
+  emit(event, ...args) {
+    return super.emit(event, ...args);
+  }
+}
+module.exports = EventEmitter;

package/dist/index.cjs14.js

@@ -0,0 +1,7 @@
+"use strict";
+const mingo = require("mingo");
+function match(item, selector) {
+  const query = new mingo.Query(selector);
+  return query.test(item);
+}
+module.exports = match;

package/dist/index.cjs15.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: "Module" } });
+function clone(value) {
+  if (typeof value === "function")
+    throw new Error("Cloning functions is not supported");
+  if (value === null || typeof value !== "object")
+    return value;
+  if (value instanceof Date)
+    return new Date(value.getTime());
+  if (Array.isArray(value))
+    return value.map((item) => clone(item));
+  if (value instanceof Map) {
+    const result2 = /* @__PURE__ */ new Map();
+    value.forEach((val, key) => {
+      result2.set(key, clone(val));
+    });
+    return result2;
+  }
+  if (value instanceof Set) {
+    const result2 = /* @__PURE__ */ new Set();
+    value.forEach((val) => {
+      result2.add(clone(val));
+    });
+    return result2;
+  }
+  if (value instanceof RegExp)
+    return new RegExp(value);
+  const result = {};
+  for (const key in value) {
+    if (Object.hasOwnProperty.call(value, key)) {
+      result[key] = clone(value[key]);
+    }
+  }
+  return result;
+}
+function deepClone(obj) {
+  if (typeof structuredClone === "function")
+    return structuredClone(obj);
+  /* istanbul ignore next -- @preserve */
+  return clone(obj);
+}
+exports.clone = clone;
+exports.default = deepClone;

package/dist/index.cjs16.js

@@ -0,0 +1,13 @@
+"use strict";
+function serializeValue(value) {
+  if (typeof value === "string")
+    return value;
+  if (typeof value === "number")
+    return value.toString();
+  if (typeof value === "boolean")
+    return value.toString();
+  if (value instanceof Date)
+    return value.toISOString();
+  return JSON.stringify(value);
+}
+module.exports = serializeValue;

package/dist/index.cjs17.js

@@ -0,0 +1,20 @@
+"use strict";
+function createSignal(dependency, initialValue, isEqual = Object.is) {
+  let value = initialValue;
+  const signal = {
+    get() {
+      if (dependency)
+        dependency.depend();
+      return value;
+    },
+    set(newValue) {
+      if (isEqual(value, newValue))
+        return;
+      value = newValue;
+      if (dependency)
+        dependency.notify();
+    }
+  };
+  return signal;
+}
+module.exports = createSignal;