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

package/dist/index5.mjs

@@ -1,6 +1,187 @@
-function createReactivityAdapter(definition) {
-  return definition;
-}
-export {
-  createReactivityAdapter as default
+import isEqual from "./index2.mjs";
+import uniqueBy from "./index3.mjs";
+import { applyQueryDelta, canApplyQueryDelta, diffQueryResults, isEmptyQueryDelta } from "./index4.mjs";
+//#region src/Collection/Observer.ts
+/**
+* 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.
+*/
+var Observer = class {
+	previousItems = [];
+	callbacks;
+	unbindEvents;
+	/**
+	* 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(bindEvents) {
+		this.callbacks = {
+			added: [],
+			addedBefore: [],
+			changed: [],
+			changedField: [],
+			movedBefore: [],
+			removed: []
+		};
+		this.unbindEvents = bindEvents();
+	}
+	call(event, ...args) {
+		this.callbacks[event].forEach(({ callback, options }) => {
+			if (!options.skipInitial || !options.isInitial) callback(...args);
+		});
+	}
+	hasCallbacks(events) {
+		return events.some((event) => this.callbacks[event].length > 0);
+	}
+	/**
+	* 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).
+	*/
+	isEmpty() {
+		return !this.hasCallbacks([
+			"added",
+			"addedBefore",
+			"changed",
+			"changedField",
+			"movedBefore",
+			"removed"
+		]);
+	}
+	/**
+	* 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.
+	*/
+	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);
+		});
+		else this.checkItems(result);
+	}
+	/**
+	* 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.
+	*/
+	applyDelta(delta, getItems) {
+		if (!canApplyQueryDelta(this.previousItems, delta)) {
+			this.runChecks(getItems);
+			return false;
+		}
+		if (isEmptyQueryDelta(delta)) return true;
+		this.emitDelta(delta, applyQueryDelta(this.previousItems, delta));
+		return true;
+	}
+	/**
+	* 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.
+	*/
+	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;
+			uniqueBy([...Object.keys(item), ...Object.keys(oldItem)], (value) => value).forEach((key) => {
+				if (isEqual(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));
+		});
+		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(diffQueryResults(this.previousItems, newItems), newItems);
+	}
+	stopped = false;
+	/**
+	* Stops the observer by unbinding all events and cleaning up resources.
+	* Safe to call multiple times - will only unbind once.
+	*/
+	stop() {
+		if (this.stopped) return;
+		this.stopped = true;
+		this.unbindEvents();
+	}
+	/**
+	* 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.
+	*/
+	addCallbacks(callbacks, skipInitial = false) {
+		Object.keys(callbacks).forEach((key) => {
+			const typedKey = key;
+			this.callbacks[typedKey].push({
+				callback: callbacks[typedKey],
+				options: {
+					skipInitial,
+					isInitial: true
+				}
+			});
+		});
+	}
+	/**
+	* 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.
+	*/
+	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
+export { Observer as default };

package/dist/index6.cjs.js

@@ -0,0 +1,303 @@
+const require_Observer = require("./index5.cjs.js");
+//#region src/Collection/Cursor.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.
+*/
+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 = [];
+	/**
+	* 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
+	*/
+	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;
+		};
+	}
+	/**
+	* 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();
+		});
+		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);
+	}
+	/**
+	* 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.
+	*/
+	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;
+		}
+	}
+	/**
+	* 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.
+	*/
+	map(callback) {
+		const results = [];
+		const maybePromise = this.forEach((item) => {
+			results.push(callback(item));
+		});
+		if (maybePromise instanceof Promise) return maybePromise.then(() => results);
+		return results;
+	}
+	/**
+	* 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.
+	*/
+	fetch() {
+		return this.map((item) => item);
+	}
+	/**
+	* 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.
+	*/
+	count() {
+		this.depend({
+			added: true,
+			removed: true
+		});
+		const maybePromise = this.getItems();
+		return maybePromise instanceof Promise ? maybePromise.then((items) => items.length) : maybePromise.length;
+	}
+	/**
+	* 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.
+	*/
+	isLoading() {
+		const queryState = this.options.queryState;
+		if (!queryState || this.options.async) return false;
+		this.depend({}, (notify) => queryState.onSettled(notify));
+		return !queryState.hasSettled();
+	}
+	/**
+	* 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.
+	*/
+	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);
+	}
+	/**
+	* 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.
+	*/
+	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 = Cursor;