@signaldb/core 1.0.0

package/dist/index8.mjs

@@ -0,0 +1,6 @@
+function createReactivityAdapter(definition) {
+  return definition;
+}
+export {
+  createReactivityAdapter as default
+};

package/dist/index9.mjs

@@ -0,0 +1,31 @@
+function isEqual(a, b) {
+  if (Object.is(a, b))
+    return true;
+  if (a instanceof RegExp && b instanceof RegExp)
+    return a.toString() === b.toString();
+  if (a instanceof Date && b instanceof Date)
+    return a.getTime() === b.getTime();
+  if (typeof a !== "object")
+    return false;
+  if (typeof b !== "object")
+    return false;
+  if (a === null)
+    return false;
+  if (b === null)
+    return false;
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length)
+    return false;
+  for (let i = 0; i < aKeys.length; i += 1) {
+    const key = aKeys[i];
+    if (!bKeys.includes(key))
+      return false;
+    if (!isEqual(a[key], b[key]))
+      return false;
+  }
+  return true;
+}
+export {
+  isEqual as default
+};

package/dist/persistence/combinePersistenceAdapters.d.ts

@@ -0,0 +1,32 @@
+import type PersistenceAdapter from '../types/PersistenceAdapter';
+/**
+ * Creates a function that executes two asynchronous functions sequentially.
+ * The first function is tried first, and if it resolves, its value is used.
+ * If the first function fails or a fallback is required, the second function is executed.
+ * An optional cache mechanism can store the result temporarily to improve performance.
+ * @template Args - The argument types for the promise functions.
+ * @template ReturnVal - The return value type of the promise functions.
+ * @param firstResolvingPromiseFn - The primary promise-based function to execute.
+ * @param secondResolvingPromiseFn - The secondary fallback promise-based function to execute.
+ * @param [options] - Optional configuration.
+ * @param [options.onResolve] - Callback executed when a promise resolves.
+ * @param [options.cacheTimeout] - Time (in ms) to cache the resolved result.
+ * @returns A function that executes the two promises as described.
+ */
+export declare function createTemporaryFallbackExecutor<Args extends Array<any>, ReturnVal>(firstResolvingPromiseFn: (...args: Args) => Promise<ReturnVal>, secondResolvingPromiseFn: (...args: Args) => Promise<ReturnVal>, options?: {
+    onResolve?: (returnValue: ReturnVal) => void;
+    cacheTimeout?: number;
+}): (...args: Args) => Promise<ReturnVal>;
+/**
+ * Combines two persistence adapters (fast and slow) into a single interface.
+ * The fast adapter is used for quick read and write operations, while the slow adapter
+ * ensures data persistence and durability. The adapters sync automatically on read and save operations.
+ * @template T - The type of the persisted data items.
+ * @template I - The type of the identifier for persisted data items.
+ * @param slowAdapter - The slow persistence adapter for long-term storage.
+ * @param fastAdapter - The fast persistence adapter for quick access.
+ * @returns A combined persistence adapter that manages synchronization between the two adapters.
+ */
+export default function combinePersistenceAdapters<T extends {
+    id: I;
+} & Record<string, any>, I>(slowAdapter: PersistenceAdapter<T, I>, fastAdapter: PersistenceAdapter<T, I>): PersistenceAdapter<T, I>;

package/dist/persistence/createPersistenceAdapter.d.ts

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

package/dist/types/Dependency.d.ts

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

package/dist/types/EventEmitter.d.ts

