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

package/dist/Collection/index.d.ts

@@ -74,7 +74,22 @@ export default class Collection<T extends BaseItem<I> = BaseItem, I = any, E ext
     private static fieldTracking;
     private static onCreationCallbacks;
     private static onDisposeCallbacks;
+    private static largeQueryWarningThreshold;
+    private static reportedLargeQueries;
     static getCollections(): Collection<any, any, any, any>[];
+    /**
+     * 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: number | null): void;
     static onCreation(callback: (collection: Collection<any>) => void): void;
     static onDispose(callback: (collection: Collection<any>) => void): void;
     /**
@@ -92,11 +107,27 @@ export default class Collection<T extends BaseItem<I> = BaseItem, I = any, E ext
      * This improves performance by avoiding repetitive index recalculations and
      * provides atomicity for the batch of operations.
      * Supports both synchronous and asynchronous callbacks.
+     *
+     * **Without a `collections` argument this affects every collection in the
+     * process, not only the ones being written to.** Each of them defers every
+     * live query's requery until the batch ends. That is what makes a batch
+     * cheap for a handful of writes belonging to one event, and what makes it
+     * dangerous around a loop whose length is data-dependent: while it is open
+     * nothing anywhere updates, and everything deferred is flushed at once when
+     * it closes. One application wrapped a sync of roughly 1,100 records this
+     * way and its screens stopped resolving their data for the whole drain.
+     *
+     * Pass the collections being written to whenever that scope is known — it is
+     * both cheaper and safer. `Collection.batch([logs, versions], () => …)`
+     * defers those two and leaves everything else live.
+     * @param collections - The collections to batch. Omit to batch all of them.
      * @param callback - The batch operation to execute.
      * @returns A promise if the callback returns a promise, otherwise `void`.
      */
     static batch<ReturnType>(callback: () => Promise<ReturnType>): Promise<void>;
     static batch<ReturnType>(callback: () => ReturnType): void;
+    static batch<ReturnType>(collections: Collection<any, any, any, any>[], callback: () => Promise<ReturnType>): Promise<void>;
+    static batch<ReturnType>(collections: Collection<any, any, any, any>[], callback: () => ReturnType): void;
     readonly name: string;
     private backend;
     private options;
@@ -131,6 +162,15 @@ export default class Collection<T extends BaseItem<I> = BaseItem, I = any, E ext
      */
     constructor(options?: CollectionOptions<T, I, E, U>);
     constructor(name: string, dataAdapter: DataAdapter, options?: CollectionOptions<T, I, E, U>);
+    /**
+     * 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.
+     */
+    private reportIfLargeQuery;
     isBatchOperationInProgress(): boolean;
     /**
      * Checks whether the collection is currently performing a pull operation

package/dist/index28.cjs.js

@@ -23,9 +23,27 @@ var Collection = class Collection extends require_EventEmitter.default {
 	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);
 	}
@@ -37,6 +55,7 @@ var Collection = class Collection extends require_EventEmitter.default {
 	*/
 	static enableDebugMode = () => {
 		Collection.debugMode = true;
+		if (Collection.largeQueryWarningThreshold == null) Collection.reportLargeQueries(500);
 		Collection.collections.forEach((collection) => {
 			collection.setDebugMode(true);
 		});
@@ -51,13 +70,17 @@ var Collection = class Collection extends require_EventEmitter.default {
 			collection.setFieldTracking(enable);
 		});
 	};
-	static batch(callback) {
-		Collection.batchOperationInProgress = true;
-		const execute = () => Collection.collections.reduce((memo, collection) => () => {
+	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 = () => {
-			Collection.batchOperationInProgress = false;
+			if (!scoped) Collection.batchOperationInProgress = false;
 		};
 		let maybePromise;
 		try {
@@ -105,6 +128,25 @@ var Collection = class Collection extends require_EventEmitter.default {
 		}).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;
 	}
@@ -297,6 +339,8 @@ var Collection = class Collection extends require_EventEmitter.default {
 					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`);
@@ -304,6 +348,7 @@ var Collection = class Collection extends require_EventEmitter.default {
 						return;
 					}
 					if (state !== "complete") return;
+					this.reportIfLargeQuery(selector, options, registrationStack);
 					if (delta != null && canApplyDeltas && !this.batchOperationInProgress) {
 						applyDelta(delta);
 						return;

package/dist/index28.mjs

@@ -23,9 +23,27 @@ var Collection = class Collection extends EventEmitter {
 	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);
 	}
@@ -37,6 +55,7 @@ var Collection = class Collection extends EventEmitter {
 	*/
 	static enableDebugMode = () => {
 		Collection.debugMode = true;
+		if (Collection.largeQueryWarningThreshold == null) Collection.reportLargeQueries(500);
 		Collection.collections.forEach((collection) => {
 			collection.setDebugMode(true);
 		});
@@ -51,13 +70,17 @@ var Collection = class Collection extends EventEmitter {
 			collection.setFieldTracking(enable);
 		});
 	};
-	static batch(callback) {
-		Collection.batchOperationInProgress = true;
-		const execute = () => Collection.collections.reduce((memo, collection) => () => {
+	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 = () => {
-			Collection.batchOperationInProgress = false;
+			if (!scoped) Collection.batchOperationInProgress = false;
 		};
 		let maybePromise;
 		try {
@@ -105,6 +128,25 @@ var Collection = class Collection extends EventEmitter {
 		}).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}:${queryId(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;
 	}
@@ -297,6 +339,8 @@ var Collection = class Collection extends EventEmitter {
 					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`);
@@ -304,6 +348,7 @@ var Collection = class Collection extends EventEmitter {
 						return;
 					}
 					if (state !== "complete") return;
+					this.reportIfLargeQuery(selector, options, registrationStack);
 					if (delta != null && canApplyDeltas && !this.batchOperationInProgress) {
 						applyDelta(delta);
 						return;

package/dist/index34.cjs.js

@@ -482,7 +482,7 @@ var WorkerDataAdapter = class WorkerDataAdapter {
 				this.worker.terminate?.();
 			},
 			isReady: async () => {
-				await this.exec("isReady", collection.name);
+				await this.collectionReady.get(collection.name);
 			}
 		};
 	}

package/dist/index34.mjs

@@ -482,7 +482,7 @@ var WorkerDataAdapter = class WorkerDataAdapter {
 				this.worker.terminate?.();
 			},
 			isReady: async () => {
-				await this.exec("isReady", collection.name);
+				await this.collectionReady.get(collection.name);
 			}
 		};
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaldb/core",
-  "version": "2.0.0-beta.14",
+  "version": "2.0.0-beta.15",
   "description": "SignalDB is a client-side database that provides a simple MongoDB-like interface to the data with first-class typescript support to achieve an optimistic UI. Data persistence can be achieved by using storage providers that store the data through a JSON interface to places such as localStorage.",
   "scripts": {
     "build": "rimraf dist && vite build",