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

package/dist/index28.mjs

@@ -1,89 +1,557 @@
-//#region src/utils/reactiveOrAsync.ts
+import Cursor from "./index6.mjs";
+import EventEmitter from "./index7.mjs";
+import createSignal from "./index8.mjs";
+import randomId from "./index9.mjs";
+import "./index15.mjs";
+import deepClone from "./index18.mjs";
+import modify from "./index20.mjs";
+import queryId from "./index26.mjs";
+import DefaultDataAdapter from "./index27.mjs";
+//#region src/Collection/index.ts
 /**
-* A generator helper that makes TypeScript infer the “synchronous value type” for maybe-async expressions.
-*
-* Usage:
-*   const doc = yield* unwrap(Collection.findOne(...))
-*   const list = yield* unwrap(Collection.find(...).fetch())
-*
-* Runtime note:
-*   This does not “unwrap” Promises by itself. It yields the value/Promise to the runner and returns the
-*   value that the runner feeds back via `.next(...)`.
-* @param value The value (or Promise of a value) to yield to the runner.
-* @returns A generator that yields `value` and resolves to the runner-supplied unwrapped `T`.
+* Represents a collection of data items with support for in-memory operations,
+* persistence, reactivity, and event-based notifications. The collection provides
+* CRUD operations, observer patterns, and batch operations.
+* @template T - The type of the items stored in the collection.
+* @template I - The type of the unique identifier for the items.
+* @template U - The transformed item type after applying transformations (default is T).
 */
