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

package/dist/index4.cjs.js

@@ -1,150 +1,209 @@
 const require_isEqual = require("./index2.cjs.js");
-const require_uniqueBy = require("./index3.cjs.js");
-//#region src/Collection/Observer.ts
+//#region src/utils/queryDelta.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.
+* Checks whether a delta leaves the result it is applied to unchanged.
+* @param delta - The delta to inspect.
+* @returns `true` when applying the delta would be a no-op.
 */
-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);
+function isEmptyQueryDelta(delta) {
+	return delta.added.length === 0 && delta.changed.length === 0 && delta.removed.length === 0 && delta.moved.length === 0;
+}
+/**
+* Calls a state-change callback, passing the delta only when there is one.
+*
+* A callback invoked as `callback(state, undefined)` has been handed two arguments, which is a
+* different thing from being handed one — visible to anything that inspects arity, and to any test
+* that asserts on the call.
+* @template T - The type of the items.
+* @param callback - The callback to invoke.
+* @param state - The state to report.
+* @param delta - The delta to report, if there is one.
+*/
+function callWithDelta(callback, state, delta) {
+	if (delta == null) {
+		callback(state);
+		return;
 	}
-	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"]) && !require_isEqual.default(newItem.item, oldItem)) {
-					this.call("changed", newItem.item);
-					if (this.hasCallbacks(["changedField"])) require_uniqueBy.default([...Object.keys(newItem.item), ...Object.keys(oldItem)], (value) => value).forEach((key) => {
-						if (require_isEqual.default(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
-				}
-			}));
-		});
+	callback(state, delta);
+}
+/**
+* Checks whether a delta describes a change to the given result.
+*
+* A delta is only meaningful against the exact result it was computed from — it names positions in
+* an array and items by id alone. Applying one to anything else produces a result that looks
+* plausible and is wrong, and from then on every further delta compounds the error. This is the
+* cheap structural check that catches that: every id the delta expects to find is there, every id
+* it expects to be new is not, and the arithmetic on the length works out. It costs the size of the
+* delta, not the size of the result.
+* @template T - The type of the items.
+* @param previous - The result the delta would be applied to.
+* @param delta - The delta to check.
+* @returns `true` when the delta can be applied.
+*/
+function canApplyQueryDelta(previous, delta) {
+	const present = new Set(previous.map((item) => item.id));
+	const seen = /* @__PURE__ */ new Set();
+	const claim = (id, shouldExist) => {
+		if (seen.has(id)) return false;
+		seen.add(id);
+		return present.has(id) === shouldExist;
+	};
+	if (previous.length - delta.removed.length + delta.added.length !== delta.resultCount) return false;
+	if (!delta.removed.every((id) => claim(id, true))) return false;
+	if (!delta.added.every(({ index, item }) => claim(item.id, false) && index >= 0 && index < delta.resultCount)) return false;
+	if (!delta.changed.every((item) => present.has(item.id))) return false;
+	return delta.moved.every(({ index, id }) => present.has(id) && !delta.removed.includes(id) && index >= 0 && index < delta.resultCount);
+}
+/**
+* Indices of the longest strictly increasing subsequence of the given numbers.
+* Used to decide which items keep their place when a result is reordered: everything outside the
+* subsequence has to move, everything inside it is already in the right relative order.
+* @param sequence - The numbers to inspect.
+* @returns The indices into `sequence` that form the longest increasing subsequence.
+*/
+function longestIncreasingSubsequence(sequence) {
+	if (sequence.length === 0) return [];
+	const tails = [];
+	const previous = Array.from({ length: sequence.length }).fill(-1);
+	for (let index = 0; index < sequence.length; index += 1) {
+		const value = sequence[index];
+		let low = 0;
+		let high = tails.length;
+		while (low < high) {
+			const middle = low + high >> 1;
+			if (sequence[tails[middle]] < value) low = middle + 1;
+			else high = middle;
+		}
+		if (low > 0) previous[index] = tails[low - 1];
+		tails[low] = index;
 	}
-	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();
+	const result = [];
+	let cursor = tails.at(-1);
+	while (cursor !== -1) {
+		result.push(cursor);
+		cursor = previous[cursor];
 	}
-	/**
-	* 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
-				}
+	return result.toReversed();
+}
+/**
+* Computes the delta between two results of the same query.
+*
+* A fallback for the cases where the change that produced the new result is not available — a query
+* that had to be re-executed in full, for instance. It costs a pass over both results, but it is
+* paid once, on the side that has both of them, instead of shipping the entire new result to
+* everyone who only needs to know what changed.
+* @template T - The type of the items.
+* @param previous - The result the delta should be relative to.
+* @param next - The result the delta should produce.
+* @returns The delta between the two results.
+*/
+function diffQueryResults(previous, next) {
+	if (holdsTheSameItems(previous, next)) return {
+		added: [],
+		changed: [],
+		removed: [],
+		moved: [],
+		resultCount: next.length
+	};
+	const previousIndexById = /* @__PURE__ */ new Map();
+	previous.forEach((item, index) => previousIndexById.set(item.id, index));
+	const added = [];
+	const changed = [];
+	const survivingPreviousIndices = [];
+	const survivingNextIndices = [];
+	const survived = Array.from({ length: previous.length }).fill(false);
+	let orderPreserved = true;
+	let lastPreviousIndex = -1;
+	next.forEach((item, index) => {
+		const previousIndex = previousIndexById.get(item.id);
+		if (previousIndex == null) {
+			added.push({
+				index,
+				item
+			});
+			return;
+		}
+		survived[previousIndex] = true;
+		if (!require_isEqual.default(previous[previousIndex], item)) changed.push(item);
+		if (previousIndex < lastPreviousIndex) orderPreserved = false;
+		lastPreviousIndex = previousIndex;
+		survivingPreviousIndices.push(previousIndex);
+		survivingNextIndices.push(index);
+	});
+	const removed = [];
+	previous.forEach((item, index) => {
+		if (!survived[index]) removed.push(item.id);
+	});
+	const moved = [];
+	if (!orderPreserved) {
+		const stationary = new Set(longestIncreasingSubsequence(survivingPreviousIndices).map((position) => survivingNextIndices[position]));
+		survivingNextIndices.forEach((nextIndex) => {
+			if (stationary.has(nextIndex)) return;
+			moved.push({
+				index: nextIndex,
+				id: next[nextIndex].id
 			});
 		});
 	}
-	/**
-	* 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);
-		});
-	}
-};
+	return {
+		added,
+		changed,
+		removed,
+		moved,
+		resultCount: next.length
+	};
+}
+/**
+* Whether two results hold the same items in the same order, by identity.
+*
+* Items are replaced rather than mutated wherever they come from, so identity is a sound answer to
+* "unchanged" — and a wrong one is impossible, only a missed shortcut.
+* @template T - The type of the items.
+* @param previous - One result.
+* @param next - The other.
+* @returns `true` when the two are element-for-element the same objects.
+*/
+function holdsTheSameItems(previous, next) {
+	if (previous === next) return true;
+	if (previous.length !== next.length) return false;
+	return previous.every((item, index) => item === next[index]);
+}
+/**
+* Applies a delta to the result it was computed against.
+* @template T - The type of the items.
+* @param previous - The result the delta is relative to. Not modified.
+* @param delta - The delta to apply.
+* @returns The resulting items.
+*/
+function applyQueryDelta(previous, delta) {
+	const removed = new Set(delta.removed);
+	const changedById = new Map(delta.changed.map((item) => [item.id, item]));
+	const movedIds = new Set(delta.moved.map(({ id }) => id));
+	const stationary = [];
+	const byId = /* @__PURE__ */ new Map();
+	previous.forEach((item) => {
+		if (removed.has(item.id)) return;
+		const current = changedById.get(item.id) ?? item;
+		byId.set(current.id, current);
+		if (!movedIds.has(current.id)) stationary.push(current);
+	});
+	const insertions = [...delta.added.map(({ index, item }) => ({
+		index,
+		item
+	})), ...delta.moved.map(({ index, id }) => ({
+		index,
+		item: byId.get(id)
+	}))].sort((a, b) => a.index - b.index);
+	const result = stationary;
+	insertions.forEach(({ index, item }) => {
+		if (item == null) return;
+		result.splice(index, 0, item);
+	});
+	return result;
+}
 //#endregion
-exports.default = Observer;
+exports.applyQueryDelta = applyQueryDelta;
+exports.callWithDelta = callWithDelta;
+exports.canApplyQueryDelta = canApplyQueryDelta;
+exports.diffQueryResults = diffQueryResults;
+exports.isEmptyQueryDelta = isEmptyQueryDelta;