@signaldb/core 2.0.0-beta.5 → 2.0.0-beta.7

package/dist/index4.mjs

@@ -1,6 +1,150 @@
-function createStorageAdapter(definition) {
-  return definition;
-}
-export {
-  createStorageAdapter as default
+import isEqual from "./index2.mjs";
+import uniqueBy from "./index3.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);
+	}
+	checkItems(newItems) {
+		const oldItemsMap = new Map(this.previousItems.map((item, index) => [item.id, {
+			item,
+			index,
+			beforeItem: this.previousItems[index + 1] || null
+		}]));
+		const newItemsMap = new Map(newItems.map((item, index) => [item.id, {
+			item,
+			index,
+			beforeItem: newItems[index + 1] || null
+		}]));
+		if (this.hasCallbacks([
+			"changed",
+			"changedField",
+			"movedBefore",
+			"removed"
+		])) oldItemsMap.forEach(({ item: oldItem, index, beforeItem: oldBeforeItem }) => {
+			const newItem = newItemsMap.get(oldItem.id);
+			if (newItem) {
+				if (this.hasCallbacks(["changed", "changedField"]) && !isEqual(newItem.item, oldItem)) {
+					this.call("changed", newItem.item);
+					if (this.hasCallbacks(["changedField"])) uniqueBy([...Object.keys(newItem.item), ...Object.keys(oldItem)], (value) => value).forEach((key) => {
+						if (isEqual(newItem.item[key], oldItem[key])) return;
+						this.call("changedField", newItem.item, key, oldItem[key], newItem.item[key]);
+					});
+				}
+				if (newItem.index !== index && newItem.beforeItem?.id !== oldBeforeItem?.id) this.call("movedBefore", newItem.item, newItem.beforeItem);
+			} else this.call("removed", oldItem);
+		});
+		if (this.hasCallbacks(["added", "addedBefore"])) newItems.forEach((newItem, index) => {
+			if (oldItemsMap.get(newItem.id)) return;
+			this.call("added", newItem);
+			this.call("addedBefore", newItem, newItems[index + 1] || null);
+		});
+		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
+				}
+			}));
+		});
+	}
+	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/index5.cjs.js

@@ -0,0 +1,254 @@
+const require_Observer = require("./index4.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) {
+		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);
+	}
+	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;
+		};
+	}
+	/**
+	* 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;
+	}
+	/**
+	* 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);
+	}
+};
+//#endregion
+exports.default = Cursor;

package/dist/index5.mjs

@@ -1,6 +1,254 @@
-function createReactivityAdapter(definition) {
-  return definition;
+import Observer from "./index4.mjs";
+//#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();
 }
-export {
-  createReactivityAdapter as default
+/**
+* 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) {
+		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);
+	}
+	ensureObserver() {
+		if (!this.observer) {
+			const observer = new Observer(() => {
+				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;
+		};
+	}
+	/**
+	* 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;
+	}
+	/**
+	* 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);
+	}
 };
+//#endregion
+export { Cursor as default };