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

package/dist/index5.cjs.js

@@ -1,288 +1,187 @@
-const require_Observer = require("./index4.cjs.js");
-//#region src/Collection/Cursor.ts
+const require_isEqual = require("./index2.cjs.js");
+const require_uniqueBy = require("./index3.cjs.js");
+const require_queryDelta = require("./index4.cjs.js");
+//#region src/Collection/Observer.ts
 /**
-* 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.
+* Represents an observer that tracks changes in a collection of items and triggers
+* callbacks for various events such as addition, removal, and modification of items.
+* @template T - The type of the items being observed, which must include an `id` field.
 */
-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 = [];
+var Observer = class {
+	previousItems = [];
+	callbacks;
+	unbindEvents;
 	/**
-	* 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
+	* Creates a new instance of the `Observer` class.
+	* Sets up event bindings and initializes the callbacks for tracking changes in a collection.
+	* @param bindEvents - A function to bind external events to the observer. Must return a cleanup function to unbind those events.
 	*/
-	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 cleanup = this.options.bindEvents && this.options.bindEvents(requery);
-				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;
+	constructor(bindEvents) {
+		this.callbacks = {
+			added: [],
+			addedBefore: [],
+			changed: [],
+			changedField: [],
+			movedBefore: [],
+			removed: []
 		};
+		this.unbindEvents = bindEvents();
 	}
-	/**
-	* 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.
-	*/
-	cleanup() {
-		this.onCleanupCallbacks.forEach((callback) => {
-			callback();
+	call(event, ...args) {
+		this.callbacks[event].forEach(({ callback, options }) => {
+			if (!options.skipInitial || !options.isInitial) callback(...args);
 		});
-		this.onCleanupCallbacks = [];
 	}
-	/**
-	* 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.
-	*/
-	onCleanup(callback) {
-		this.onCleanupCallbacks.push(callback);
+	hasCallbacks(events) {
+		return events.some((event) => this.callbacks[event].length > 0);
 	}
 	/**
-	* 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.
+	* Determines if the observer has no active callbacks registered for any events.
+	* @returns A boolean indicating whether the observer is empty (i.e., no callbacks are registered).
 	*/
-	forEach(callback) {
-		this.depend({
-			addedBefore: true,
-			removed: true,
-			movedBefore: true,
-			...this.options.fieldTracking ? {} : { changed: true }
-		});
-		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;
-		}
+	isEmpty() {
+		return !this.hasCallbacks([
+			"added",
+			"addedBefore",
+			"changed",
+			"changedField",
+			"movedBefore",
+			"removed"
+		]);
 	}
 	/**
-	* 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.
+	* Compares the previous state of items with the new state and triggers the appropriate callbacks
+	* for events such as added, removed, changed, or moved items.
+	* @param getItems - A function that returns a promise resolving to the new items or the items themselves.
 	*/
-	map(callback) {
-		const results = [];
-		const maybePromise = this.forEach((item) => {
-			results.push(callback(item));
+	runChecks(getItems) {
+		const result = getItems();
+		if (result instanceof Promise) result.then((newItems) => this.checkItems(newItems)).catch((error) => {
+			console.error("Error while asynchronously querying items", error);
 		});
-		if (maybePromise instanceof Promise) return maybePromise.then(() => results);
-		return results;
+		else this.checkItems(result);
 	}
 	/**
-	* 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.
+	* Brings the observer up to date from a description of what changed, instead of from the new
+	* result.
+	*
+	* `runChecks` has to rediscover the change by comparing the whole new result against the whole
+	* old one — a cost proportional to the result, paid on every write, to find out that one row
+	* moved. When the change is already known it can simply be reported, and the cost becomes
+	* proportional to the change.
+	*
+	* The delta must have been computed against exactly the result this observer holds. If it was
+	* not, this reports nothing, falls back to `runChecks`, and returns `false`.
+	*
+	* Note that the reported moves are minimal, where a comparison reports every item whose
+	* neighbour changed. Applying them yields the same order either way — there are simply fewer of
+	* them.
+	* @param delta - The change to report.
+	* @param getItems - Used to fall back to a comparison when the delta cannot be applied.
+	* @returns Whether the delta was applied.
 	*/
-	fetch() {
-		return this.map((item) => item);
+	applyDelta(delta, getItems) {
+		if (!require_queryDelta.canApplyQueryDelta(this.previousItems, delta)) {
+			this.runChecks(getItems);
+			return false;
+		}
+		if (require_queryDelta.isEmptyQueryDelta(delta)) return true;
+		this.emitDelta(delta, require_queryDelta.applyQueryDelta(this.previousItems, delta));
+		return true;
 	}
 	/**
-	* 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.
+	* Reports a delta and adopts the result it produces.
+	*
+	* The single place the callbacks are fired from, whether the change arrived as a delta or was
+	* found by comparing two results — so the two can never disagree about what a consumer is told.
+	* @param delta - The change to report.
+	* @param nextItems - The result the delta produces.
 	*/
-	count() {
-		this.depend({
-			added: true,
-			removed: true
+	emitDelta(delta, nextItems) {
+		if (this.isEmpty()) {
+			this.finishCheck(nextItems);
+			return;
+		}
+		const beforeOf = (index) => nextItems[index + 1] || null;
+		const previousById = delta.removed.length > 0 && this.hasCallbacks(["removed"]) || delta.changed.length > 0 && this.hasCallbacks(["changedField"]) ? new Map(this.previousItems.map((item) => [item.id, item])) : null;
+		if (this.hasCallbacks(["changed", "changedField"])) delta.changed.forEach((item) => {
+			this.call("changed", item);
+			if (!this.hasCallbacks(["changedField"])) return;
+			const oldItem = previousById?.get(item.id);
+			if (!oldItem) return;
+			require_uniqueBy.default([...Object.keys(item), ...Object.keys(oldItem)], (value) => value).forEach((key) => {
+				if (require_isEqual.default(item[key], oldItem[key])) return;
+				this.call("changedField", item, key, oldItem[key], item[key]);
+			});
+		});
+		if (this.hasCallbacks(["removed"])) delta.removed.forEach((id) => {
+			const oldItem = previousById?.get(id);
+			if (oldItem) this.call("removed", oldItem);
+		});
+		if (this.hasCallbacks(["added", "addedBefore"])) delta.added.forEach(({ index, item }) => {
+			this.call("added", item);
+			this.call("addedBefore", item, beforeOf(index));
+		});
+		if (this.hasCallbacks(["movedBefore"])) delta.moved.forEach(({ index }) => {
+			this.call("movedBefore", nextItems[index], beforeOf(index));
 		});
-		const maybePromise = this.getItems();
-		return maybePromise instanceof Promise ? maybePromise.then((items) => items.length) : maybePromise.length;
+		this.finishCheck(nextItems);
 	}
+	finishCheck(newItems) {
+		this.previousItems = newItems;
+		Object.keys(this.callbacks).forEach((key) => {
+			const event = key;
+			const callbacks = this.callbacks[event];
+			this.callbacks[event] = callbacks.map((callback) => ({
+				...callback,
+				options: {
+					...callback.options,
+					isInitial: false
+				}
+			}));
+		});
+	}
+	checkItems(newItems) {
+		this.emitDelta(require_queryDelta.diffQueryResults(this.previousItems, newItems), newItems);
+	}
+	stopped = false;
 	/**
-	* 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.
+	* Stops the observer by unbinding all events and cleaning up resources.
+	* Safe to call multiple times - will only unbind once.
 	*/
-	isLoading() {
-		const queryState = this.options.queryState;
-		if (!queryState || this.options.async) return false;
-		this.depend({}, (notify) => queryState.onSettled(notify));
-		return !queryState.hasSettled();
+	stop() {
+		if (this.stopped) return;
+		this.stopped = true;
+		this.unbindEvents();
 	}
 	/**
-	* 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.
+	* Registers callbacks for specific events to observe changes in the collection.
+	* @param callbacks - An object containing the callbacks for various events (e.g., 'added', 'removed').
+	* @param skipInitial - A boolean indicating whether to skip invoking the callbacks for the initial state of the collection.
 	*/
-	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] : []);
+	addCallbacks(callbacks, skipInitial = false) {
+		Object.keys(callbacks).forEach((key) => {
+			const typedKey = key;
+			this.callbacks[typedKey].push({
+				callback: callbacks[typedKey],
+				options: {
+					skipInitial,
+					isInitial: true
 				}
-			};
-		}, {}), skipInitial);
+			});
+		});
 	}
 	/**
-	* 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.
+	* Removes the specified callbacks for specific events, unregistering them from the observer.
+	* @param callbacks - An object containing the callbacks to be removed for various events.
 	*/
-	requery() {
-		if (!this.observer) return;
-		this.observer.runChecks(this.getItems);
+	removeCallbacks(callbacks) {
+		Object.keys(callbacks).forEach((key) => {
+			const typedKey = key;
+			const index = this.callbacks[typedKey].findIndex(({ callback }) => callback === callbacks[typedKey]);
+			this.callbacks[typedKey].splice(index, 1);
+		});
 	}
 };
 //#endregion
-exports.default = Cursor;
+exports.default = Observer;