@@ -0,0 +1,25 @@
+import { EventEmitter as BaseEventEmitter } from 'events';
+/**
+ * Extends the `EventEmitter` class from Node.js to provide a strongly-typed
+ * event emitter that enforces type safety for events and their corresponding listeners.
+ * @template Events - A record where keys represent event names (string or symbol),
+ *   and values represent the listener function types for those events.
+ */
+export default class EventEmitter<Events extends Record<string | symbol, any>> extends BaseEventEmitter {
+    /**
+     * 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<K extends keyof Events>(event: K, listener: Events[K]): 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<K extends keyof Events>(event: K, ...args: Parameters<Events[K]>): boolean;
+}

package/dist/types/IndexProvider.d.ts

@@ -0,0 +1,19 @@
+import type { BaseItem } from '../Collection';
+import type { FlatSelector } from './Selector';
+type IndexResult = {
+    positions: number[];
+    fields: string[];
+    matched: true;
+} | {
+    positions?: never;
+    fields?: never;
+    matched: false;
+};
+interface IndexProvider<T extends BaseItem<I> = BaseItem, I = any> {
+    query(selector: FlatSelector<T>): IndexResult;
+    rebuild(items: T[]): void;
+}
+export type LowLevelIndexProvider<T extends BaseItem<I> = BaseItem, I = any> = IndexProvider<T, I> & {
+    _index: Map<string, Set<number>>;
+};
+export default IndexProvider;

package/dist/types/MemoryAdapter.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Abstract class representing a memory adapter that implements methods
+ * from the JavaScript `Array` class for data manipulation.
+ * Designed to be extended and customized for specific use cases.
+ * @template T - The type of the items stored in the memory adapter (default is a record of key-value pairs).
+ */
+export default abstract class MemoryAdapter<T = Record<string, any>> {
+    abstract push(item: T): void;
+    abstract pop(): T | undefined;
+    abstract splice(start: number, deleteCount?: number, ...items: T[]): T[];
+    abstract map<U>(callbackfn: (value: T, index: number, array: T[]) => U): U[];
+    abstract find(predicate: (value: T, index: number, obj: T[]) => boolean): T | undefined;
+    abstract filter(predicate: (value: T, index: number, array: T[]) => unknown): T[];
+    abstract findIndex(predicate: (value: T, index: number, obj: T[]) => boolean): number;
+}

package/dist/types/Modifier.d.ts

@@ -0,0 +1,39 @@
+type Dictionary<T> = Record<string, T>;
+type PartialMapTo<T, M> = Partial<Record<keyof T, M>>;
+type OnlyElementsOfArrays<T> = T extends any[] ? Partial<T[0]> : never;
+type ElementsOf<T> = {
+    [P in keyof T]?: OnlyElementsOfArrays<T[P]>;
+};
+type PushModifier<T> = {
+    [P in keyof T]?: OnlyElementsOfArrays<T[P]> | {
+        $each?: T[P] | undefined;
+        $position?: number | undefined;
+        $slice?: number | undefined;
+        $sort?: 1 | -1 | Dictionary<number> | undefined;
+    };
+};
+type ArraysOrEach<T> = {
+    [P in keyof T]?: OnlyElementsOfArrays<T[P]> | {
+        $each: T[P];
+    };
+};
+type CurrentDateModifier = {
+    $type: 'timestamp' | 'date';
+} | true;
+type Modifier<T extends Dictionary<any> = Dictionary<any>> = {
+    $currentDate?: (Partial<Record<keyof 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?: (Partial<T> & Dictionary<any>) | undefined;
+    $setOnInsert?: (Partial<T> & 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?: (Partial<T> & Dictionary<any>) | undefined;
+    $pop?: (PartialMapTo<T, 1 | -1> & Dictionary<1 | -1>) | undefined;
+};
+export default Modifier;

package/dist/types/PersistenceAdapter.d.ts

@@ -0,0 +1,20 @@
+export interface Changeset<T> {
+    added: T[];
+    modified: T[];
+    removed: T[];
+}
+export type LoadResponse<T> = {
+    items: T[];
+    changes?: never;
+} | {
+    changes: Changeset<T>;
+    items?: never;
+};
+export default interface PersistenceAdapter<T extends {
+    id: I;
+} & Record<string, any>, I> {
+    load(): Promise<LoadResponse<T>>;
+    save(items: T[], changes: Changeset<T>): Promise<void>;
+    register(onChange: (data?: LoadResponse<T>) => void | Promise<void>): Promise<void>;
+    unregister?(): Promise<void>;
+}

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

@@ -0,0 +1,47 @@
+export interface FieldExpression<T> {
+    $eq?: T | undefined;
+    $gt?: T | undefined;
+    $gte?: T | undefined;
+    $lt?: T | undefined;
+    $lte?: T | undefined;
+    $in?: T[] | undefined;
+    $nin?: T[] | undefined;
+    $ne?: T | undefined;
+    $exists?: boolean | undefined;
+    $not?: FieldExpression<T> | undefined;
+    $expr?: FieldExpression<T> | undefined;
+    $jsonSchema?: any;
+    $mod?: number[] | undefined;
+    $regex?: RegExp | string | undefined;
+    $options?: string | undefined;
+    $text?: {
+        $search: string;
+        $language?: string | undefined;
+        $caseSensitive?: boolean | undefined;
+        $diacriticSensitive?: boolean | undefined;
+    } | undefined;
+    $where?: string | ((item: T) => boolean) | undefined;
+    $all?: T[] | undefined;
+    $elemMatch?: T extends object ? Query<T> : FieldExpression<T> | undefined;
+    $size?: number | undefined;
+    $bitsAllClear?: any;
+    $bitsAllSet?: any;
+    $bitsAnyClear?: any;
+    $bitsAnySet?: any;
+}
+type Flatten<T> = T extends any[] ? T[0] : T;
+type FlatQuery<T> = {
+    [P in keyof T]?: Flatten<T[P]> | RegExp | FieldExpression<Flatten<T[P]>>;
+} & Record<string, any>;
+type Query<T> = FlatQuery<T> & {
+    $or?: Query<T>[] | undefined;
+    $and?: Query<T>[] | undefined;
+    $nor?: Query<T>[] | undefined;
+};
+export type FlatSelector<T extends Record<string, any> = Record<string, any>> = FlatQuery<T> & {
+    $or?: never;
+    $and?: never;
+    $nor?: never;
+};
+type Selector<T extends Record<string, any> = Record<string, any>> = Query<T>;
+export default Selector;

package/dist/types/Signal.d.ts

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

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

@@ -0,0 +1,14 @@
+import type Dependency from '../types/Dependency';
+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 dependency - An optional dependency object for tracking and notifying reactivity.
+ * @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>(dependency: Dependency | undefined, initialValue: T, isEqual?: (a: T, b: T) => boolean): Signal<T>;

package/dist/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 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 obj - The object to deep clone.
+ * @returns A deep copy of the provided object.
+ */
+export default function deepClone<T>(obj: T): T;

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

@@ -0,0 +1,14 @@
+import type { BaseItem } from '../Collection/types';
+import type { FlatSelector } from '../types/Selector';
+/**
+ * Extracts the matching keys for a given field in a selector.
+ * Supports serialized values and `$in` field expressions for optimization.
+ * Returns `null` 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 array of serialized matching keys for the field, or `null` if the field
+ *   cannot be optimized (e.g., if it's a `RegExp` or non-optimizable field expression).
+ */
+export default function getMatchingKeys<T extends BaseItem<I> = BaseItem, I = any>(field: string, selector: FlatSelector<T>): string[] | null;

package/dist/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/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;

package/dist/utils/isFieldExpression.d.ts

@@ -0,0 +1,11 @@
+import type { FieldExpression } from '../types/Selector';
+/**
+ * Determines whether a given object is a valid field expression.
+ * A field expression is an object containing query operators supported by MongoDB-style queries.
+ * @template T - The type of the field expression.
+ * @param expression - The object to test.
+ * @returns A boolean indicating whether the object is a valid field expression.
+ *   - `true` if the object contains only recognized query operators.
+ *   - `false` otherwise.
+ */
+export default function isFieldExpression<T>(expression: any): expression is FieldExpression<T>;

package/dist/utils/match.d.ts

@@ -0,0 +1,12 @@
+import type Selector from '../types/Selector';
+type BaseItem = Record<string, any>;
+/**
+ * Tests whether a given item matches a specified selector.
+ * Uses the `mingo` library to evaluate the query.
+ * @template T - The type of the item being tested.
+ * @param item - The item to test against the selector.
+ * @param selector - The query selector used to match the item.
+ * @returns A boolean indicating whether the item matches the selector.
+ */
+export default function match<T extends BaseItem = BaseItem>(item: T, selector: Selector<T>): boolean;
+export {};

package/dist/utils/modify.d.ts

@@ -0,0 +1,14 @@
+import type Modifier from '../types/Modifier';
+/**
+ * Applies a modifier to an object and returns a new modified object.
+ * @template T - The type of the object to be modified.
+ * @param item - The object to be modified.
+ * @param modifier - The modifier to apply. This can be any transformation logic.
+ * @returns - Returns a new object with the modifications applied.
+ * @example
+ * const item = { a: 1, b: 2 }
+ * const modifier = { $set: { b: 3, c: 4 } }
+ * const result = modify(item, modifier)
+ * // result: { a: 1, b: 3, c: 4 }
+ */
+export default function modify<T extends Record<string, any>>(item: T, modifier: Modifier): T;

package/dist/utils/project.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Projects the fields of an object based on a specified fields configuration.
+ * Supports inclusion (`1`) and exclusion (`0`) of specific fields. Creates a new object
+ * with the desired fields included or excluded, based on the configuration.
+ * @template T - The type of the object being projected.
+ * @param item - The original object to project fields from.
+ * @param fields - An object defining the fields to include (`1`) or exclude (`0`).
+ *   - Keys are the field names, and values are either `1` (include) or `0` (exclude).
+ * @returns A new object with the specified fields included or excluded.
+ *   - If all fields are set to `0`, the excluded fields are removed from the result.
+ *   - If fields are set to `1`, only the included fields are retained.
+ */
+export default function project<T extends Record<string, any>>(item: T, fields: {
+    [P in keyof T]?: 0 | 1;
+} & Record<string, 0 | 1>): T;

package/dist/utils/randomId.d.ts

@@ -0,0 +1,7 @@
+/**
+ * creates a random id
+ * @returns a random string of 16 characters
+ * @example
+ * randomId() // '1234567890abcdef'
+ */
+export default function randomId(): string;

package/dist/utils/serializeValue.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Serializes a value into a string representation.
+ * Handles various types, including strings, numbers, booleans, dates, and objects.
+ * Falls back to JSON stringification for unsupported types.
+ * @param value - The value to serialize.
+ *   - Strings are returned as-is.
+ *   - Numbers and booleans are converted to their string representation.
+ *   - Dates are converted to ISO string format.
+ *   - Other values are stringified using `JSON.stringify`.
+ * @returns A string representation of the value.
+ */
+export default function serializeValue(value: any): string;

package/dist/utils/set.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Sets a value at a specified path within an object. Creates nested structures
+ * (arrays or objects) as needed to set the value at the correct location. Supports
+ * deleting the key if the value is `undefined` and the `deleteIfUndefined` flag is set to `true`.
+ * @template T - The type of the object to modify.
+ * @template K - The type of the value to set.
+ * @param obj - The object to modify. The object is mutated directly.
+ * @param path - The path (dot or bracket notation) where the value should be set.
+ * @param value - The value to set at the specified path.
+ * @param deleteIfUndefined - A boolean indicating whether to delete the key if the value is `undefined` (default: `false`).
+ * @returns The modified object.
+ */
+export default function set<T extends object, K>(obj: T, path: string, value: K, deleteIfUndefined?: boolean): T;

package/dist/utils/sortItems.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Sorts an array of items based on multiple fields and their specified sort order.
+ * Uses the `fast-sort` library for efficient sorting.
+ * @template T - The type of the items in the array.
+ * @param items - The array of items to be sorted.
+ * @param sortFields - An object defining the sort order for each field.
+ *   - Keys are the field names, and values are either `1` (ascending) or `-1` (descending).
+ * @returns A new array of items sorted based on the specified fields and their order.
+ */
+export default function sortItems<T extends Record<string, any>>(items: T[], sortFields: {
+    [P in keyof T]?: -1 | 1;
+} & Record<string, -1 | 1>): T[];

package/dist/utils/uniqueBy.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Filters an array to ensure unique values based on a specified key or transformation function.
+ * @template T - The type of the elements in the array.
+ * @param arr - The array to filter for unique values.
+ * @param fn - A key or transformation function to determine uniqueness.
+ *   - If a key is provided, it will use the corresponding property of each element for uniqueness.
+ *   - If a function is provided, it will use the return value of the function applied to each element for uniqueness.
+ * @returns A new array containing only unique elements based on the specified key or transformation.
+ */
+export default function uniqueBy<T>(arr: T[], fn: keyof T | ((item: T) => any)): T[];

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@signaldb/core",
+  "version": "1.0.0",
+  "description": "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 interface to places such as localStorage.",
+  "scripts": {
+    "build": "rimraf dist && vite build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maxnowack/signaldb.git"
+  },
+  "homepage": "https://signaldb.js.org",
+  "keywords": [
+    "client-database",
+    "client",
+    "database",
+    "local-database",
+    "meteor",
+    "minimongo",
+    "mongodb",
+    "offline-first",
+    "optimistic-ui",
+    "reactive",
+    "replication",
+    "synchronization",
+    "tracker",
+    "typescript"
+  ],
+  "author": "Max Nowack <max.nowack@gmail.com>",
+  "license": "MIT",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs.js",
+      "default": "./dist/index.cjs.js"
+    }
+  },
+  "main": "./dist/index.cjs.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./dist/*",
+        "./dist/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "fast-sort": "^3.4.1",
+    "mingo": "^6.5.1"
+  }
+}