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

package/dist/index6.cjs.js

@@ -1,125 +1,303 @@
-//#region src/utils/EventEmitter.ts
+const require_Observer = require("./index5.cjs.js");
+//#region src/Collection/Cursor.ts
 /**
-* A strongly‑typed EventEmitter.
+* Checks if the current scope is reactive, considering the provided reactivity adapter.
+* @param reactivity - The reactivity adapter or a boolean indicating whether reactivity is enabled.
+* @returns A boolean indicating if the current scope is reactive.
 */
-var EventEmitter = class {
-	_maxListeners = 100;
+function isInReactiveScope(reactivity) {
+	if (!reactivity) return false;
+	if (!reactivity.isInScope) return true;
+	return reactivity.isInScope();
+}
+/**
+* Represents a cursor for querying and observing a filtered, sorted, and transformed
+* subset of items from a collection. Supports reactivity and field tracking.
+* @template T - The type of the items in the collection.
+* @template U - The transformed item type after applying transform (default is T).
+*/
+var Cursor = class {
+	observer;
+	getItems;
+	options;
+	onCleanupCallbacks = [];
 	/**
-	* We store a set of the listeners for each event.
+	* Creates a new instance of the `Cursor` class.
+	* Provides utilities for querying, observing, and transforming items from a collection.
+	* @template T - The type of the items in the collection.
+	* @template U - The transformed item type after applying transformations (default is T).
+	* @param getItems - A function that retrieves the filtered list of items.
+	* @param options - Optional configuration for the cursor.
+	* @param options.transform - A transformation function to apply to each item when retrieving them.
+	* @param options.bindEvents - A function to bind reactivity events for the cursor, which should return a cleanup function.
+	* @param options.fields - A projection object defining which fields of the item should be included or excluded.
+	* @param options.sort - A sort specifier to determine the order of the items.
+	* @param options.skip - The number of items to skip from the beginning of the result set.
+	* @param options.limit - The maximum number of items to return in the result set.
+	* @param options.reactive - A reactivity adapter to enable observing changes in the cursor's result set.
+	* @param options.fieldTracking - A boolean to enable fine-grained field tracking for reactivity.
+	* @param options.transformAll - A function that will be able to solve the n+1 problem
 	*/
-	_listenerStore = /* @__PURE__ */ new Map();
-	setMaxListeners(max) {
-		this._maxListeners = max;
-		return this;
+	constructor(getItems, options) {
+		this.getItems = getItems;
+		this.options = options || {};
+	}
+	addGetters(item) {
+		if (!isInReactiveScope(this.options.reactive)) return item;
+		const depend = this.depend.bind(this);
+		return Object.entries(item).reduce((memo, [key, value]) => {
+			Object.defineProperty(memo, key, {
+				get() {
+					depend({ changedField: (notify) => (changedItem, changedFieldName) => {
+						if (changedFieldName !== key || changedItem.id !== item.id) return;
+						notify();
+					} });
+					return value;
+				},
+				enumerable: true,
+				configurable: true
+			});
+			return memo;
+		}, {});
+	}
+	transform(rawItem) {
+		const item = this.options.fieldTracking ? this.addGetters(rawItem) : rawItem;
+		if (!this.options.transform) return item;
+		return this.options.transform(item);
+	}
+	depend(changeEvents, bindExtraNotifier) {
+		if (this.options?.async) return;
+		if (!isInReactiveScope(this.options.reactive)) console.warn("Cursor.depend() called outside of a reactive scope without async option; consider using { async: true } or wrapping in a reactive scope");
+		if (!this.options.reactive) return;
+		const signal = this.options.reactive.create();
+		signal.depend();
+		const notify = () => signal.notify();
+		/**
+		* Builds a notifier function for the specified event.
+		* @template Event - The type of the event.
+		* @param event - The event for which to build the notifier.
+		* @returns A function that handles the event and triggers the appropriate notifications.
+		*/
+		function buildNotifier(event) {
+			const eventHandler = changeEvents[event];
+			return (...args) => {
+				if (eventHandler === true) {
+					notify();
+					return;
+				}
+				if (typeof eventHandler !== "function") return;
+				eventHandler(notify)(...args);
+			};
+		}
+		const stop = this.observeRawChanges({
+			added: buildNotifier("added"),
+			addedBefore: buildNotifier("addedBefore"),
+			changed: buildNotifier("changed"),
+			changedField: buildNotifier("changedField"),
+			movedBefore: buildNotifier("movedBefore"),
+			removed: buildNotifier("removed")
+		}, true);
+		if (this.options.reactive.onDispose) this.options.reactive.onDispose(() => stop(), signal);
+		this.onCleanup(stop);
+		if (!bindExtraNotifier) return;
+		const stopExtraNotifier = bindExtraNotifier(notify);
+		if (this.options.reactive.onDispose) this.options.reactive.onDispose(() => stopExtraNotifier(), signal);
+		this.onCleanup(stopExtraNotifier);
+	}
+	ensureObserver() {
+		if (!this.observer) {
+			const observer = new require_Observer.default(() => {
+				const requery = () => {
+					observer.runChecks(this.getItems);
+				};
+				const applyDelta = (delta) => {
+					observer.applyDelta(delta, this.getItems);
+				};
+				const cleanup = this.options.bindEvents && this.options.bindEvents(requery, applyDelta);
+				return () => {
+					if (cleanup) cleanup();
+				};
+			});
+			this.onCleanup(() => observer.stop());
+			this.observer = observer;
+		}
+		return this.observer;
+	}
+	observeRawChanges(callbacks, skipInitial = false) {
+		const observer = this.ensureObserver();
+		observer.addCallbacks(callbacks, skipInitial);
+		observer.runChecks(this.getItems);
+		return () => {
+			observer.removeCallbacks(callbacks);
+			if (!observer.isEmpty()) return;
+			observer.stop();
+			this.observer = void 0;
+		};
 	}
 	/**
-	* 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).
+	* Cleans up all resources associated with the cursor, such as reactive bindings
+	* and event listeners. This method should be called when the cursor is no longer needed
+	* to prevent memory leaks.
 	*/
-	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;
+	cleanup() {
+		this.onCleanupCallbacks.forEach((callback) => {
+			callback();
+		});
+		this.onCleanupCallbacks = [];
 	}
 	/**
-	* 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).
+	* Registers a cleanup callback to be executed when the `cleanup` method is called.
+	* Useful for managing resources and ensuring proper cleanup of bindings or listeners.
+	* @param callback - A function to be executed during cleanup.
 	*/
-	addListener(eventName, listener) {
-		return this.on(eventName, listener);
+	onCleanup(callback) {
+		this.onCleanupCallbacks.push(callback);
 	}
 	/**
-	* 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).
+	* Iterates over each item in the cursor's result set, applying the provided callback
+	* function to each transformed item.
+	* ⚡️ this function is reactive!
+	* @param callback - A function to execute for each item in the result set.
+	* @param callback.item - The transformed item.
+	* @returns A promise that resolves when all items have been processed, or void if not in async mode.
 	*/
-	once(eventName, listener) {
-		const onceWrapper = ((...args) => {
-			listener(...args);
-			this.off(eventName, onceWrapper);
+	forEach(callback) {
+		this.depend({
+			addedBefore: true,
+			removed: true,
+			movedBefore: true,
+			...this.options.fieldTracking ? {} : { changed: true }
 		});
-		return this.on(eventName, onceWrapper);
+		const executeForEach = (items) => {
+			items.forEach((item) => {
+				callback(this.transform(item));
+			});
+		};
+		const result = this.getItems();
+		if (result instanceof Promise) return result.then(executeForEach);
+		else {
+			executeForEach(result);
+			return;
+		}
 	}
 	/**
-	* 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).
+	* Creates a new array populated with the results of applying the provided callback
+	* function to each transformed item in the cursor's result set.
+	* ⚡️ this function is reactive!
+	* @template V - The type of the items in the resulting array.
+	* @param callback - A function to execute for each item in the result set.
+	* @param callback.item - The transformed item.
+	* @returns An array of results after applying the callback to each item.
 	*/
-	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;
+	map(callback) {
+		const results = [];
+		const maybePromise = this.forEach((item) => {
+			results.push(callback(item));
+		});
+		if (maybePromise instanceof Promise) return maybePromise.then(() => results);
+		return results;
 	}
 	/**
-	* 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).
+	* Fetches all transformed items from the cursor's result set as an array.
+	* Automatically applies filtering, sorting, and limiting as per the cursor's options.
+	* ⚡️ this function is reactive!
+	* @returns An array of transformed items in the result set.
 	*/
-	removeListener(eventName, listener) {
-		return this.off(eventName, listener);
+	fetch() {
+		return this.map((item) => item);
 	}
 	/**
-	* 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.
+	* Counts the total number of items in the cursor's result set after applying
+	* filtering and other criteria.
+	* ⚡️ this function is reactive!
+	* @returns The total number of items in the result set.
 	*/
-	emit(eventName, ...args) {
-		this.listeners(eventName).forEach((listener) => {
-			listener(...args);
+	count() {
+		this.depend({
+			added: true,
+			removed: true
 		});
+		const maybePromise = this.getItems();
+		return maybePromise instanceof Promise ? maybePromise.then((items) => items.length) : maybePromise.length;
 	}
 	/**
-	* 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.
+	* Whether this cursor's query has yet to deliver a first result.
+	* ⚡️ this function is reactive!
+	*
+	* An asynchronous data adapter answers a newly registered query only after a
+	* round trip, and serves a neutral empty result until it does — which a
+	* consumer cannot otherwise tell apart from "there is nothing to show". This
+	* is that distinction, per query rather than per collection, so one screen
+	* waiting on its own data says nothing about any other query.
+	*
+	* Follows the usual `isLoading`/`isFetching` split: it reports "no result
+	* yet", not "an execution is in flight". A write that re-runs an
+	* already-settled query drives it through `'active'` again while this stays
+	* `false`, so a list does not fall back to a loading state every time one of
+	* its rows changes.
+	*
+	* A query that fails counts as settled — the `query.error` event on the
+	* collection is what surfaces the failure, and a loading state that never
+	* ends is the worse answer. Reading this registers the query if nothing else
+	* has, so it cannot wait on something nobody asked for. It is always `false`
+	* for an `{ async: true }` cursor, whose `fetch()` awaits the real result
+	* anyway, and for a data adapter that answers synchronously.
+	* @returns A boolean indicating whether the first result is still pending.
 	*/
-	listeners(eventName) {
-		const listenersSet = this._listenerStore.get(eventName);
-		if (!listenersSet) return [];
-		return [...listenersSet.values()];
+	isLoading() {
+		const queryState = this.options.queryState;
+		if (!queryState || this.options.async) return false;
+		this.depend({}, (notify) => queryState.onSettled(notify));
+		return !queryState.hasSettled();
 	}
 	/**
-	* Returns the number of listeners for a given event.
-	* @param eventName The event name (key of E).
-	* @returns         The number of listeners.
+	* Observes changes to the cursor's result set and triggers the specified callbacks
+	* when items are added, removed, or updated. Supports reactivity and transformation.
+	* @param callbacks - An object containing the callback functions to handle different change events.
+	* @param callbacks.added - Triggered when an item is added to the result set.
+	* @param callbacks.removed - Triggered when an item is removed from the result set.
+	* @param callbacks.changed - Triggered when an item in the result set is modified.
+	* @param callbacks.addedBefore - Triggered when an item is added before another item in the result set.
+	* @param callbacks.movedBefore - Triggered when an item is moved before another item in the result set.
+	* @param callbacks.changedField - Triggered when a specific field of an item changes.
+	* @param skipInitial - A boolean indicating whether to skip the initial notification of the current result set.
+	* @returns A function to stop observing changes.
 	*/
-	listenerCount(eventName) {
-		const listenersSet = this._listenerStore.get(eventName);
-		return listenersSet ? listenersSet.size : 0;
+	observeChanges(callbacks, skipInitial = false) {
+		return this.observeRawChanges(Object.entries(callbacks).reduce((memo, [callbackName, callback]) => {
+			if (!callback) return memo;
+			return {
+				...memo,
+				[callbackName]: (item, before) => {
+					const transformedValue = this.transform(item);
+					const hasBeforeParameter = before !== void 0;
+					const transformedBeforeValue = hasBeforeParameter && before ? this.transform(before) : null;
+					return callback(transformedValue, ...hasBeforeParameter ? [transformedBeforeValue] : []);
+				}
+			};
+		}, {}), skipInitial);
 	}
 	/**
-	* 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).
+	* Forces the cursor to re-evaluate its result set by re-fetching items
+	* from the collection. This is useful when the underlying data or query
+	* criteria have changed, and you want to ensure the cursor reflects the latest state.
 	*/
-	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;
+	requery() {
+		if (!this.observer) return;
+		this.observer.runChecks(this.getItems);
+	}
+	/**
+	* Brings the cursor up to date from a description of what changed, rather than by re-running the
+	* query and comparing the result with the previous one.
+	*
+	* Falls back to `requery` when the delta does not fit the result the cursor currently holds, so
+	* a caller never has to decide which of the two is safe.
+	* @param delta - The change to apply.
+	*/
+	applyDelta(delta) {
+		if (!this.observer) return;
+		this.observer.applyDelta(delta, this.getItems);
 	}
 };
 //#endregion
-exports.default = EventEmitter;
+exports.default = Cursor;