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

package/dist/index4.cjs.js

@@ -0,0 +1,209 @@
+const require_isEqual = require("./index2.cjs.js");
+//#region src/utils/queryDelta.ts
+/**
+* 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.
+*/
+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;
+	}
+	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;
+	}
+	const result = [];
+	let cursor = tails.at(-1);
+	while (cursor !== -1) {
+		result.push(cursor);
+		cursor = previous[cursor];
+	}
+	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
+			});
+		});
+	}
+	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.applyQueryDelta = applyQueryDelta;
+exports.callWithDelta = callWithDelta;
+exports.canApplyQueryDelta = canApplyQueryDelta;
+exports.diffQueryResults = diffQueryResults;
+exports.isEmptyQueryDelta = isEmptyQueryDelta;

package/dist/index4.mjs

@@ -1,6 +1,205 @@
-function createStorageAdapter(definition) {
-  return definition;
+import isEqual from "./index2.mjs";
+//#region src/utils/queryDelta.ts
+/**
+* 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.
+*/
+function isEmptyQueryDelta(delta) {
+	return delta.added.length === 0 && delta.changed.length === 0 && delta.removed.length === 0 && delta.moved.length === 0;
 }
-export {
-  createStorageAdapter as default
-};
+/**
+* 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;
+	}
+	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;
+	}
+	const result = [];
+	let cursor = tails.at(-1);
+	while (cursor !== -1) {
+		result.push(cursor);
+		cursor = previous[cursor];
+	}
+	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 (!isEqual(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
+			});
+		});
+	}
+	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
+export { applyQueryDelta, callWithDelta, canApplyQueryDelta, diffQueryResults, isEmptyQueryDelta };

package/dist/index5.cjs.js

@@ -0,0 +1,187 @@
+const require_isEqual = require("./index2.cjs.js");
+const require_uniqueBy = require("./index3.cjs.js");
+const require_queryDelta = require("./index4.cjs.js");
+//#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);
+	}
+	/**
+	* Brings the observer up to date from a description of what changed, instead of from the new
+	* result.
+	*
+	* `runChecks` has to rediscover the change by comparing the whole new result against the whole
+	* old one — a cost proportional to the result, paid on every write, to find out that one row
+	* moved. When the change is already known it can simply be reported, and the cost becomes
+	* proportional to the change.
+	*
+	* The delta must have been computed against exactly the result this observer holds. If it was
+	* not, this reports nothing, falls back to `runChecks`, and returns `false`.
+	*
+	* Note that the reported moves are minimal, where a comparison reports every item whose
+	* neighbour changed. Applying them yields the same order either way — there are simply fewer of
+	* them.
+	* @param delta - The change to report.
+	* @param getItems - Used to fall back to a comparison when the delta cannot be applied.
+	* @returns Whether the delta was applied.
+	*/
+	applyDelta(delta, getItems) {
+		if (!require_queryDelta.canApplyQueryDelta(this.previousItems, delta)) {
+			this.runChecks(getItems);
+			return false;
+		}
+		if (require_queryDelta.isEmptyQueryDelta(delta)) return true;
+		this.emitDelta(delta, require_queryDelta.applyQueryDelta(this.previousItems, delta));
+		return true;
+	}
+	/**
+	* Reports a delta and adopts the result it produces.
+	*
+	* The single place the callbacks are fired from, whether the change arrived as a delta or was
+	* found by comparing two results — so the two can never disagree about what a consumer is told.
+	* @param delta - The change to report.
+	* @param nextItems - The result the delta produces.
+	*/
+	emitDelta(delta, nextItems) {
+		if (this.isEmpty()) {
+			this.finishCheck(nextItems);
+			return;
+		}
+		const beforeOf = (index) => nextItems[index + 1] || null;
+		const previousById = delta.removed.length > 0 && this.hasCallbacks(["removed"]) || delta.changed.length > 0 && this.hasCallbacks(["changedField"]) ? new Map(this.previousItems.map((item) => [item.id, item])) : null;
+		if (this.hasCallbacks(["changed", "changedField"])) delta.changed.forEach((item) => {
+			this.call("changed", item);
+			if (!this.hasCallbacks(["changedField"])) return;
+			const oldItem = previousById?.get(item.id);
+			if (!oldItem) return;
+			require_uniqueBy.default([...Object.keys(item), ...Object.keys(oldItem)], (value) => value).forEach((key) => {
+				if (require_isEqual.default(item[key], oldItem[key])) return;
+				this.call("changedField", item, key, oldItem[key], item[key]);
+			});
+		});
+		if (this.hasCallbacks(["removed"])) delta.removed.forEach((id) => {
+			const oldItem = previousById?.get(id);
+			if (oldItem) this.call("removed", oldItem);
+		});
+		if (this.hasCallbacks(["added", "addedBefore"])) delta.added.forEach(({ index, item }) => {
+			this.call("added", item);
+			this.call("addedBefore", item, beforeOf(index));
+		});
+		if (this.hasCallbacks(["movedBefore"])) delta.moved.forEach(({ index }) => {
+			this.call("movedBefore", nextItems[index], beforeOf(index));
+		});
+		this.finishCheck(nextItems);
+	}
+	finishCheck(newItems) {
+		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
+				}
+			}));
+		});
+	}
+	checkItems(newItems) {
+		this.emitDelta(require_queryDelta.diffQueryResults(this.previousItems, newItems), newItems);
+	}
+	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
+exports.default = Observer;