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

package/dist/base/core/src/AsyncDataAdapter.d.ts

@@ -82,16 +82,25 @@ export default class AsyncDataAdapter implements DataAdapter {
      * @param qid - query id
      * @param state - new state
      * @param error - error if state is 'error', null otherwise
+     * @param delta - what changed about the result, when that is known
      */
     private publishState;
     private publishResult;
+    private queryItemIds;
     private getIndexInfo;
     private queryItems;
     private executeQuery;
     /**
-     * After mutations, recompute and push updates for affected active queries
+     * After mutations, bring every affected active query up to date.
+     *
+     * A query whose previous result is enough to answer the change is brought up to date from that
+     * result alone — no round trip to the storage, and no detour through `'active'`, because there is
+     * no window in which the query is stale. Only a query the change cannot be reasoned about
+     * locally — a window onto a larger set, or one that has never been answered — goes back to the
+     * store, and that one gets the same retry and reporting behaviour a freshly registered query
+     * gets: a refresh that fails silently leaves exactly the same dead cursor.
      * @param collectionName - name of the collection
-     * @param affectedItems - item states before and/or after the mutation
+     * @param changes - the items the write created, updated or removed
      */
     private checkQueryUpdates;
     private insert;

package/dist/base/core/src/AsyncDataAdapter.js

@@ -12,7 +12,9 @@ const isEqual_1 = __importDefault(require("./utils/isEqual"));
 const getIndexInfo_1 = __importDefault(require("./getIndexInfo"));
 const getMatchingKeys_1 = __importDefault(require("./utils/getMatchingKeys"));
 const sortItems_1 = __importDefault(require("./utils/sortItems"));
-const project_1 = __importDefault(require("./utils/project"));
+const projectItems_1 = __importDefault(require("./utils/projectItems"));
+const incrementalQueryUpdate_1 = __importDefault(require("./utils/incrementalQueryUpdate"));
+const queryDelta_1 = require("./utils/queryDelta");
 /**
  * Carries the context needed to act on a failed query. The bare storage error
  * on its own does not say which collection or selector produced it, which made
@@ -35,6 +37,27 @@ class QueryError extends Error {
     }
 }
 exports.QueryError = QueryError;
+/**
+ * Turns the item states a write produced into the upsert/delete split a query update needs.
+ *
+ * The two lists are not symmetric: an item that is still there after the write is described by its
+ * new state, while an item that is gone — removed, or given a new id — is described by the id it
+ * used to have and nothing else. Mixing the states from before and after a write into one list
+ * loses exactly that distinction.
+ * @template T - The type of the items.
+ * @param previousItems - The items as they were before the write.
+ * @param modifiedItems - The items as they are after it.
+ * @returns The changeset describing the write.
+ */
+function toChangeset(previousItems, modifiedItems) {
+    const modifiedIds = new Set(modifiedItems.map(item => item.id));
+    return {
+        upserts: modifiedItems,
+        deletes: previousItems
+            .map(item => item.id)
+            .filter(id => !modifiedIds.has(id)),
+    };
+}
 const DEFAULT_RETRY_ATTEMPTS = 3;
 const defaultRetryDelay = (attempt) => 100 * (4 ** (attempt - 1));
 const wait = (ms) => new Promise((resolve) => {
@@ -254,8 +277,14 @@ class AsyncDataAdapter {
                 return;
             try {
                 const items = await this.executeQuery(collectionName, selector, options);
+                const rec = this.queries.get(collectionName)?.get(qid);
+                // A query answered for the first time has no previous result to be relative to; whoever is
+                // waiting on it holds nothing yet and needs the whole thing.
+                const delta = rec?.answered
+                    ? (0, queryDelta_1.diffQueryResults)(rec.items, items)
+                    : undefined;
                 this.publishResult(collectionName, qid, items);
-                this.publishState(collectionName, qid, 'complete', null);
+                this.publishState(collectionName, qid, 'complete', null, delta);
                 return;
             }
             catch (error) {
@@ -274,8 +303,9 @@ class AsyncDataAdapter {
      * @param qid - query id
      * @param state - new state
      * @param error - error if state is 'error', null otherwise
+     * @param delta - what changed about the result, when that is known
      */
-    publishState(collectionName, qid, state, error) {
+    publishState(collectionName, qid, state, error, delta) {
         const rec = this.queries.get(collectionName)?.get(qid);
         if (!rec)
             return;
@@ -289,7 +319,7 @@ class AsyncDataAdapter {
         const subscribers = [...rec.listeners];
         for (const callback of subscribers) {
             try {
-                callback(state);
+                (0, queryDelta_1.callWithDelta)(callback, state, delta);
             }
             catch (error_) {
                 this.onError(error_);
@@ -301,6 +331,13 @@ class AsyncDataAdapter {
         if (!rec)
             return;
         rec.items = items;
+        rec.itemIds = undefined;
+        rec.answered = true;
+    }
+    queryItemIds(rec) {
+        if (!rec.itemIds)
+            rec.itemIds = new Set(rec.items.map(item => item.id));
+        return rec.itemIds;
     }
     async getIndexInfo(collectionName, selector) {
         const storageAdapter = this.storageAdapters.get(collectionName);
@@ -395,37 +432,60 @@ class AsyncDataAdapter {
         const sorted = sort ? (0, sortItems_1.default)(items, sort) : items;
         const skipped = skip ? sorted.slice(skip) : sorted;
         const limited = limit ? skipped.slice(0, limit) : skipped;
-        const idExcluded = fields && fields.id === 0;
-        return limited.map((item) => {
-            if (!fields)
-                return item;
-            return { ...(idExcluded ? {} : { id: item.id }), ...(0, project_1.default)(item, fields) };
-        });
+        return (0, projectItems_1.default)(limited, fields);
     }
     /**
-     * After mutations, recompute and push updates for affected active queries
+     * After mutations, bring every affected active query up to date.
+     *
+     * A query whose previous result is enough to answer the change is brought up to date from that
+     * result alone — no round trip to the storage, and no detour through `'active'`, because there is
+     * no window in which the query is stale. Only a query the change cannot be reasoned about
+     * locally — a window onto a larger set, or one that has never been answered — goes back to the
+     * store, and that one gets the same retry and reporting behaviour a freshly registered query
+     * gets: a refresh that fails silently leaves exactly the same dead cursor.
      * @param collectionName - name of the collection
-     * @param affectedItems - item states before and/or after the mutation
+     * @param changes - the items the write created, updated or removed
      */
-    async checkQueryUpdates(collectionName, affectedItems) {
+    async checkQueryUpdates(collectionName, changes) {
         const registry = this.queries.get(collectionName);
         if (!registry)
             throw new Error(`Collection ${collectionName} not initialized!`);
         if (registry.size === 0)
             return;
-        // Find active queries matching an item state before or after the mutation
-        const affected = [...registry.values()].filter(({ selector }) => affectedItems.some(item => (0, match_1.default)(item, selector)));
+        if (changes.upserts.length === 0 && changes.deletes.length === 0)
+            return;
+        // A query is affected when the write produces something it should hold, or takes away
+        // something it already holds. The second half is what the written items cannot tell us on
+        // their own: an item that no longer matches, or that is gone, is invisible to the matcher.
+        const affected = [...registry.values()].filter((rec) => {
+            const ids = this.queryItemIds(rec);
+            if (changes.deletes.some(id => ids.has(id)))
+                return true;
+            return changes.upserts.some(item => ids.has(item.id) || (0, match_1.default)(item, rec.selector));
+        });
         if (affected.length === 0)
             return;
-        // Mark active and notify…
-        for (const { selector, options } of affected) {
+        const needsReExecution = [];
+        for (const rec of affected) {
+            const { selector, options } = rec;
+            const incremental = rec.answered
+                ? (0, incrementalQueryUpdate_1.default)(rec.items, selector, options, changes)
+                : null;
+            if (incremental == null) {
+                needsReExecution.push(rec);
+                continue;
+            }
             const qid = (0, queryId_1.default)(selector, options);
-            this.publishState(collectionName, qid, 'active', null);
+            const delta = (0, queryDelta_1.diffQueryResults)(rec.items, incremental);
+            if ((0, queryDelta_1.isEmptyQueryDelta)(delta))
+                continue;
+            this.publishResult(collectionName, qid, incremental);
+            this.publishState(collectionName, qid, 'complete', null, delta);
         }
-        // …then recompute and complete, with the same retry/report behaviour a
-        // freshly registered query gets — a mutation-triggered refresh that fails
-        // silently leaves exactly the same dead cursor.
-        await Promise.all(affected.map(({ selector, options }) => this.runQuery(collectionName, selector, options)));
+        for (const { selector, options } of needsReExecution) {
+            this.publishState(collectionName, (0, queryId_1.default)(selector, options), 'active', null);
+        }
+        await Promise.all(needsReExecution.map(({ selector, options }) => this.runQuery(collectionName, selector, options)));
     }
     async insert(collectionName, newItem) {
         const storage = this.storageAdapters.get(collectionName);
@@ -435,7 +495,7 @@ class AsyncDataAdapter {
         if (existingItems.length > 0)
             throw new Error(`Item with id ${String(newItem.id)} already exists`);
         await storage.insert([newItem]);
-        await this.checkQueryUpdates(collectionName, [newItem]);
+        await this.checkQueryUpdates(collectionName, { upserts: [newItem], deletes: [] });
         return newItem;
     }
     async updateOne(collectionName, selector, modifier) {
@@ -454,7 +514,7 @@ class AsyncDataAdapter {
                 throw new Error(`Item with id ${String(modified.id)} already exists`);
         }
         await storage.replace([modified]);
-        await this.checkQueryUpdates(collectionName, [item, modified]);
+        await this.checkQueryUpdates(collectionName, toChangeset([item], [modified]));
         return [modified];
     }
     async updateMany(collectionName, selector, modifier) {
@@ -475,7 +535,7 @@ class AsyncDataAdapter {
             return modified;
         }));
         await storage.replace(changed);
-        await this.checkQueryUpdates(collectionName, [...items, ...changed]);
+        await this.checkQueryUpdates(collectionName, toChangeset(items, changed));
         return changed;
     }
     async replaceOne(collectionName, selector, replacement) {
@@ -493,7 +553,7 @@ class AsyncDataAdapter {
                 throw new Error(`Item with id ${String(modified.id)} already exists`);
         }
         await storage.replace([modified]);
-        await this.checkQueryUpdates(collectionName, [item, modified]);
+        await this.checkQueryUpdates(collectionName, toChangeset([item], [modified]));
         return [modified];
     }
     async removeOne(collectionName, selector) {
@@ -505,7 +565,7 @@ class AsyncDataAdapter {
         if (item == null)
             return [];
         await storage.remove([item]);
-        await this.checkQueryUpdates(collectionName, [item]);
+        await this.checkQueryUpdates(collectionName, { upserts: [], deletes: [item.id] });
         return [item];
     }
     async removeMany(collectionName, selector) {
@@ -516,7 +576,10 @@ class AsyncDataAdapter {
         if (items.length === 0)
             return [];
         await storage.remove(items);
-        await this.checkQueryUpdates(collectionName, items);
+        await this.checkQueryUpdates(collectionName, {
+            upserts: [],
+            deletes: items.map(item => item.id),
+        });
         return items;
     }
 }

package/dist/base/core/src/Collection/Cursor.d.ts

@@ -1,4 +1,5 @@
 import type ReactivityAdapter from '../types/ReactivityAdapter';
+import type { QueryDelta } from '../utils/queryDelta';
 import type { BaseItem, FindOptions, Transform } from './types';
 import type { ObserveCallbacks } from './Observer';
 /**
@@ -25,7 +26,7 @@ export interface QueryStateAccessor {
 }
 export interface CursorOptions<T extends BaseItem, U = T, Async extends boolean = false> extends FindOptions<T, Async> {
     transform?: Transform<T, U>;
-    bindEvents?: (requery: () => void) => () => void;
+    bindEvents?: (requery: () => void, applyDelta: (delta: QueryDelta<T>) => void) => () => void;
     queryState?: QueryStateAccessor;
 }
 /**
@@ -152,4 +153,13 @@ export default class Cursor<T extends BaseItem, U = T, Async extends boolean = f
      * criteria have changed, and you want to ensure the cursor reflects the latest state.
      */
     requery(): void;
+    /**
+     * Brings the cursor up to date from a description of what changed, rather than by re-running the
+     * query and comparing the result with the previous one.
+     *
+     * Falls back to `requery` when the delta does not fit the result the cursor currently holds, so
+     * a caller never has to decide which of the two is safe.
+     * @param delta - The change to apply.
+     */
+    applyDelta(delta: QueryDelta<T>): void;
 }

package/dist/base/core/src/Collection/Cursor.js

@@ -142,7 +142,11 @@ class Cursor {
                 const requery = () => {
                     observer.runChecks(this.getItems);
                 };
-                const cleanup = this.options.bindEvents && this.options.bindEvents(requery);
+                const applyDelta = (delta) => {
+                    observer.applyDelta(delta, this.getItems);
+                };
+                const cleanup = this.options.bindEvents
+                    && this.options.bindEvents(requery, applyDelta);
                 return () => {
                     if (cleanup)
                         cleanup();
@@ -331,5 +335,18 @@ class Cursor {
             return;
         this.observer.runChecks(this.getItems);
     }
+    /**
+     * Brings the cursor up to date from a description of what changed, rather than by re-running the
+     * query and comparing the result with the previous one.
+     *
+     * Falls back to `requery` when the delta does not fit the result the cursor currently holds, so
+     * a caller never has to decide which of the two is safe.
+     * @param delta - The change to apply.
+     */
+    applyDelta(delta) {
+        if (!this.observer)
+            return;
+        this.observer.applyDelta(delta, this.getItems);
+    }
 }
 exports.default = Cursor;

package/dist/base/core/src/Collection/Observer.d.ts

@@ -1,3 +1,4 @@
+import type { QueryDelta } from '../utils/queryDelta';
 type AddedCallback<T> = (item: T) => void;
 type AddedBeforeCallback<T> = (item: T, before: T) => void;
 type ChangedCallback<T> = (item: T) => void;
@@ -42,6 +43,36 @@ export default class Observer<T extends {
      * @param getItems - A function that returns a promise resolving to the new items or the items themselves.
      */
     runChecks(getItems: () => Promise<T[]> | T[]): void;
+    /**
+     * 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: QueryDelta<T>, getItems: () => Promise<T[]> | T[]): boolean;
+    /**
+     * 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.
+     */
+    private emitDelta;
+    private finishCheck;
     private checkItems;
     private stopped;
     /**

package/dist/base/core/src/Collection/Observer.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const isEqual_1 = __importDefault(require("../utils/isEqual"));
 const uniqueBy_1 = __importDefault(require("../utils/uniqueBy"));
+const queryDelta_1 = require("../utils/queryDelta");
 /**
  * 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.
@@ -74,58 +75,97 @@ class Observer {
             this.checkItems(result);
         }
     }
-    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'])) {
-            // Check for removed or changed items
-            oldItemsMap.forEach(({ item: oldItem, index, beforeItem: oldBeforeItem }) => {
-                const newItem = newItemsMap.get(oldItem.id);
-                if (newItem) {
-                    if (this.hasCallbacks(['changed', 'changedField']) // If the item exists but has changed, call 'changed' callback
-                        && !(0, isEqual_1.default)(newItem.item, oldItem)) {
-                        this.call('changed', newItem.item);
-                        if (this.hasCallbacks(['changedField'])) {
-                            // check for changed fields and call 'changedField' callback
-                            const keys = (0, uniqueBy_1.default)([
-                                ...Object.keys(newItem.item),
-                                ...Object.keys(oldItem),
-                            ], value => value);
-                            keys.forEach((key) => {
-                                if ((0, isEqual_1.default)(newItem.item[key], oldItem[key]))
-                                    return;
-                                this.call('changedField', newItem.item, key, oldItem[key], newItem.item[key]);
-                            });
-                        }
-                    }
-                    // If the item's beforeItem has changed, call 'movedBefore' callback
-                    if (newItem.index !== index && newItem.beforeItem?.id !== oldBeforeItem?.id) {
-                        this.call('movedBefore', newItem.item, newItem.beforeItem);
-                    }
-                }
-                else {
-                    // If the item no longer exists, call 'removed' callback
+    /**
+     * 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 (!(0, queryDelta_1.canApplyQueryDelta)(this.previousItems, delta)) {
+            this.runChecks(getItems);
+            return false;
+        }
+        if ((0, queryDelta_1.isEmptyQueryDelta)(delta))
+            return true;
+        this.emitDelta(delta, (0, queryDelta_1.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;
+        // Indexing the previous result costs its whole length, and most deltas do not need it: an item
+        // that changed is reported by its new value, and only a listener asking which *field* changed,
+        // or one asking about a removal, needs to see what was there before.
+        const needsPreviousItems = (delta.removed.length > 0 && this.hasCallbacks(['removed']))
+            || (delta.changed.length > 0 && this.hasCallbacks(['changedField']));
+        const previousById = needsPreviousItems
+            ? 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;
+                const keys = (0, uniqueBy_1.default)([
+                    ...Object.keys(item),
+                    ...Object.keys(oldItem),
+                ], value => value);
+                keys.forEach((key) => {
+                    if ((0, isEqual_1.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'])) {
-            // Check for added items
-            newItems.forEach((newItem, index) => {
-                const oldItem = oldItemsMap.get(newItem.id);
-                if (oldItem)
-                    return;
-                // If the item is newly added, call 'added' and 'addedBefore' callbacks
-                this.call('added', newItem);
-                this.call('addedBefore', newItem, newItems[index + 1] || null);
+            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) {
         // Store new items as previous items for next check
         this.previousItems = newItems;
         Object.keys(this.callbacks).forEach((key) => {
@@ -140,6 +180,12 @@ class Observer {
             }));
         });
     }
+    checkItems(newItems) {
+        // Derives the change and reports it through the same path a change that arrived ready-made
+        // takes. Comparing and then reporting item by item, as this used to, meant the two paths could
+        // describe the same change differently — most visibly in how many moves they reported.
+        this.emitDelta((0, queryDelta_1.diffQueryResults)(this.previousItems, newItems), newItems);
+    }
     stopped = false;
     /**
      * Stops the observer by unbinding all events and cleaning up resources.