@signaldb/core 2.0.0-beta.13 → 2.0.0-beta.14

package/dist/index7.mjs

@@ -1,33 +1,125 @@
-//#region src/utils/createSignal.ts
+//#region src/utils/EventEmitter.ts
 /**
-* 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.
+* A strongly‑typed EventEmitter.
 */
-function createSignal(reactivityAdapter, initialValue, isEqual = Object.is) {
-	let value = initialValue;
-	const dependency = reactivityAdapter?.create();
-	const isInReactiveScope = () => {
-		if (!reactivityAdapter?.isInScope) return true;
-		return reactivityAdapter.isInScope();
-	};
-	return {
-		get() {
-			if (dependency && isInReactiveScope()) dependency.depend();
-			return value;
-		},
-		set(newValue) {
-			if (isEqual(value, newValue)) return;
-			value = newValue;
-			if (dependency) dependency.notify();
+var EventEmitter = class {
+	_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;
+	}
+};
 //#endregion
-export { createSignal as default };
+export { EventEmitter as default };

package/dist/index8.cjs.js

@@ -1,12 +1,33 @@
-//#region src/utils/randomId.ts
+//#region src/utils/createSignal.ts
 /**
-* creates a random id
-* @returns a random string of 16 characters
-* @example
-* randomId() // '1234567890abcdef'
+* 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.
 */
-function randomId() {
-	return Array.from({ length: 16 }, () => "abcdefghijklmnopqrstuvwxyz0123456789"[Math.floor(Math.random() * 36)]).join("");
+function createSignal(reactivityAdapter, initialValue, isEqual = Object.is) {
+	let value = initialValue;
+	const dependency = reactivityAdapter?.create();
+	const isInReactiveScope = () => {
+		if (!reactivityAdapter?.isInScope) return true;
+		return reactivityAdapter.isInScope();
+	};
+	return {
+		get() {
+			if (dependency && isInReactiveScope()) dependency.depend();
+			return value;
+		},
+		set(newValue) {
+			if (isEqual(value, newValue)) return;
+			value = newValue;
+			if (dependency) dependency.notify();
+		}
+	};
 }
 //#endregion
-exports.default = randomId;
+exports.default = createSignal;

package/dist/index8.mjs

@@ -1,12 +1,33 @@
-//#region src/utils/randomId.ts
+//#region src/utils/createSignal.ts
 /**
-* creates a random id
-* @returns a random string of 16 characters
-* @example
-* randomId() // '1234567890abcdef'
+* 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.
 */
-function randomId() {
-	return Array.from({ length: 16 }, () => "abcdefghijklmnopqrstuvwxyz0123456789"[Math.floor(Math.random() * 36)]).join("");
+function createSignal(reactivityAdapter, initialValue, isEqual = Object.is) {
+	let value = initialValue;
+	const dependency = reactivityAdapter?.create();
+	const isInReactiveScope = () => {
+		if (!reactivityAdapter?.isInScope) return true;
+		return reactivityAdapter.isInScope();
+	};
+	return {
+		get() {
+			if (dependency && isInReactiveScope()) dependency.depend();
+			return value;
+		},
+		set(newValue) {
+			if (isEqual(value, newValue)) return;
+			value = newValue;
+			if (dependency) dependency.notify();
+		}
+	};
 }
 //#endregion
-export { randomId as default };
+export { createSignal as default };

package/dist/index9.cjs.js

@@ -1,11 +1,12 @@
-//#region src/createIndexProvider.ts
+//#region src/utils/randomId.ts
 /**
-* Creates an IndexProvider based on the given definition.
-* @param definition - The definition of the IndexProvider.
-* @returns The created IndexProvider.
+* creates a random id
+* @returns a random string of 16 characters
+* @example
+* randomId() // '1234567890abcdef'
 */
-function createIndexProvider(definition) {
-	return definition;
+function randomId() {
+	return Array.from({ length: 16 }, () => "abcdefghijklmnopqrstuvwxyz0123456789"[Math.floor(Math.random() * 36)]).join("");
 }
 //#endregion
-exports.default = createIndexProvider;
+exports.default = randomId;

package/dist/index9.mjs

@@ -1,11 +1,12 @@
-//#region src/createIndexProvider.ts
+//#region src/utils/randomId.ts
 /**
-* Creates an IndexProvider based on the given definition.
-* @param definition - The definition of the IndexProvider.
-* @returns The created IndexProvider.
+* creates a random id
+* @returns a random string of 16 characters
+* @example
+* randomId() // '1234567890abcdef'
 */
-function createIndexProvider(definition) {
-	return definition;
+function randomId() {
+	return Array.from({ length: 16 }, () => "abcdefghijklmnopqrstuvwxyz0123456789"[Math.floor(Math.random() * 36)]).join("");
 }
 //#endregion
-export { createIndexProvider as default };
+export { randomId as default };

package/dist/utils/incrementalQueryUpdate.d.ts

@@ -0,0 +1,60 @@
+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 `sort`: the previous items are projected, so the field the sort is keyed
+ *   on may no longer be there to sort by.
+ * - 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/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/package.json

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