-function unwrap(value) {
-	return (function* () {
-		return yield value;
-	})();
-}
-/**
-* Internal: checks for thenables (Promise-like).
-* @param value The value to test.
-* @returns `true` if `value` looks like a Promise/thenable.
-*/
-function isThenable(value) {
-	return typeof value === "object" && value !== null && typeof value.then === "function";
-}
-/**
-* Internal runner: executes a generator either synchronously (reactive) or asynchronously (imperative).
-*
-* - In sync mode, yielding a Promise is a programming error and throws.
-* - In async mode, yielded Promises are awaited.
-* @param thisArgument The `this` value to bind when invoking `gen`.
-* @param mode Execution mode options.
-* @param gen The generator workflow to run.
-* @returns The workflow result (a plain value in sync mode, or a Promise in async mode).
-*/
-function runReactiveOrAsync(thisArgument, mode, gen) {
-	const a = !!mode?.async;
-	const it = gen.call(thisArgument, a);
-	if (!a) {
-		let step = it.next();
-		while (!step.done) {
-			const y = step.value;
-			if (isThenable(y)) throw new Error("Promise yielded in sync flow");
-			step = it.next(y);
+var Collection = class Collection extends EventEmitter {
+	static collections = [];
+	static debugMode = false;
+	static batchOperationInProgress = false;
+	static fieldTracking = false;
+	static onCreationCallbacks = [];
+	static onDisposeCallbacks = [];
+	static getCollections() {
+		return Collection.collections;
+	}
+	static onCreation(callback) {
+		Collection.onCreationCallbacks.push(callback);
+	}
+	static onDispose(callback) {
+		Collection.onDisposeCallbacks.push(callback);
+	}
+	/**
+	* Enables debug mode for all collections.
+	*/
+	static enableDebugMode = () => {
+		Collection.debugMode = true;
+		Collection.collections.forEach((collection) => {
+			collection.setDebugMode(true);
+		});
+	};
+	/**
+	* Enables field tracking for all collections.
+	* @param enable - A boolean indicating whether to enable field tracking.
+	*/
+	static setFieldTracking = (enable) => {
+		Collection.fieldTracking = enable;
+		Collection.collections.forEach((collection) => {
+			collection.setFieldTracking(enable);
+		});
+	};
+	static batch(callback) {
+		Collection.batchOperationInProgress = true;
+		const execute = () => Collection.collections.reduce((memo, collection) => () => {
+			return collection.batch(memo);
+		}, callback)();
+		const afterBatch = () => {
+			Collection.batchOperationInProgress = false;
+		};
+		let maybePromise;
+		try {
+			maybePromise = execute();
+		} catch (error) {
+			afterBatch();
+			throw error;
 		}
-		return step.value;
-	}
-	return (async function() {
-		let step = it.next();
-		while (!step.done) {
-			const y = step.value;
-			const v = isThenable(y) ? await y : y;
-			step = it.next(v);
+		if (maybePromise && typeof maybePromise.then === "function") return maybePromise.then(() => afterBatch(), (error) => {
+			afterBatch();
+			throw error;
+		});
+		else afterBatch();
+	}
+	name;
+	backend;
+	options;
+	isPullingSignal;
+	isPushingSignal;
+	readySignal;
+	debugMode;
+	batchOperationInProgress = false;
+	isDisposed = false;
+	postBatchCallbacks = /* @__PURE__ */ new Set();
+	fieldTracking = false;
+	queryListenersMap = /* @__PURE__ */ new Map();
+	settledQueriesSet = /* @__PURE__ */ new Set();
+	constructor(nameOrOptions, maybeDataAdapter, maybeOptions) {
+		super();
+		const name = typeof nameOrOptions === "string" ? nameOrOptions : nameOrOptions?.name || `${this.constructor.name}-${randomId()}`;
+		const options = typeof nameOrOptions === "string" ? maybeOptions || {} : nameOrOptions || {};
+		const persistence = options.persistence;
+		const dataAdapter = maybeDataAdapter || new DefaultDataAdapter({ ...persistence ? { storage: () => persistence } : {} });
+		Collection.collections.push(this);
+		this.name = name;
+		this.options = { ...options };
+		this.fieldTracking = this.options.fieldTracking ?? Collection.fieldTracking;
+		this.debugMode = this.options.enableDebugMode ?? Collection.debugMode;
+		this.isPullingSignal = createSignal(this.options.reactivity, false);
+		this.isPushingSignal = createSignal(this.options.reactivity, false);
+		this.readySignal = createSignal(this.options.reactivity, false);
+		this.backend = dataAdapter.createCollectionBackend(this, this.options.indices ?? []);
+		this.backend.isReady().then(() => {
+			this.readySignal.set(true);
+		}).catch(() => {});
+		Collection.onCreationCallbacks.forEach((callback) => callback(this));
+	}
+	isBatchOperationInProgress() {
+		return Collection.batchOperationInProgress || this.batchOperationInProgress;
+	}
+	/**
+	* Checks whether the collection is currently performing a pull operation
+	* ⚡️ this function is reactive!
+	* (loading data from the persistence adapter).
+	* @returns A boolean indicating if the collection is in the process of pulling data.
+	*/
+	isPulling() {
+		return this.isPullingSignal.get() ?? false;
+	}
+	/**
+	* Checks whether the collection is currently performing a push operation
+	* ⚡️ this function is reactive!
+	* (saving data to the persistence adapter).
+	* @returns A boolean indicating if the collection is in the process of pushing data.
+	*/
+	isPushing() {
+		return this.isPushingSignal.get() ?? false;
+	}
+	/**
+	* Checks whether the collection is currently performing either a pull or push operation,
+	* ⚡️ this function is reactive!
+	* indicating that it is loading or saving data.
+	* @returns A boolean indicating if the collection is in the process of loading or saving data.
+	*/
+	isLoading() {
+		const isPulling = this.isPulling();
+		const isPushing = this.isPushing();
+		return isPulling || isPushing;
+	}
+	/**
+	* Retrieves the current debug mode status of the collection.
+	* @returns A boolean indicating whether debug mode is enabled for the collection.
+	*/
+	getDebugMode() {
+		return this.debugMode;
+	}
+	/**
+	* Enables or disables debug mode for the collection.
+	* When debug mode is enabled, additional debugging information and events are emitted.
+	* @param enable - A boolean indicating whether to enable (`true`) or disable (`false`) debug mode.
+	*/
+	setDebugMode(enable) {
+		this.debugMode = enable;
+	}
+	/**
+	* Enables or disables field tracking for the collection.
+	* @param enable - A boolean indicating whether to enable (`true`) or disable (`false`) field tracking.
+	*/
+	setFieldTracking(enable) {
+		this.fieldTracking = enable;
+	}
+	/**
+	* Resolves when the persistence adapter finished initializing
+	* and the collection is ready to be used.
+	* @returns A promise that resolves when the collection is ready.
+	* @example
+	* ```ts
+	* const collection = new Collection({
+	*   persistence: // ...
+	* })
+	* await collection.isReady()
+	*
+	* collection.insert({ name: 'Item 1' })
+	*/
+	async ready() {
+		return this.backend.isReady();
+	}
+	/**
+	* Checks if the collection is ready.
+	* ⚡️ this function is reactive!
+	* @returns A boolean indicating whether the collection is ready.
+	*/
+	isReady() {
+		return this.readySignal.get() ?? false;
+	}
+	profile(fn, measureFunction) {
+		if (!this.debugMode) return fn();
+		const startTime = performance.now();
+		const handleProfileEnd = (result) => {
+			measureFunction(performance.now() - startTime);
+			return result;
+		};
+		const maybePromise = fn();
+		return maybePromise instanceof Promise ? maybePromise.then(handleProfileEnd) : handleProfileEnd(maybePromise);
+	}
+	executeInDebugMode(fn) {
+		if (!this.debugMode) return;
+		fn((/* @__PURE__ */ new Error()).stack || "");
+	}
+	transform(item) {
+		if (!this.options.transform) return item;
+		return this.options.transform(item);
+	}
+	transformAll(items, fields) {
+		if (!this.options.transformAll) return items;
+		return this.options.transformAll(deepClone(items), fields);
+	}
+	getItem(selector, options) {
+		const itemsOrPromise = this.getItems(selector, {
+			...options,
+			limit: 1
+		});
+		if (itemsOrPromise instanceof Promise) return itemsOrPromise.then((items) => {
+			return items[0] || void 0;
+		});
+		return itemsOrPromise[0];
+	}
+	getItems(selector, options) {
+		this.emit("getItems", selector);
+		return this.profile(() => {
+			if (!options?.async) return this.backend.getQueryResult(selector, options);
+			this.isPullingSignal.set(true);
+			return this.backend.executeQuery(selector, options).finally(() => {
+				this.isPullingSignal.set(false);
+			});
+		}, (measuredTime) => this.executeInDebugMode((callstack) => this.emit("_debug.getItems", callstack, selector, measuredTime)));
+	}
+	async withPushState(asyncFunction) {
+		this.isPushingSignal.set(true);
+		try {
+			return await asyncFunction();
+		} finally {
+			this.isPushingSignal.set(false);
 		}
-		return step.value;
-	})();
-}
-/**
-* Factory that turns a generator workflow into a callable method that can run in sync (reactive) or async mode.
-*
-* Call style:
-*   fn(a, b)                        -> sync/reactive return
-*   await fn(a, b, { async: true }) -> async return
-* @param gen Generator workflow. Receives `(a)` which indicates async mode and should `yield`/`yield* unwrap(...)`
-*   any values that may be Promises.
-* @returns A callable method with overloads plus a `.generator` property for composition.
-*/
-function reactiveOrAsync(gen) {
-	/**
-	* The generated method wrapper.
-	* @param allArguments Method arguments, optionally ending with a `ModeOptions` object.
-	* @returns The workflow result (sync) or a Promise of the result (async).
-	*/
-	function method(...allArguments) {
-		const last = allArguments.length > 0 ? allArguments.at(-1) : void 0;
-		const hasMode = typeof last === "object" && last !== null && "async" in last;
-		const mode = hasMode ? last : void 0;
-		const parameters = hasMode ? allArguments.slice(0, -1) : allArguments;
-		return runReactiveOrAsync(this, mode, function* (a) {
-			return yield* gen.call(this, a, ...parameters);
+	}
+	queryListeners(query, listeners) {
+		const id = queryId(query.selector, query.options);
+		if (listeners != null) return this.queryListenersMap.set(id, listeners);
+		return this.queryListenersMap.get(id) ?? 0;
+	}
+	/**
+	* Disposes the collection, unregisters persistence adapters, clears memory, and
+	* cleans up all resources used by the collection.
+	* @returns A promise that resolves when the collection is disposed.
+	*/
+	async dispose() {
+		await this.backend.dispose();
+		this.isDisposed = true;
+		this.removeAllListeners();
+		Collection.collections = Collection.collections.filter((collection) => collection !== this);
+		Collection.onDisposeCallbacks.forEach((callback) => callback(this));
+	}
+	find(selector = {}, options) {
+		if (this.isDisposed) throw new Error("Collection is disposed");
+		if (selector !== void 0 && (!selector || typeof selector !== "object")) throw new Error("Invalid selector");
+		const getTransformedItems = () => {
+			const itemsOrPromise = this.getItems(selector, options || {});
+			if (itemsOrPromise instanceof Promise) return itemsOrPromise.then((items) => {
+				return this.transformAll(items, options?.fields);
+			});
+			const items = itemsOrPromise;
+			return this.transformAll(items, options?.fields);
+		};
+		const cursor = new Cursor(getTransformedItems, {
+			reactive: this.options.reactivity,
+			fieldTracking: this.fieldTracking,
+			...options,
+			transform: this.transform.bind(this),
+			queryState: {
+				hasSettled: () => {
+					if (this.settledQueriesSet.has(queryId(selector, options))) return true;
+					const state = this.backend.getQueryState(selector, options || {});
+					return state === "complete" || state === "error";
+				},
+				onSettled: (callback) => this.backend.onQueryStateChange(selector, options || {}, (state) => {
+					if (state !== "complete" && state !== "error") return;
+					this.settledQueriesSet.add(queryId(selector, options));
+					callback();
+				})
+			},
+			bindEvents: (requery, applyDelta) => {
+				const handleRequery = () => {
+					if (this.batchOperationInProgress) {
+						this.postBatchCallbacks.add(requery);
+						return;
+					}
+					requery();
+				};
+				const canApplyDeltas = !this.options.transformAll && !options?.async;
+				const listeners = this.queryListeners({
+					selector,
+					options
+				});
+				const didRegister = listeners === 0;
+				if (didRegister) this.backend.registerQuery(selector, options || {});
+				this.queryListeners({
+					selector,
+					options
+				}, listeners + 1);
+				const queryStateChangeCleanup = this.backend.onQueryStateChange(selector, options || {}, (state, delta) => {
+					if (state === "error") {
+						const queryError = this.backend.getQueryError(selector, options || {}) || /* @__PURE__ */ new Error(`Query on "${this.name}" failed`);
+						this.emit("query.error", queryError, selector, options);
+						return;
+					}
+					if (state !== "complete") return;
+					if (delta != null && canApplyDeltas && !this.batchOperationInProgress) {
+						applyDelta(delta);
+						return;
+					}
+					handleRequery();
+				});
+				this.emit("observer.created", selector, options);
+				return () => {
+					queueMicrotask(() => {
+						const newListeners = Math.max(0, this.queryListeners({
+							selector,
+							options
+						}) - 1);
+						if (newListeners === 0 && didRegister) {
+							this.backend.unregisterQuery(selector, options || {});
+							this.settledQueriesSet.delete(queryId(selector, options));
+						}
+						this.queryListeners({
+							selector,
+							options
+						}, newListeners);
+						queryStateChangeCleanup();
+						this.emit("observer.disposed", selector, options);
+					});
+				};
+			}
+		});
+		this.emit("find", selector, options, cursor);
+		this.executeInDebugMode((callstack) => this.emit("_debug.find", callstack, selector, options, cursor));
+		return cursor;
+	}
+	findOne(selector, options) {
+		if (this.isDisposed) throw new Error("Collection is disposed");
+		const cursor = this.find(selector, {
+			limit: 1,
+			...options
+		});
+		const handleItems = (items) => {
+			const returnValue = items[0] || void 0;
+			this.emit("findOne", selector, options, returnValue);
+			this.executeInDebugMode((callstack) => this.emit("_debug.findOne", callstack, selector, options, returnValue));
+			return returnValue;
+		};
+		const maybePromise = cursor.fetch();
+		return maybePromise instanceof Promise ? maybePromise.then(handleItems) : handleItems(maybePromise);
+	}
+	batch(callback) {
+		if (this.batchOperationInProgress) return callback();
+		this.batchOperationInProgress = true;
+		const afterBatch = () => {
+			this.batchOperationInProgress = false;
+			this.postBatchCallbacks.forEach((callback_) => callback_());
+			this.postBatchCallbacks.clear();
+		};
+		let maybePromise;
+		try {
+			maybePromise = callback();
+		} catch (error) {
+			afterBatch();
+			throw error;
+		}
+		if (maybePromise && typeof maybePromise.then === "function") return maybePromise.then(() => afterBatch(), (error) => {
+			afterBatch();
+			throw error;
+		});
+		else afterBatch();
+	}
+	onPostBatch(callback) {
+		if (this.isDisposed) throw new Error("Collection is disposed");
+		if (this.batchOperationInProgress) {
+			this.postBatchCallbacks.add(callback);
+			return;
+		}
+		return callback();
+	}
+	/**
+	* Inserts a single item into the collection. Generates a unique ID if not provided.
+	* @param item - The item to insert.
+	* @returns The ID of the inserted item.
+	* @throws {Error} If the collection is disposed or the item has an invalid ID.
+	*/
+	async insert(item) {
+		if (this.isDisposed) throw new Error("Collection is disposed");
+		if (!item) throw new Error("Invalid item");
+		const itemWithId = {
+			id: (this.options.primaryKeyGenerator ?? randomId)(item),
+			...item
+		};
+		this.emit("validate", itemWithId);
+		const newItem = await this.withPushState(() => this.backend.insert(itemWithId));
+		this.emit("added", newItem);
+		this.emit("insert", newItem);
+		this.executeInDebugMode((callstack) => this.emit("_debug.insert", callstack, newItem));
+		return newItem.id;
+	}
+	/**
+	* Inserts multiple items into the collection. Generates unique IDs for items if not provided.
+	* @param items - The items to insert.
+	* @returns An array of IDs of the inserted items.
+	* @throws {Error} If the collection is disposed or the items are invalid.
+	*/
+	async insertMany(items) {
+		if (this.isDisposed) throw new Error("Collection is disposed");
+		if (!items) throw new Error("Invalid items");
+		if (items.length === 0) return [];
+		const ids = [];
+		await this.batch(async () => {
+			await Promise.all(items.map(async (item) => {
+				ids.push(await this.insert(item));
+			}));
+		});
+		return ids;
+	}
+	/**
+	* Updates a single item in the collection that matches the given selector.
+	* @param selector - The criteria to select the item to update.
+	* @param modifier - The modifications to apply to the item.
+	* @param [options] - Optional settings for the update operation.
+	* @param [options.upsert] - If `true`, creates a new item if no item matches the selector.
+	* @returns The number of items updated (0 or 1).
+	* @throws {Error} If the collection is disposed or invalid arguments are provided.
+	*/
+	async updateOne(selector, modifier, options) {
+		if (this.isDisposed) throw new Error("Collection is disposed");
+		if (!selector) throw new Error("Invalid selector");
+		if (!modifier) throw new Error("Invalid modifier");
+		const { $setOnInsert, ...restModifier } = modifier;
+		if (this.listenerCount("validate") > 0) {
+			const item = await this.getItem(selector, { async: true });
+			if (item != null) this.emit("validate", modify(deepClone(item), restModifier));
+		}
+		const changes = await this.withPushState(() => this.backend.updateOne(selector, modifier));
+		if (changes.length === 0) {
+			if (!options?.upsert) return 0;
+			const newItem = modify({}, {
+				...restModifier,
+				$set: {
+					...$setOnInsert,
+					...restModifier.$set
+				}
+			});
+			await this.insert(newItem);
+			return 1;
+		}
+		changes.forEach((item) => this.emit("changed", item, restModifier));
+		this.emit("updateOne", selector, modifier);
+		this.executeInDebugMode((callstack) => this.emit("_debug.updateOne", callstack, selector, modifier));
+		return changes.length;
+	}
+	/**
+	* Updates multiple items in the collection that match the given selector.
+	* @param selector - The criteria to select the items to update.
+	* @param modifier - The modifications to apply to the items.
+	* @param [options] - Optional settings for the update operation.
+	* @param [options.upsert] - If `true`, creates new items if no items match the selector.
+	* @returns The number of items updated.
+	* @throws {Error} If the collection is disposed or invalid arguments are provided.
+	*/
+	async updateMany(selector, modifier, options) {
+		if (this.isDisposed) throw new Error("Collection is disposed");
+		if (!selector) throw new Error("Invalid selector");
+		if (!modifier) throw new Error("Invalid modifier");
+		const { $setOnInsert, ...restModifier } = modifier;
+		if (this.listenerCount("validate") > 0) (await this.getItems(selector, { async: true })).forEach((item) => {
+			this.emit("validate", modify(deepClone(item), restModifier));
+		});
+		const changes = await this.withPushState(() => this.backend.updateMany(selector, modifier));
+		if (changes.length === 0) {
+			if (!options?.upsert) return 0;
+			const newItem = modify({}, {
+				...restModifier,
+				$set: {
+					...$setOnInsert,
+					...restModifier.$set
+				}
+			});
+			await this.insert(newItem);
+			return 1;
+		}
+		changes.forEach((item) => {
+			this.emit("changed", item, restModifier);
+		});
+		this.emit("updateMany", selector, modifier);
+		this.executeInDebugMode((callstack) => this.emit("_debug.updateMany", callstack, selector, modifier));
+		return changes.length;
+	}
+	/**
+	* Replaces a single item in the collection that matches the given selector.
+	* @param selector - The criteria to select the item to replace.
+	* @param replacement - The item to replace the selected item with.
+	* @param [options] - Optional settings for the replace operation.
+	* @param [options.upsert] - If `true`, creates a new item if no item matches the selector.
+	* @returns The number of items replaced (0 or 1).
+	* @throws {Error} If the collection is disposed or invalid arguments are provided.
+	*/
+	async replaceOne(selector, replacement, options) {
+		if (this.isDisposed) throw new Error("Collection is disposed");
+		if (!selector) throw new Error("Invalid selector");
+		if (this.listenerCount("validate") > 0) {
+			const item = await this.getItem(selector, { async: true });
+			if (item != null) this.emit("validate", {
+				id: item.id,
+				...replacement
+			});
+		}
+		const changes = await this.withPushState(() => this.backend.replaceOne(selector, replacement));
+		if (changes.length === 0) {
+			if (!options?.upsert) return 0;
+			await this.insert(replacement);
+			return 1;
+		}
+		changes.forEach((item) => this.emit("changed", item, replacement));
+		this.emit("replaceOne", selector, replacement);
+		this.executeInDebugMode((callstack) => this.emit("_debug.replaceOne", callstack, selector, replacement));
+		return changes.length;
+	}
+	/**
+	* Removes a single item from the collection that matches the given selector.
+	* @param selector - The criteria to select the item to remove.
+	* @returns The number of items removed (0 or 1).
+	* @throws {Error} If the collection is disposed or invalid arguments are provided.
+	*/
+	async removeOne(selector) {
+		if (this.isDisposed) throw new Error("Collection is disposed");
+		if (!selector) throw new Error("Invalid selector");
+		const removedItems = await this.withPushState(() => this.backend.removeOne(selector));
+		this.emit("removed", removedItems[0]);
+		this.emit("removeOne", selector);
+		this.executeInDebugMode((callstack) => this.emit("_debug.removeOne", callstack, selector));
+		return removedItems.length;
+	}
+	/**
+	* Removes multiple items from the collection that match the given selector.
+	* @param selector - The criteria to select the items to remove.
+	* @returns The number of items removed.
+	* @throws {Error} If the collection is disposed or invalid arguments are provided.
+	*/
+	async removeMany(selector) {
+		if (this.isDisposed) throw new Error("Collection is disposed");
+		if (!selector) throw new Error("Invalid selector");
+		const removedItems = await this.withPushState(() => this.backend.removeMany(selector));
+		removedItems.forEach((item) => {
+			this.emit("removed", item);
 		});
+		this.emit("removeMany", selector);
+		this.executeInDebugMode((callstack) => this.emit("_debug.removeMany", callstack, selector));
+		return removedItems.length;
 	}
-	method.generator = gen;
-	return method;
-}
+};
 //#endregion
-export { reactiveOrAsync as default, unwrap };
+export { Collection as default };