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

package/dist/index29.cjs.js

@@ -0,0 +1,602 @@
+const require_Cursor = require("./index6.cjs.js");
+const require_EventEmitter = require("./index7.cjs.js");
+const require_createSignal = require("./index8.cjs.js");
+const require_randomId = require("./index9.cjs.js");
+require("./index15.cjs.js");
+const require_deepClone = require("./index18.cjs.js");
+const require_modify = require("./index20.cjs.js");
+const require_queryId = require("./index26.cjs.js");
+const require_DefaultDataAdapter = require("./index28.cjs.js");
+//#region src/Collection/index.ts
+/**
+* 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).
+*/
+var Collection = class Collection extends require_EventEmitter.default {
+	static collections = [];
+	static debugMode = false;
+	static batchOperationInProgress = false;
+	static fieldTracking = false;
+	static onCreationCallbacks = [];
+	static onDisposeCallbacks = [];
+	static largeQueryWarningThreshold = null;
+	static reportedLargeQueries = /* @__PURE__ */ new Set();
+	static getCollections() {
+		return Collection.collections;
+	}
+	/**
+	* Reports live queries whose result is larger than `rows`, once each, with
+	* the stack that registered them.
+	*
+	* A reactive query is re-evaluated whenever the data under it changes, and
+	* one registered from a long-lived place — a navigation bar, a provider
+	* near the root — keeps that cost for the lifetime of the application. There
+	* is otherwise nothing to see: the query works, and its price is only
+	* visible as an application that has grown slow. Finding one such query in a
+	* real app took a purpose-built profiler and the better part of a day.
+	* @param rows - Result size to report above, or `null` to switch the check off.
+	*/
+	static reportLargeQueries(rows) {
+		Collection.largeQueryWarningThreshold = rows;
+		if (rows == null) Collection.reportedLargeQueries.clear();
+	}
+	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;
+		if (Collection.largeQueryWarningThreshold == null) Collection.reportLargeQueries(500);
+		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(collectionsOrCallback, maybeCallback) {
+		const scoped = Array.isArray(collectionsOrCallback);
+		const callback = scoped ? maybeCallback : collectionsOrCallback;
+		if (typeof callback !== "function") throw new TypeError("Collection.batch requires a callback");
+		const collections = scoped ? collectionsOrCallback : Collection.collections;
+		if (!scoped) Collection.batchOperationInProgress = true;
+		const execute = () => collections.reduce((memo, collection) => () => {
+			return collection.batch(memo);
+		}, callback)();
+		const afterBatch = () => {
+			if (!scoped) Collection.batchOperationInProgress = false;
+		};
+		let maybePromise;
+		try {
+			maybePromise = execute();
+		} catch (error) {
+			afterBatch();
+			throw error;
+		}
+		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}-${require_randomId.default()}`;
+		const options = typeof nameOrOptions === "string" ? maybeOptions || {} : nameOrOptions || {};
+		const persistence = options.persistence;
+		const dataAdapter = maybeDataAdapter || new require_DefaultDataAdapter.default({ ...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 = require_createSignal.default(this.options.reactivity, false);
+		this.isPushingSignal = require_createSignal.default(this.options.reactivity, false);
+		this.readySignal = require_createSignal.default(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));
+	}
+	/**
+	* Reports a live query the first time its result is found to be larger than
+	* the configured threshold. Once per query, because it re-runs on every
+	* write and a warning per write would be its own performance problem.
+	* @param selector - The query's selector.
+	* @param options - The query's options.
+	* @param registrationStack - Where the query was registered, if captured.
+	*/
+	reportIfLargeQuery(selector, options, registrationStack) {
+		const threshold = Collection.largeQueryWarningThreshold;
+		if (threshold == null) return;
+		const id = `${this.name}:${require_queryId.default(selector, options)}`;
+		if (Collection.reportedLargeQueries.has(id)) return;
+		const rows = this.backend.getQueryResult(selector, options || {}).length;
+		if (rows <= threshold) return;
+		Collection.reportedLargeQueries.add(id);
+		const keys = selector && typeof selector === "object" ? Object.keys(selector) : [];
+		console.warn(`[SignalDB] Live query on "${this.name}" holds ${rows} rows with selector {${keys.join(", ")}}. It is re-evaluated on every write to this collection, for as long as it stays registered. ${registrationStack ?? ""}`);
+	}
+	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(require_deepClone.default(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);
+		}
+	}
+	queryListeners(query, listeners) {
+		const id = require_queryId.default(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 require_Cursor.default(getTransformedItems, {
+			reactive: this.options.reactivity,
+			fieldTracking: this.fieldTracking,
+			...options,
+			transform: this.transform.bind(this),
+			queryState: {
+				hasSettled: () => {
+					if (this.settledQueriesSet.has(require_queryId.default(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(require_queryId.default(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 registrationStack = didRegister && Collection.largeQueryWarningThreshold != null ? (/* @__PURE__ */ new Error("query registered here")).stack : void 0;
+				if (didRegister) this.reportIfLargeQuery(selector, options, registrationStack);
+				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;
+					this.reportIfLargeQuery(selector, options, registrationStack);
+					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) {
+							this.backend.unregisterQuery(selector, options || {});
+							this.settledQueriesSet.delete(require_queryId.default(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 ?? require_randomId.default)(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", require_modify.default(require_deepClone.default(item), restModifier));
+		}
+		const changes = await this.withPushState(() => this.backend.updateOne(selector, modifier));
+		if (changes.length === 0) {
+			if (!options?.upsert) return 0;
+			const newItem = require_modify.default({}, {
+				...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", require_modify.default(require_deepClone.default(item), restModifier));
+		});
+		const changes = await this.withPushState(() => this.backend.updateMany(selector, modifier));
+		if (changes.length === 0) {
+			if (!options?.upsert) return 0;
+			const newItem = require_modify.default({}, {
+				...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;
+	}
+};
+//#endregion
+exports.default = Collection;