@signaldb/core 2.0.0-beta.2 → 2.0.0-beta.21

package/dist/index9.mjs

@@ -1,134 +1,12 @@
-class EventEmitter {
-  _maxListeners = 100;
-  /**
-   * We store a set of the listeners for each event.
-   */
-  _listenerStore = /* @__PURE__ */ new Map();
-  setMaxListeners(max) {
-    this._maxListeners = max;
-    return 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(eventName, listener) {
-    let listenersSet = this._listenerStore.get(eventName);
-    if (!listenersSet) {
-      listenersSet = /* @__PURE__ */ new Set();
-      this._listenerStore.set(eventName, listenersSet);
-    }
-    listenersSet.add(listener);
-    if (listenersSet.size > this._maxListeners) {
-      console.warn(`Possible EventEmitter memory leak detected. ${listenersSet.size} ${String(eventName)} listeners added. Use emitter.setMaxListeners() to increase limit.`);
-    }
-    return 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(eventName, listener) {
-    return this.on(eventName, listener);
-  }
-  /**
-   * 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(eventName, listener) {
-    const onceWrapper = ((...args) => {
-      listener(...args);
-      this.off(eventName, onceWrapper);
-    });
-    return this.on(eventName, onceWrapper);
-  }
-  /**
-   * 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(eventName, listener) {
-    const listenersSet = this._listenerStore.get(eventName);
-    if (!listenersSet)
-      return this;
-    listenersSet.delete(listener);
-    if (listenersSet.size === 0) {
-      this._listenerStore.delete(eventName);
-    }
-    return 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(eventName, listener) {
-    return this.off(eventName, listener);
-  }
-  /**
-   * 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(eventName, ...args) {
-    this.listeners(eventName).forEach((listener) => {
-      listener(...args);
-    });
-  }
-  /**
-   * 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(eventName) {
-    const listenersSet = this._listenerStore.get(eventName);
-    if (!listenersSet)
-      return [];
-    return [...listenersSet.values()];
-  }
-  /**
-   * Returns the number of listeners for a given event.
-   * @param eventName The event name (key of E).
-   * @returns         The number of listeners.
-   */
-  listenerCount(eventName) {
-    const listenersSet = this._listenerStore.get(eventName);
-    return listenersSet ? listenersSet.size : 0;
-  }
-  /**
-   * 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(eventName) {
-    if (eventName === void 0) {
-      for (const [eventName_, listenersSet] of this._listenerStore.entries()) {
-        for (const listener of listenersSet.values()) {
-          this.off(eventName_, listener);
-        }
-      }
-      this._listenerStore.clear();
-    } else {
-      const listenersSet = this._listenerStore.get(eventName);
-      if (listenersSet) {
-        for (const listener of listenersSet.values()) {
-          this.off(eventName, listener);
-        }
-        this._listenerStore.delete(eventName);
-      }
-    }
-    return this;
-  }
+//#region src/utils/randomId.ts
+/**
+* creates a random id
+* @returns a random string of 16 characters
+* @example
+* randomId() // '1234567890abcdef'
+*/
+function randomId() {
+	return Array.from({ length: 16 }, () => "abcdefghijklmnopqrstuvwxyz0123456789"[Math.floor(Math.random() * 36)]).join("");
 }
-export {
-  EventEmitter as default
-};
+//#endregion
+export { randomId as default };

package/dist/types/IndexProvider.d.ts

@@ -1,5 +1,5 @@
-import type { BaseItem } from '../Collection';
-import type { FlatSelector } from './Selector';
+import { BaseItem } from '../Collection';
+import { FlatSelector } from './Selector';
 export type IndexResult<IdType> = {
     ids: IdType[];
     fields: string[];

package/dist/types/Modifier.d.ts

@@ -1,4 +1,4 @@
-import type { DotNotation, GetType } from './Selector';
+import { 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;

package/dist/types/ReactivityAdapter.d.ts

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

package/dist/types/StorageAdapter.d.ts

@@ -12,7 +12,15 @@ export default interface StorageAdapter<T extends {
     readIds(positions: I[]): Promise<T[]>;
     createIndex(field: string): Promise<void>;
     dropIndex(field: string): Promise<void>;
-    readIndex(field: string): Promise<Map<any, Set<I>>>;
+    /**
+     * The index, keyed by `serializeValue(value)` — not by the raw field value.
+     *
+     * SignalDB looks an index up with the serialized form, because that is what
+     * makes `3`, `'3'` and `new Date(...)` comparable as map keys at all. An
+     * adapter that stores its backend's own keys instead answers nothing for
+     * every non-string field, and everything for a `$ne` on one.
+     */
+    readIndex(field: string): Promise<Map<string | null, Set<I>>>;
     insert(items: T[]): Promise<void>;
     replace(items: T[]): Promise<void>;
     remove(items: T[]): Promise<void>;

package/dist/utils/applyQueryOptions.d.ts

@@ -0,0 +1,15 @@
+import { QueryOptions } from '../DataAdapter';
+import { default as Selector } from '../types/Selector';
+import { BaseItem } from '../Collection/types';
+/**
+ * Filters, sorts, paginates and projects a plain in-memory array the same way
+ * DefaultDataAdapter and WorkerDataAdapterHost apply a selector/QueryOptions
+ * pair to their stored items. Used to re-derive a query's result locally after
+ * a write, without asking the backing store again.
+ * @template T - The type of the items.
+ * @param items - The items to filter, sort, paginate and project.
+ * @param selector - The selector to match items against.
+ * @param options - Sort, skip, limit and field projection options.
+ * @returns The resulting items.
+ */
+export default function applyQueryOptions<T extends BaseItem>(items: T[], selector: Selector<T>, options?: QueryOptions<T>): T[];

package/dist/utils/createSignal.d.ts

@@ -1,5 +1,5 @@
-import type ReactivityAdapter from '../types/ReactivityAdapter';
-import type Signal from '../types/Signal';
+import { default as ReactivityAdapter } from '../types/ReactivityAdapter';
+import { default as 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,

package/dist/utils/getMatchingKeys.d.ts

@@ -1,5 +1,5 @@
-import type { BaseItem } from '../Collection/types';
-import type { FlatSelector } from '../types/Selector';
+import { BaseItem } from '../Collection/types';
+import { FlatSelector } from '../types/Selector';
 type KeyResult = {
     include: (string | null)[] | null;
     exclude: (string | null)[] | null;

package/dist/utils/idIndexQuery.d.ts

@@ -0,0 +1,20 @@
+import { BaseItem } from '../Collection/types';
+import { IndexResult } from '../types/IndexProvider';
+import { FlatSelector } from '../types/Selector';
+/**
+ * Resolves a selector on `id` into the ids it names, without consulting an index.
+ *
+ * `id` is the one field every storage adapter can look up directly — that is what
+ * `readIds` is — so a query on it never needs an index to be declared and never
+ * needs the whole collection to be read. This behaves like an index provider that
+ * happens to need no stored index, because the ids are already in the selector.
+ *
+ * Only inclusive forms can be answered this way. `$ne`/`$nin` describe everything
+ * except* something, which cannot be enumerated without knowing every id, so they
+ * report no match and take the ordinary path.
+ * @template T - The type of the items in the collection.
+ * @template I - The type of the unique identifier for the items.
+ * @param selector - The flat selector to resolve.
+ * @returns An index result naming the matched ids, or `{ matched: false }`.
+ */
+export default function idIndexQuery<T extends BaseItem<I> = BaseItem, I = any>(selector: FlatSelector<T>): IndexResult<I>;

package/dist/utils/incrementalQueryUpdate.d.ts

@@ -0,0 +1,62 @@
+import { QueryOptions } from '../DataAdapter';
+import { BaseItem } from '../Collection/types';
+import { default as Selector } from '../types/Selector';
+/**
+ * The items a write created, updated or removed, from the point of view of a store.
+ *
+ * `upserts` are the *current* state of every item that still exists; `deletes` are the ids of items
+ * that no longer do. A write that changes an item's id contributes to both. Callers are responsible
+ * for that split — an "affected items" list holding an item's state from before and after a write
+ * cannot be told apart from two unrelated items here.
+ */
+export interface QueryChangeset<T extends BaseItem> {
+    upserts: T[];
+    deletes: any[];
+}
+/**
+ * Recomputes a query's result from its previous result and the change that was just written,
+ * without going back to the store.
+ *
+ * A store re-executing the query instead reads every item it holds (or every item an index points
+ * at) and filters, sorts and projects the lot — for a write that touched one row. This does the
+ * same job in the size of the write, which is what a query's result costs to keep up to date when
+ * the change that affects it is already in hand.
+ *
+ * Returns `null` when the previous result is not enough to answer, and the caller has to re-execute
+ * the query after all:
+ * - `limit` or `skip`: the result is a window onto a larger set, and an item leaving the window has
+ *   to be replaced by one the previous result never contained.
+ * - `fields` together with a `sort` the projection does not keep: the previous items are
+ *   projected, so a sort key the projection dropped is no longer there to sort by. A projection
+ *   that keeps every sort key is fine, and is the common case — a list sorted by the same date it
+ *   displays.
+ * - a `null` selector, which matches nothing and is not worth a special case.
+ * @template T - The type of the items.
+ * @param previous - The query's previous result.
+ * @param selector - The query's selector.
+ * @param options - The query's options.
+ * @param changes - The items the write created, updated or removed.
+ * @returns The new result, or `null` when the query has to be re-executed.
+ */
+export default function incrementalQueryUpdate<T extends BaseItem>(previous: T[], selector: Selector<T>, options: QueryOptions<T> | undefined, changes: QueryChangeset<T>): T[] | null;
+/**
+ * Folds a change into a query's result, whatever the query's options.
+ *
+ * The unguarded version of `incrementalQueryUpdate`, for the places where the alternative is not a
+ * more accurate answer but a wrong one — layering a write that has not been confirmed yet on top of
+ * the last confirmed result, say. For a query returning everything it matches, this is exact. For a
+ * window onto a larger set it is the closest the window itself can get: an item that no longer
+ * belongs is dropped, one that does is placed, and the window is trimmed back to its length — but
+ * an item pulled in from beyond the window is not something the window knows about.
+ *
+ * What it never does is re-examine the items already in the result. They matched when the store
+ * produced them, they still match, and asking again is both wasteful and — for a projected result,
+ * whose items no longer carry the fields the selector names — wrong.
+ * @template T - The type of the items.
+ * @param previous - The query's previous result.
+ * @param selector - The query's selector.
+ * @param options - The query's options.
+ * @param changes - The items the write created, updated or removed.
+ * @returns The resulting items.
+ */
+export declare function mergeChangesetIntoResult<T extends BaseItem>(previous: T[], selector: Selector<T>, options: QueryOptions<T> | undefined, changes: QueryChangeset<T>): T[];

package/dist/utils/isFieldExpression.d.ts

@@ -1,4 +1,4 @@
-import type { FieldExpression } from '../types/Selector';
+import { 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.

package/dist/utils/match.d.ts

@@ -1,4 +1,4 @@
-import type Selector from '../types/Selector';
+import { default as Selector } from '../types/Selector';
 type BaseItem = Record<string, any>;
 /**
  * Tests whether a given item matches a specified selector.

package/dist/utils/modify.d.ts

@@ -1,4 +1,4 @@
-import type Modifier from '../types/Modifier';
+import { default as 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.

package/dist/utils/projectItems.d.ts

@@ -0,0 +1,12 @@
+import { QueryOptions } from '../DataAdapter';
+import { BaseItem } from '../Collection/types';
+/**
+ * Applies a query's field projection to a list of items, keeping the primary key unless the
+ * projection excludes it outright. Returns the items untouched when there is no projection, so a
+ * caller does not have to check for one first.
+ * @template T - The type of the items.
+ * @param items - The items to project.
+ * @param fields - The projection, or `undefined` for none.
+ * @returns The projected items.
+ */
+export default function projectItems<T extends BaseItem>(items: T[], fields: QueryOptions<T>['fields']): T[];

package/dist/utils/queryDelta.d.ts

@@ -0,0 +1,83 @@
+import { BaseItem } from '../Collection/types';
+/**
+ * The change between two consecutive results of the same query, expressed so it can be applied to
+ * the earlier result to obtain the later one.
+ *
+ * Indices in `added` and `moved` are positions in the *resulting* array and are always ascending,
+ * which is what makes applying them a matter of splicing in order. Removals and moves name items by
+ * id only: whoever applies the delta still holds the previous result and can look the item up
+ * there, so there is no reason to send it twice — the point of the whole exercise is that a change
+ * costs the size of the change, not the size of the result.
+ */
+export interface QueryDelta<T extends BaseItem = BaseItem> {
+    /** Items that were not in the previous result, at their position in the new one. */
+    added: {
+        index: number;
+        item: T;
+    }[];
+    /** Items that were in the previous result and whose contents changed. */
+    changed: T[];
+    /** Ids of items that are no longer in the result. */
+    removed: any[];
+    /** Items that stayed, at their new position, because the order around them changed. */
+    moved: {
+        index: number;
+        id: any;
+    }[];
+    /** Length of the resulting array — lets a recipient verify it applied the delta to the result it was computed against. */
+    resultCount: number;
+}
+/**
+ * Checks whether a delta leaves the result it is applied to unchanged.
+ * @param delta - The delta to inspect.
+ * @returns `true` when applying the delta would be a no-op.
+ */
+export declare function isEmptyQueryDelta(delta: QueryDelta<any>): boolean;
+/**
+ * Calls a state-change callback, passing the delta only when there is one.
+ *
+ * A callback invoked as `callback(state, undefined)` has been handed two arguments, which is a
+ * different thing from being handed one — visible to anything that inspects arity, and to any test
+ * that asserts on the call.
+ * @template T - The type of the items.
+ * @param callback - The callback to invoke.
+ * @param state - The state to report.
+ * @param delta - The delta to report, if there is one.
+ */
+export declare function callWithDelta<T extends BaseItem>(callback: (state: 'active' | 'complete' | 'error', delta?: QueryDelta<T>) => void, state: 'active' | 'complete' | 'error', delta?: QueryDelta<T>): void;
+/**
+ * Checks whether a delta describes a change to the given result.
+ *
+ * A delta is only meaningful against the exact result it was computed from — it names positions in
+ * an array and items by id alone. Applying one to anything else produces a result that looks
+ * plausible and is wrong, and from then on every further delta compounds the error. This is the
+ * cheap structural check that catches that: every id the delta expects to find is there, every id
+ * it expects to be new is not, and the arithmetic on the length works out. It costs the size of the
+ * delta, not the size of the result.
+ * @template T - The type of the items.
+ * @param previous - The result the delta would be applied to.
+ * @param delta - The delta to check.
+ * @returns `true` when the delta can be applied.
+ */
+export declare function canApplyQueryDelta<T extends BaseItem>(previous: T[], delta: QueryDelta<T>): boolean;
+/**
+ * Computes the delta between two results of the same query.
+ *
+ * A fallback for the cases where the change that produced the new result is not available — a query
+ * that had to be re-executed in full, for instance. It costs a pass over both results, but it is
+ * paid once, on the side that has both of them, instead of shipping the entire new result to
+ * everyone who only needs to know what changed.
+ * @template T - The type of the items.
+ * @param previous - The result the delta should be relative to.
+ * @param next - The result the delta should produce.
+ * @returns The delta between the two results.
+ */
+export declare function diffQueryResults<T extends BaseItem>(previous: T[], next: T[]): QueryDelta<T>;
+/**
+ * Applies a delta to the result it was computed against.
+ * @template T - The type of the items.
+ * @param previous - The result the delta is relative to. Not modified.
+ * @param delta - The delta to apply.
+ * @returns The resulting items.
+ */
+export declare function applyQueryDelta<T extends BaseItem>(previous: T[], delta: QueryDelta<T>): T[];

package/dist/utils/queryId.d.ts

@@ -1,5 +1,5 @@
-import type { QueryOptions } from '../DataAdapter';
-import type Selector from '../types/Selector';
+import { QueryOptions } from '../DataAdapter';
+import { default as Selector } from '../types/Selector';
 /**
  * Generates a unique identifier for a query based on its selector and options.
  * @param selector - The selector object.

package/dist/utils/reactiveOrAsync.d.ts

@@ -0,0 +1,59 @@
+export type MaybePromise<T> = T | Promise<T>;
+/**
+ * Options that control execution mode (and potential future mode-specific behavior).
+ * Keep this minimal; you can extend it later (e.g. signal, timeoutMs, debugLabel).
+ */
+export type ModeOptions = {
+    async?: boolean;
+};
+/**
+ * A generator helper that makes TypeScript infer the “synchronous value type” for maybe-async expressions.
+ *
+ * Usage:
+ *   const doc = yield* unwrap(Collection.findOne(...))
+ *   const list = yield* unwrap(Collection.find(...).fetch())
+ *
+ * Runtime note:
+ *   This does not “unwrap” Promises by itself. It yields the value/Promise to the runner and returns the
+ *   value that the runner feeds back via `.next(...)`.
+ * @param value The value (or Promise of a value) to yield to the runner.
+ * @returns A generator that yields `value` and resolves to the runner-supplied unwrapped `T`.
+ */
+export declare function unwrap<T>(value: MaybePromise<T>): Generator<MaybePromise<T>, T, T>;
+/**
+ * Generator shape used by the factory.
+ *
+ * `TThis` is the type of `this` inside the generator.
+ * `Args` are the method parameters (excluding the mode flag).
+ * `TReturn` is the final return value of the workflow.
+ * `TNext` is the type that is yielded/awaited and fed back via `.next(...)`.
+ *
+ * Note:
+ * - For best inference at yield sites, prefer `yield* unwrap(expr)` for maybe-async expressions.
+ */
+export type ReactiveOrAsyncGen<TThis, Arguments extends any[], TReturn, TNext> = (this: TThis, a: boolean, ...args: Arguments) => Generator<MaybePromise<TNext>, TReturn, TNext>;
+/**
+ * The method type produced from the generator signature.
+ * Adds overloads so that `{ async: true }` yields a `Promise<...>` return type.
+ */
+export type ReactiveOrAsyncMethod<TThis, P extends any[], R, N> = {
+    (this: TThis, ...args: P): R;
+    (this: TThis, ...args: [...P, ModeOptions?]): MaybePromise<R>;
+    (this: TThis, ...args: [...P, {
+        async: true;
+    }]): Promise<R>;
+} & {
+    /** Exposes the underlying generator for composition via `yield* method.generator.call(this, a, ...)` */
+    generator: (this: TThis, a: boolean, ...args: P) => Generator<MaybePromise<N>, R, N>;
+};
+/**
+ * Factory that turns a generator workflow into a callable method that can run in sync (reactive) or async mode.
+ *
+ * Call style:
+ *   fn(a, b)                        -> sync/reactive return
+ *   await fn(a, b, { async: true }) -> async return
+ * @param gen Generator workflow. Receives `(a)` which indicates async mode and should `yield`/`yield* unwrap(...)`
+ *   any values that may be Promises.
+ * @returns A callable method with overloads plus a `.generator` property for composition.
+ */
+export default function reactiveOrAsync<TThis, P extends any[], R, N>(gen: (this: TThis, a: boolean, ...args: P) => Generator<MaybePromise<N>, R, N>): ReactiveOrAsyncMethod<TThis, P, R, N>;

package/dist/utils/storageIndexQuery.d.ts

@@ -0,0 +1,20 @@
+import { BaseItem } from '../Collection/types';
+import { default as StorageAdapter } from '../types/StorageAdapter';
+import { AsynchronousQueryFunction } from '../types/IndexProvider';
+/**
+ * Builds the index provider a data adapter uses to narrow a selector down through
+ * a storage adapter's index.
+ *
+ * Every adapter that keeps its data in a `StorageAdapter` needs exactly this, and
+ * each of them used to carry its own copy — three transcriptions of one set of
+ * rules about null, `$exists`, inclusion and exclusion, which is how they drift
+ * apart without anyone noticing. The index is keyed by `serializeValue(value)`,
+ * which is what `getMatchingKeys` produces, so the two only agree while they stay
+ * in one place.
+ * @template T - The type of the items in the collection.
+ * @template I - The type of the unique identifier for the items.
+ * @param storage - The storage adapter holding the index.
+ * @param field - The indexed field this provider answers for.
+ * @returns A query function for `getIndexInfo`.
+ */
+export default function storageIndexQuery<T extends BaseItem<I>, I = any>(storage: Pick<StorageAdapter<T, I>, 'readIndex'>, field: string): AsynchronousQueryFunction<T, I>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaldb/core",
-  "version": "2.0.0-beta.2",
+  "version": "2.0.0-beta.21",
   "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",

package/dist/index.cjs10.js

@@ -1,18 +0,0 @@
-"use strict";
-function get(value, path) {
-  const normalized = path.replaceAll(/\[(\w+)\]/g, ".$1");
-  if (normalized.includes("..") || normalized.startsWith(".") || normalized.endsWith(".")) {
-    return;
-  }
-  const segments = normalized.split(".");
-  let current = value;
-  for (const key of segments) {
-    if (current == null)
-      return;
-    current = current[key];
-  }
-  if (current === void 0)
-    return;
-  return current;
-}
-module.exports = get;

package/dist/index.cjs11.js

@@ -1,15 +0,0 @@
-"use strict";
-function serializeValue(value) {
-  if (value == null)
-    return null;
-  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;