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

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

@@ -281,8 +281,13 @@ class AsyncDataAdapter {
             return;
         rec.state = state;
         rec.error = error;
-        // notify subscribers
-        for (const callback of rec.listeners) {
+        // Notify over a snapshot, never the live set: a subscriber is free to
+        // resubscribe from inside its own callback — a reactive scope that reads
+        // the query state does exactly that when it re-runs — and `Set` iteration
+        // visits entries added while it is still running, so notifying in place
+        // turns one state change into an unbounded loop.
+        const subscribers = [...rec.listeners];
+        for (const callback of subscribers) {
             try {
                 callback(state);
             }

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

@@ -7,9 +7,26 @@ import type { ObserveCallbacks } from './Observer';
  * @returns A boolean indicating if the current scope is reactive.
  */
 export declare function isInReactiveScope(reactivity: ReactivityAdapter | undefined | false): boolean;
+/**
+ * Reports whether the query a cursor stands for has produced an outcome yet.
+ * Supplied by the collection, which owns the query registration; a cursor
+ * built without one simply never reports itself as loading.
+ */
+export interface QueryStateAccessor {
+    /**
+     * Whether the query has settled — completed or failed — at least once
+     * since it was registered.
+     */
+    hasSettled: () => boolean;
+    /**
+     * Subscribes to the query settling. Returns a cleanup function.
+     */
+    onSettled: (callback: () => void) => () => void;
+}
 export interface CursorOptions<T extends BaseItem, U = T, Async extends boolean = false> extends FindOptions<T, Async> {
     transform?: Transform<T, U>;
     bindEvents?: (requery: () => void) => () => void;
+    queryState?: QueryStateAccessor;
 }
 /**
  * Represents a cursor for querying and observing a filtered, sorted, and transformed
@@ -90,6 +107,31 @@ export default class Cursor<T extends BaseItem, U = T, Async extends boolean = f
      * @returns The total number of items in the result set.
      */
     count(): Async extends true ? Promise<number> : number;
+    /**
+     * Whether this cursor's query has yet to deliver a first result.
+     * ⚡️ this function is reactive!
+     *
+     * An asynchronous data adapter answers a newly registered query only after a
+     * round trip, and serves a neutral empty result until it does — which a
+     * consumer cannot otherwise tell apart from "there is nothing to show". This
+     * is that distinction, per query rather than per collection, so one screen
+     * waiting on its own data says nothing about any other query.
+     *
+     * Follows the usual `isLoading`/`isFetching` split: it reports "no result
+     * yet", not "an execution is in flight". A write that re-runs an
+     * already-settled query drives it through `'active'` again while this stays
+     * `false`, so a list does not fall back to a loading state every time one of
+     * its rows changes.
+     *
+     * A query that fails counts as settled — the `query.error` event on the
+     * collection is what surfaces the failure, and a loading state that never
+     * ends is the worse answer. Reading this registers the query if nothing else
+     * has, so it cannot wait on something nobody asked for. It is always `false`
+     * for an `{ async: true }` cursor, whose `fetch()` awaits the real result
+     * anyway, and for a data adapter that answers synchronously.
+     * @returns A boolean indicating whether the first result is still pending.
+     */
+    isLoading(): boolean;
     /**
      * Observes changes to the cursor's result set and triggers the specified callbacks
      * when items are added, removed, or updated. Supports reactivity and transformation.

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

@@ -79,7 +79,7 @@ class Cursor {
             return item;
         return this.options.transform(item);
     }
-    depend(changeEvents) {
+    depend(changeEvents, bindExtraNotifier) {
         if (this.options?.async)
             return;
         if (!isInReactiveScope(this.options.reactive)) {
@@ -124,6 +124,17 @@ class Cursor {
             this.options.reactive.onDispose(() => stop(), signal);
         }
         this.onCleanup(stop);
+        // A notifier that isn't driven by the result set itself — `isLoading()`
+        // needs to re-run its scope when the query settles, which is precisely
+        // the moment the result set may *not* have changed (an empty query
+        // completing produces no diff, so the observer above stays silent).
+        if (!bindExtraNotifier)
+            return;
+        const stopExtraNotifier = bindExtraNotifier(notify);
+        if (this.options.reactive.onDispose) {
+            this.options.reactive.onDispose(() => stopExtraNotifier(), signal);
+        }
+        this.onCleanup(stopExtraNotifier);
     }
     ensureObserver() {
         if (!this.observer) {
@@ -247,6 +258,37 @@ class Cursor {
             ? maybePromise.then(items => items.length)
             : maybePromise.length);
     }
+    /**
+     * Whether this cursor's query has yet to deliver a first result.
+     * ⚡️ this function is reactive!
+     *
+     * An asynchronous data adapter answers a newly registered query only after a
+     * round trip, and serves a neutral empty result until it does — which a
+     * consumer cannot otherwise tell apart from "there is nothing to show". This
+     * is that distinction, per query rather than per collection, so one screen
+     * waiting on its own data says nothing about any other query.
+     *
+     * Follows the usual `isLoading`/`isFetching` split: it reports "no result
+     * yet", not "an execution is in flight". A write that re-runs an
+     * already-settled query drives it through `'active'` again while this stays
+     * `false`, so a list does not fall back to a loading state every time one of
+     * its rows changes.
+     *
+     * A query that fails counts as settled — the `query.error` event on the
+     * collection is what surfaces the failure, and a loading state that never
+     * ends is the worse answer. Reading this registers the query if nothing else
+     * has, so it cannot wait on something nobody asked for. It is always `false`
+     * for an `{ async: true }` cursor, whose `fetch()` awaits the real result
+     * anyway, and for a data adapter that answers synchronously.
+     * @returns A boolean indicating whether the first result is still pending.
+     */
+    isLoading() {
+        const queryState = this.options.queryState;
+        if (!queryState || this.options.async)
+            return false;
+        this.depend({}, notify => queryState.onSettled(notify));
+        return !queryState.hasSettled();
+    }
     /**
      * Observes changes to the cursor's result set and triggers the specified callbacks
      * when items are added, removed, or updated. Supports reactivity and transformation.

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

@@ -8,7 +8,7 @@ import type StorageAdapter from '../types/StorageAdapter';
 import Cursor from './Cursor';
 import type { AsyncFindOptions, BaseItem, FindOptions, SyncFindOptions, Transform, TransformAll } from './types';
 export type { AnyFindOptions, AsyncFindOptions, BaseItem, Transform, TransformAll, SortSpecifier, FieldSpecifier, FindOptions, SyncFindOptions, } from './types';
-export type { CursorOptions } from './Cursor';
+export type { CursorOptions, QueryStateAccessor } from './Cursor';
 export type { ObserveCallbacks } from './Observer';
 export { default as createIndex } from '../createIndex';
 export interface CollectionOptions<T extends BaseItem<I>, I, E extends BaseItem = T, U = E> {
@@ -110,6 +110,7 @@ export default class Collection<T extends BaseItem<I> = BaseItem, I = any, E ext
     private postBatchCallbacks;
     private fieldTracking;
     private queryListenersMap;
+    private settledQueriesSet;
     /**
      * Initializes a new instance of the `Collection` class with optional configuration.
      * Sets up memory, persistence, reactivity, and indices as specified in the options.

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

@@ -102,6 +102,15 @@ class Collection extends EventEmitter_1.default {
     postBatchCallbacks = new Set();
     fieldTracking = false;
     queryListenersMap = new Map();
+    // Which registered queries have delivered an outcome at least once, backing
+    // `Cursor#isLoading()`. Kept here rather than on a cursor because a cursor is
+    // rebuilt on every reactive re-run, and rather than in the data adapters
+    // because deriving it from the state they already publish needs no change to
+    // the `CollectionBackend` contract. Keyed and dropped exactly like
+    // `queryListenersMap`, so a query that gets unregistered starts out pending
+    // again — which is correct, since the adapter re-executes it on the next
+    // registration.
+    settledQueriesSet = new Set();
     constructor(nameOrOptions, maybeDataAdapter, maybeOptions) {
         super();
         const name = typeof nameOrOptions === 'string'
@@ -310,6 +319,25 @@ class Collection extends EventEmitter_1.default {
             fieldTracking: this.fieldTracking,
             ...options,
             transform: this.transform.bind(this),
+            queryState: {
+                hasSettled: () => {
+                    if (this.settledQueriesSet.has((0, queryId_1.default)(selector, options)))
+                        return true;
+                    // An adapter that answers synchronously reports `'complete'` from
+                    // the start, so a cursor over one is never in a loading state.
+                    const state = this.backend.getQueryState(selector, options || {});
+                    return state === 'complete' || state === 'error';
+                },
+                // The latch is set by the very callback that notifies, so a cursor
+                // can never be woken to read a state that has not been recorded yet,
+                // whatever order the backend runs its subscribers in.
+                onSettled: callback => this.backend.onQueryStateChange(selector, options || {}, (state) => {
+                    if (state !== 'complete' && state !== 'error')
+                        return;
+                    this.settledQueriesSet.add((0, queryId_1.default)(selector, options));
+                    callback();
+                }),
+            },
             bindEvents: (requery) => {
                 const handleRequery = () => {
                     if (this.batchOperationInProgress) {
@@ -351,8 +379,10 @@ class Collection extends EventEmitter_1.default {
                         // Only unregister if this observer was the one that registered
                         // This prevents race conditions where a new observer registers
                         // before the old one's cleanup runs
-                        if (newListeners === 0 && didRegister)
+                        if (newListeners === 0 && didRegister) {
                             this.backend.unregisterQuery(selector, options || {});
+                            this.settledQueriesSet.delete((0, queryId_1.default)(selector, options));
+                        }
                         this.queryListeners({ selector, options }, newListeners);
                         queryStateChangeCleanup();
                         this.emit('observer.disposed', selector, options);

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

@@ -22,8 +22,28 @@ export default class WorkerDataAdapter implements DataAdapter {
     private collectionReady;
     private batchExecutionHelpers;
     private queries;
+    private pendingWrites;
+    private pendingWriteSeq;
     constructor(worker: WorkerDataAdapterEndpoint, options: WorkerDataAdapterOptions);
     private exec;
+    private observableItems;
+    private mergePendingWrites;
+    /**
+     * Registers a write's effect locally and notifies every active query it
+     * touches, then returns a function that drops it again once the write
+     * settles.
+     * @param collectionName - The collection the write targets.
+     * @param upserts - Items inserted or updated by the write.
+     * @param deletes - Ids removed by the write.
+     * @returns A function that drops the pending write and re-notifies.
+     */
+    private applyPendingWrite;
+    private notifyAffectedQueries;
+    private matchObservableItems;
+    private resolveUpdate;
+    private resolveRemoval;
+    private resolveReplacement;
+    private withPendingWrite;
     private enqueueBatched;
     private updateQuery;
     createCollectionBackend<T extends BaseItem<I>, I = any, E extends BaseItem = T, U = E>(collection: Collection<T, I, E, U>, indices: string[]): CollectionBackend<T, I>;

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

@@ -6,6 +6,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const queryId_1 = __importDefault(require("./utils/queryId"));
 const randomId_1 = __importDefault(require("./utils/randomId"));
 const batchOnNextTick_1 = __importDefault(require("./utils/batchOnNextTick"));
+const applyQueryOptions_1 = __importDefault(require("./utils/applyQueryOptions"));
+const match_1 = __importDefault(require("./utils/match"));
+const modify_1 = __importDefault(require("./utils/modify"));
+const deepClone_1 = __importDefault(require("./utils/deepClone"));
 class WorkerDataAdapter {
     worker;
     options;
@@ -16,6 +20,19 @@ class WorkerDataAdapter {
     collectionReady = new Map();
     batchExecutionHelpers = new Map();
     queries = {};
+    // Writes that have been issued but not yet confirmed by the worker. Their
+    // effect is layered on top of each active query's last authoritative result
+    // in `getQueryResult`, so a cursor reflects a write immediately instead of
+    // waiting out the postMessage → SQLite write → re-executed query →
+    // postMessage round trip. Deliberately scoped to items that active queries
+    // already hold: this adapter must not turn into a full in-memory mirror of
+    // the backing store, and anything no active query holds isn't observable
+    // anyway. Dropped again once the write settles — on success the worker's
+    // own `queryUpdate` has already landed (it is posted before the write's
+    // response, and message order is preserved), on failure dropping it is the
+    // rollback.
+    pendingWrites = new Map();
+    pendingWriteSeq = 0;
     constructor(worker, options) {
         this.worker = worker;
         this.options = options;
@@ -78,6 +95,117 @@ class WorkerDataAdapter {
             });
         });
     }
+    // The items an active query currently holds, deduplicated by id — the only
+    // items this adapter knows about, and the set a selector-based write can be
+    // resolved against locally.
+    observableItems(collectionName) {
+        const byId = new Map();
+        this.queries[collectionName]?.forEach((query) => {
+            this.mergePendingWrites(collectionName, query.items).forEach((item) => {
+                byId.set(item.id, item);
+            });
+        });
+        return [...byId.values()];
+    }
+    mergePendingWrites(collectionName, items) {
+        const pending = this.pendingWrites.get(collectionName);
+        if (!pending || pending.size === 0)
+            return items;
+        const merged = new Map(items.map(item => [item.id, item]));
+        [...pending.entries()]
+            .sort(([a], [b]) => a - b) // eslint-disable-line unicorn/no-array-sort -- unavailable on Hermes
+            .forEach(([, write]) => {
+            write.upserts.forEach((item, id) => merged.set(id, item));
+            write.deletes.forEach(id => merged.delete(id));
+        });
+        return [...merged.values()];
+    }
+    /**
+     * Registers a write's effect locally and notifies every active query it
+     * touches, then returns a function that drops it again once the write
+     * settles.
+     * @param collectionName - The collection the write targets.
+     * @param upserts - Items inserted or updated by the write.
+     * @param deletes - Ids removed by the write.
+     * @returns A function that drops the pending write and re-notifies.
+     */
+    applyPendingWrite(collectionName, upserts, deletes) {
+        if (upserts.length === 0 && deletes.length === 0)
+            return () => { };
+        const seq = this.pendingWriteSeq += 1;
+        const pending = this.pendingWrites.get(collectionName)
+            ?? new Map();
+        pending.set(seq, {
+            upserts: new Map(upserts.map(item => [item.id, item])),
+            deletes: new Set(deletes),
+        });
+        this.pendingWrites.set(collectionName, pending);
+        const affectedIds = new Set([...upserts.map(item => item.id), ...deletes]);
+        this.notifyAffectedQueries(collectionName, upserts, affectedIds);
+        return () => {
+            const current = this.pendingWrites.get(collectionName);
+            if (!current)
+                return;
+            current.delete(seq);
+            if (current.size === 0)
+                this.pendingWrites.delete(collectionName);
+            this.notifyAffectedQueries(collectionName, upserts, affectedIds);
+        };
+    }
+    // Re-runs the state-change callbacks of every query whose result the write
+    // can have changed — either because a written item matches its selector, or
+    // because it already held one of the affected items (an update that moves an
+    // item out of a query, or a removal).
+    notifyAffectedQueries(collectionName, upserts, affectedIds) {
+        this.queries[collectionName]?.forEach((query) => {
+            const wasHolding = query.items.some(item => affectedIds.has(item.id));
+            const nowMatches = upserts.some(item => query.selector != null
+                && (0, match_1.default)(item, query.selector));
+            if (!wasHolding && !nowMatches)
+                return;
+            query.stateChangeCallbacks.forEach(callback => callback(query.state));
+        });
+    }
+    matchObservableItems(collectionName, selector, onlyFirst) {
+        if (selector == null)
+            return [];
+        const matches = this.observableItems(collectionName).filter(item => (0, match_1.default)(item, selector));
+        return onlyFirst ? matches.slice(0, 1) : matches;
+    }
+    resolveUpdate(collectionName, selector, modifier, onlyFirst) {
+        const { $setOnInsert, ...restModifier } = modifier;
+        const upserts = [];
+        const deletes = [];
+        this.matchObservableItems(collectionName, selector, onlyFirst).forEach((item) => {
+            const modifiedItem = (0, modify_1.default)((0, deepClone_1.default)(item), restModifier);
+            upserts.push(modifiedItem);
+            if (modifiedItem.id !== item.id)
+                deletes.push(item.id);
+        });
+        return { upserts, deletes };
+    }
+    resolveRemoval(collectionName, selector, onlyFirst) {
+        return this.matchObservableItems(collectionName, selector, onlyFirst).map(item => item.id);
+    }
+    resolveReplacement(item, replacement) {
+        const modifiedItem = { ...replacement, id: replacement.id ?? item.id };
+        return {
+            upserts: [modifiedItem],
+            deletes: modifiedItem.id === item.id ? [] : [item.id],
+        };
+    }
+    // Makes a write's effect visible to active queries for the duration of the
+    // round trip, and drops it again once the worker has spoken — see
+    // `pendingWrites`.
+    async withPendingWrite(collectionName, delta, run) {
+        const dropPendingWrite = this.applyPendingWrite(collectionName, delta.upserts, delta.deletes);
+        try {
+            return await run();
+        }
+        finally {
+            dropPendingWrite();
+        }
+    }
     enqueueBatched(collectionName, method, args) {
         const helper = this.batchExecutionHelpers.get(collectionName);
         if (!helper)
@@ -92,6 +220,8 @@ class WorkerDataAdapter {
             return;
         const existing = collectionQueries.get(id);
         const newState = {
+            selector: query.selector,
+            options: query.options,
             state: 'active',
             error: null,
             items: [],
@@ -110,22 +240,25 @@ class WorkerDataAdapter {
         this.batchExecutionHelpers.set(collection.name, (0, batchOnNextTick_1.default)(async (method, args) => this.exec(method, collection.name, args)));
         return {
             insert: async (item) => {
-                return this.enqueueBatched(collection.name, 'insert', [item]);
+                return this.withPendingWrite(collection.name, { upserts: [item], deletes: [] }, () => this.enqueueBatched(collection.name, 'insert', [item]));
             },
             updateOne: async (selector, modifier) => {
-                return this.enqueueBatched(collection.name, 'updateOne', [selector, modifier]);
+                return this.withPendingWrite(collection.name, this.resolveUpdate(collection.name, selector, modifier, true), () => this.enqueueBatched(collection.name, 'updateOne', [selector, modifier]));
             },
             updateMany: async (selector, modifier) => {
-                return this.enqueueBatched(collection.name, 'updateMany', [selector, modifier]);
+                return this.withPendingWrite(collection.name, this.resolveUpdate(collection.name, selector, modifier, false), () => this.enqueueBatched(collection.name, 'updateMany', [selector, modifier]));
             },
             replaceOne: async (selector, replacement) => {
-                return this.enqueueBatched(collection.name, 'replaceOne', [selector, replacement]);
+                const [item] = this.matchObservableItems(collection.name, selector, true);
+                return this.withPendingWrite(collection.name, item == null
+                    ? { upserts: [], deletes: [] }
+                    : this.resolveReplacement(item, replacement), () => this.enqueueBatched(collection.name, 'replaceOne', [selector, replacement]));
             },
             removeOne: async (selector) => {
-                return this.enqueueBatched(collection.name, 'removeOne', [selector]);
+                return this.withPendingWrite(collection.name, { upserts: [], deletes: this.resolveRemoval(collection.name, selector, true) }, () => this.enqueueBatched(collection.name, 'removeOne', [selector]));
             },
             removeMany: async (selector) => {
-                return this.enqueueBatched(collection.name, 'removeMany', [selector]);
+                return this.withPendingWrite(collection.name, { upserts: [], deletes: this.resolveRemoval(collection.name, selector, false) }, () => this.enqueueBatched(collection.name, 'removeMany', [selector]));
             },
             // methods for registering and unregistering queries that will be called from the collection during find/findOne
             registerQuery: (selector, options) => {
@@ -176,7 +309,12 @@ class WorkerDataAdapter {
             },
             getQueryResult: (selector, options) => {
                 const query = this.queries[collection.name]?.get((0, queryId_1.default)(selector, options));
-                return query?.items || [];
+                if (!query)
+                    return [];
+                const pending = this.pendingWrites.get(collection.name);
+                if (!pending || pending.size === 0)
+                    return query.items;
+                return (0, applyQueryOptions_1.default)(this.mergePendingWrites(collection.name, query.items), selector, options);
             },
             onQueryStateChange: (selector, options, callback) => {
                 this.updateQuery(collection.name, { selector, options }, {

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

@@ -2,7 +2,7 @@ export type { default as ReactivityAdapter } from './types/ReactivityAdapter';
 export type { default as StorageAdapter, Changeset, } from './types/StorageAdapter';
 export type { default as Selector } from './types/Selector';
 export type { default as Modifier } from './types/Modifier';
-export type { BaseItem, ObserveCallbacks, CursorOptions, Transform, TransformAll, SortSpecifier, FieldSpecifier, AnyFindOptions, AsyncFindOptions, FindOptions, SyncFindOptions, CollectionOptions, } from './Collection';
+export type { BaseItem, ObserveCallbacks, CursorOptions, Transform, TransformAll, SortSpecifier, FieldSpecifier, AnyFindOptions, AsyncFindOptions, FindOptions, SyncFindOptions, CollectionOptions, QueryStateAccessor, } from './Collection';
 export type { default as DataAdapter } from './DataAdapter';
 export { default as Cursor } from './Collection/Cursor';
 export { default as Collection } from './Collection';

package/dist/base/core/src/utils/applyQueryOptions.d.ts

@@ -0,0 +1,15 @@
+import type { QueryOptions } from '../DataAdapter';
+import type Selector from '../types/Selector';
+import type { BaseItem } from '../Collection/types';
+/**
+ * Filters, sorts, paginates and projects a plain in-memory array the same way
+ * DefaultDataAdapter and WorkerDataAdapterHost apply a selector/QueryOptions
+ * pair to their stored items. Used to re-derive a query's result locally after
+ * a write, without asking the backing store again.
+ * @template T - The type of the items.
+ * @param items - The items to filter, sort, paginate and project.
+ * @param selector - The selector to match items against.
+ * @param options - Sort, skip, limit and field projection options.
+ * @returns The resulting items.
+ */
+export default function applyQueryOptions<T extends BaseItem>(items: T[], selector: Selector<T>, options?: QueryOptions<T>): T[];

package/dist/base/core/src/utils/applyQueryOptions.js

@@ -0,0 +1,36 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = applyQueryOptions;
+const match_1 = __importDefault(require("./match"));
+const sortItems_1 = __importDefault(require("./sortItems"));
+const project_1 = __importDefault(require("./project"));
+/**
+ * Filters, sorts, paginates and projects a plain in-memory array the same way
+ * DefaultDataAdapter and WorkerDataAdapterHost apply a selector/QueryOptions
+ * pair to their stored items. Used to re-derive a query's result locally after
+ * a write, without asking the backing store again.
+ * @template T - The type of the items.
+ * @param items - The items to filter, sort, paginate and project.
+ * @param selector - The selector to match items against.
+ * @param options - Sort, skip, limit and field projection options.
+ * @returns The resulting items.
+ */
+function applyQueryOptions(items, selector, options) {
+    const matched = selector == null ? [] : items.filter(item => (0, match_1.default)(item, selector));
+    const { sort, skip, limit, fields } = options || {};
+    const sorted = sort ? (0, sortItems_1.default)(matched, sort) : matched;
+    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),
+        };
+    });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@signaldb/svelte",
   "type": "module",
-  "version": "2.0.0-beta.11",
+  "version": "2.0.0-beta.13",
   "scripts": {
     "build": "tsc -d --noEmit false",
     "analyze-bundle": "bundle-analyzer ./dist --upload-token=$BUNDLE_ANALYZER_UPLOAD_TOKEN --bundle-name=@signaldb/svelte",