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

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

@@ -0,0 +1,761 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createIndex = void 0;
+const EventEmitter_1 = __importDefault(require("../utils/EventEmitter"));
+const createSignal_1 = __importDefault(require("../utils/createSignal"));
+const randomId_1 = __importDefault(require("../utils/randomId"));
+const DefaultDataAdapter_1 = __importDefault(require("../DefaultDataAdapter"));
+const modify_1 = __importDefault(require("../utils/modify"));
+const deepClone_1 = __importDefault(require("../utils/deepClone"));
+const queryId_1 = __importDefault(require("../utils/queryId"));
+const Cursor_1 = __importDefault(require("./Cursor"));
+var createIndex_1 = require("../createIndex");
+Object.defineProperty(exports, "createIndex", { enumerable: true, get: function () { return __importDefault(createIndex_1).default; } });
+/**
+ * Represents a collection of data items with support for in-memory operations,
+ * persistence, reactivity, and event-based notifications. The collection provides
+ * CRUD operations, observer patterns, and batch operations.
+ * @template T - The type of the items stored in the collection.
+ * @template I - The type of the unique identifier for the items.
+ * @template U - The transformed item type after applying transformations (default is T).
+ */
+class Collection extends EventEmitter_1.default {
+    static collections = [];
+    static debugMode = false;
+    static batchOperationInProgress = false;
+    static fieldTracking = false;
+    static onCreationCallbacks = [];
+    static onDisposeCallbacks = [];
+    // How many rows a live query may hold before it is reported as expensive.
+    // `null` disables the check, which is the default: it costs a stack capture
+    // per registered query, which is worth paying while developing and not in
+    // production. `enableDebugMode()` turns it on.
+    static largeQueryWarningThreshold = null;
+    static reportedLargeQueries = 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);
+    }
+    static onDispose(callback) {
+        Collection.onDisposeCallbacks.push(callback);
+    }
+    /**
+     * Enables debug mode for all collections.
+     */
+    static enableDebugMode = () => {
+        Collection.debugMode = true;
+        // A query large enough to matter is exactly the kind of thing debug mode
+        // exists to surface, and it is invisible otherwise. Call
+        // `reportLargeQueries()` afterwards to pick a different threshold or turn
+        // it off again.
+        if (Collection.largeQueryWarningThreshold == null)
+            Collection.reportLargeQueries(500);
+        Collection.collections.forEach((collection) => {
+            collection.setDebugMode(true);
+        });
+    };
+    /**
+     * Enables field tracking for all collections.
+     * @param enable - A boolean indicating whether to enable field tracking.
+     */
+    static setFieldTracking = (enable) => {
+        Collection.fieldTracking = enable;
+        Collection.collections.forEach((collection) => {
+            collection.setFieldTracking(enable);
+        });
+    };
+    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;
+        // Only a batch that really covers every collection may claim the global
+        // flag; a scoped one must not make unrelated collections report themselves
+        // as batching through `isBatchOperationInProgress()`.
+        if (!scoped)
+            Collection.batchOperationInProgress = true;
+        const execute = () => collections.reduce((memo, collection) => () => {
+            return collection.batch(memo);
+        }, callback)();
+        const afterBatch = () => {
+            if (!scoped)
+                Collection.batchOperationInProgress = false;
+        };
+        let maybePromise;
+        try {
+            maybePromise = execute();
+        }
+        catch (error) {
+            // A synchronously throwing callback must not leave the batch flag
+            // stuck at `true` — that would defer every requery forever (see the
+            // rejection branch below).
+            afterBatch();
+            throw error;
+        }
+        if (maybePromise && typeof maybePromise.then === 'function') {
+            return maybePromise
+                .then(() => afterBatch(), (error) => {
+                // Rejections need the same cleanup as fulfillment — otherwise
+                // `batchOperationInProgress` stays `true` and all deferred
+                // requeries are never flushed, silently freezing reactivity.
+                afterBatch();
+                throw error;
+            });
+        }
+        else {
+            afterBatch();
+        }
+    }
+    name;
+    backend;
+    options;
+    isPullingSignal;
+    isPushingSignal;
+    readySignal;
+    debugMode;
+    batchOperationInProgress = false;
+    isDisposed = false;
+    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'
+            ? nameOrOptions
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
+            : nameOrOptions?.name || `${this.constructor.name}-${(0, randomId_1.default)()}`;
+        const options = typeof nameOrOptions === 'string'
+            ? maybeOptions || {}
+            : nameOrOptions || {};
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
+        const persistence = options.persistence;
+        const dataAdapter = maybeDataAdapter || new DefaultDataAdapter_1.default({
+            ...persistence ? { storage: () => persistence } : {},
+        });
+        Collection.collections.push(this);
+        this.name = name;
+        this.options = { ...options };
+        this.fieldTracking = this.options.fieldTracking ?? Collection.fieldTracking;
+        this.debugMode = this.options.enableDebugMode ?? Collection.debugMode;
+        this.isPullingSignal = (0, createSignal_1.default)(this.options.reactivity, false);
+        this.isPushingSignal = (0, createSignal_1.default)(this.options.reactivity, false);
+        this.readySignal = (0, createSignal_1.default)(this.options.reactivity, false);
+        this.backend = dataAdapter.createCollectionBackend(this, this.options.indices ?? []);
+        void this.backend.isReady()
+            .then(() => {
+            this.readySignal.set(true);
+        })
+            .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}:${(0, queryId_1.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);
+        // The selector's *keys*, never its values: the shape is what identifies the
+        // problem — an empty one means the query holds the whole collection — and
+        // the values would put user data into a log.
+        const keys = selector && typeof selector === 'object' ? Object.keys(selector) : [];
+        // eslint-disable-next-line no-console
+        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;
+    }
+    /**
+     * Checks whether the collection is currently performing a pull operation
+     * ⚡️ this function is reactive!
+     * (loading data from the persistence adapter).
+     * @returns A boolean indicating if the collection is in the process of pulling data.
+     */
+    isPulling() {
+        return this.isPullingSignal.get() ?? false;
+    }
+    /**
+     * Checks whether the collection is currently performing a push operation
+     * ⚡️ this function is reactive!
+     * (saving data to the persistence adapter).
+     * @returns A boolean indicating if the collection is in the process of pushing data.
+     */
+    isPushing() {
+        return this.isPushingSignal.get() ?? false;
+    }
+    /**
+     * Checks whether the collection is currently performing either a pull or push operation,
+     * ⚡️ this function is reactive!
+     * indicating that it is loading or saving data.
+     * @returns A boolean indicating if the collection is in the process of loading or saving data.
+     */
+    isLoading() {
+        const isPulling = this.isPulling();
+        const isPushing = this.isPushing();
+        return isPulling || isPushing;
+    }
+    /**
+     * Retrieves the current debug mode status of the collection.
+     * @returns A boolean indicating whether debug mode is enabled for the collection.
+     */
+    getDebugMode() {
+        return this.debugMode;
+    }
+    /**
+     * Enables or disables debug mode for the collection.
+     * When debug mode is enabled, additional debugging information and events are emitted.
+     * @param enable - A boolean indicating whether to enable (`true`) or disable (`false`) debug mode.
+     */
+    setDebugMode(enable) {
+        this.debugMode = enable;
+    }
+    /**
+     * Enables or disables field tracking for the collection.
+     * @param enable - A boolean indicating whether to enable (`true`) or disable (`false`) field tracking.
+     */
+    setFieldTracking(enable) {
+        this.fieldTracking = enable;
+    }
+    /**
+     * Resolves when the persistence adapter finished initializing
+     * and the collection is ready to be used.
+     * @returns A promise that resolves when the collection is ready.
+     * @example
+     * ```ts
+     * const collection = new Collection({
+     *   persistence: // ...
+     * })
+     * await collection.isReady()
+     *
+     * collection.insert({ name: 'Item 1' })
+     */
+    async ready() {
+        return this.backend.isReady();
+    }
+    /**
+     * Checks if the collection is ready.
+     * ⚡️ this function is reactive!
+     * @returns A boolean indicating whether the collection is ready.
+     */
+    isReady() {
+        return this.readySignal.get() ?? false;
+    }
+    profile(fn, measureFunction) {
+        if (!this.debugMode)
+            return fn();
+        const startTime = performance.now();
+        const handleProfileEnd = (result) => {
+            const endTime = performance.now();
+            measureFunction(endTime - startTime);
+            return result;
+        };
+        const maybePromise = fn();
+        return maybePromise instanceof Promise
+            ? maybePromise.then(handleProfileEnd)
+            : handleProfileEnd(maybePromise);
+    }
+    executeInDebugMode(fn) {
+        if (!this.debugMode)
+            return;
+        // eslint-disable-next-line unicorn/error-message
+        const callstack = new Error().stack || '';
+        fn(callstack);
+    }
+    transform(item) {
+        if (!this.options.transform)
+            return item;
+        return this.options.transform(item);
+    }
+    transformAll(items, fields) {
+        if (!this.options.transformAll)
+            return items;
+        return this.options.transformAll((0, deepClone_1.default)(items), fields);
+    }
+    getItem(selector, options) {
+        const itemsOrPromise = this.getItems(selector, { ...options, limit: 1 });
+        if (itemsOrPromise instanceof Promise) {
+            return itemsOrPromise.then((items) => {
+                return items[0] || undefined;
+            });
+        }
+        return itemsOrPromise[0];
+    }
+    getItems(selector, options) {
+        this.emit('getItems', selector);
+        return this.profile(() => {
+            if (!options?.async)
+                return this.backend.getQueryResult(selector, options);
+            this.isPullingSignal.set(true);
+            return this.backend.executeQuery(selector, options)
+                .finally(() => {
+                this.isPullingSignal.set(false);
+            });
+        }, measuredTime => this.executeInDebugMode(callstack => this.emit('_debug.getItems', callstack, selector, measuredTime)));
+    }
+    async withPushState(asyncFunction) {
+        this.isPushingSignal.set(true);
+        try {
+            return await asyncFunction();
+        }
+        finally {
+            this.isPushingSignal.set(false);
+        }
+    }
+    queryListeners(query, listeners) {
+        const id = (0, queryId_1.default)(query.selector, query.options);
+        if (listeners != null) {
+            return this.queryListenersMap.set(id, listeners);
+        }
+        return this.queryListenersMap.get(id) ?? 0;
+    }
+    /**
+     * Disposes the collection, unregisters persistence adapters, clears memory, and
+     * cleans up all resources used by the collection.
+     * @returns A promise that resolves when the collection is disposed.
+     */
+    async dispose() {
+        await this.backend.dispose();
+        this.isDisposed = true;
+        this.removeAllListeners();
+        Collection.collections = Collection.collections.filter(collection => collection !== this);
+        Collection.onDisposeCallbacks.forEach(callback => callback(this));
+    }
+    find(selector = {}, options) {
+        if (this.isDisposed)
+            throw new Error('Collection is disposed');
+        if (selector !== undefined && (!selector || typeof selector !== 'object'))
+            throw new Error('Invalid selector');
+        const getTransformedItems = () => {
+            const itemsOrPromise = this.getItems(selector, options || {});
+            if (itemsOrPromise instanceof Promise) {
+                return itemsOrPromise.then((items) => {
+                    return this.transformAll(items, options?.fields);
+                });
+            }
+            const items = itemsOrPromise;
+            return this.transformAll(items, options?.fields);
+        };
+        const cursor = new Cursor_1.default(getTransformedItems, {
+            reactive: this.options.reactivity,
+            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, applyDelta) => {
+                const handleRequery = () => {
+                    if (this.batchOperationInProgress) {
+                        this.postBatchCallbacks.add(requery);
+                        return;
+                    }
+                    requery();
+                };
+                // A `transformAll` sits between the backend's result and what the cursor holds, and it
+                // is free to produce anything at all — so a delta describing the backend's result says
+                // nothing about the cursor's. Those collections keep comparing.
+                const canApplyDeltas = !this.options.transformAll && !options?.async;
+                // register query if not yet registered
+                const listeners = this.queryListeners({ selector, options });
+                const didRegister = listeners === 0;
+                if (didRegister)
+                    this.backend.registerQuery(selector, options || {});
+                this.queryListeners({ selector, options }, listeners + 1);
+                // Captured at registration, not at completion: by the time the result
+                // arrives the stack is the adapter's, and the only useful thing to
+                // report is where the query was asked for.
+                const registrationStack = didRegister && Collection.largeQueryWarningThreshold != null
+                    ? new Error('query registered here').stack
+                    : undefined;
+                // A synchronous adapter already holds the result here and never
+                // reports `'complete'`, so the check has to happen at both points.
+                // Reporting is once per query, which makes the overlap harmless.
+                if (didRegister)
+                    this.reportIfLargeQuery(selector, options, registrationStack);
+                const queryStateChangeCleanup = this.backend.onQueryStateChange(selector, options || {}, (state, delta) => {
+                    // A failed query never reaches `'complete'`, so the cursor keeps
+                    // serving its neutral empty value — indistinguishable from "no
+                    // data" for anyone reading it. Surfacing the failure as an event
+                    // is the only way a consumer can tell the difference. Requerying
+                    // here would be pointless (the backend result is still empty)
+                    // and risks a loop, so it deliberately does not.
+                    if (state === 'error') {
+                        const queryError = this.backend.getQueryError(selector, options || {})
+                            || new Error(`Query on "${this.name}" failed`);
+                        this.emit('query.error', queryError, selector, options);
+                        return;
+                    }
+                    if (state !== 'complete')
+                        return;
+                    this.reportIfLargeQuery(selector, options, registrationStack);
+                    // Inside a batch the update is deferred to the end of it, by which point this delta
+                    // is one of several and no longer describes the whole change — so the batch always
+                    // ends in a comparison.
+                    if (delta != null && canApplyDeltas && !this.batchOperationInProgress) {
+                        applyDelta(delta);
+                        return;
+                    }
+                    handleRequery();
+                });
+                this.emit('observer.created', selector, options);
+                return () => {
+                    // Use queueMicrotask instead of setTimeout to avoid race conditions
+                    // while still allowing batching of quick register/unregister calls
+                    queueMicrotask(() => {
+                        // unregister query if no more listeners
+                        const newListeners = Math.max(0, this.queryListeners({ selector, options }) - 1);
+                        // The count decides, and only the count. Asking additionally whether *this*
+                        // observer was the one that registered leaks the query permanently: a rerun that
+                        // creates its replacement before the old one's cleanup runs — which the microtask
+                        // above deliberately allows — hands the count to an observer for which
+                        // `didRegister` is false, and when that one is disposed the count reaches zero with
+                        // nobody left who is allowed to act on it. The backend keeps the query registered
+                        // and maintains its result on every write for the rest of the session, while
+                        // `queryListeners` reads zero, so the next observer registers it a second time and
+                        // is answered with the whole result again.
+                        //
+                        // The race that guard was written for is already covered here: an observer that
+                        // registered in the meantime has incremented the count, so `newListeners` is not
+                        // zero and nothing is unregistered.
+                        if (newListeners === 0) {
+                            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);
+                    });
+                };
+            },
+        });
+        this.emit('find', selector, options, cursor);
+        this.executeInDebugMode(callstack => this.emit('_debug.find', callstack, selector, options, cursor));
+        return cursor;
+    }
+    findOne(selector, options) {
+        if (this.isDisposed)
+            throw new Error('Collection is disposed');
+        const cursor = this.find(selector, {
+            limit: 1,
+            ...options,
+        });
+        const handleItems = (items) => {
+            const returnValue = items[0] || undefined;
+            this.emit('findOne', selector, options, returnValue);
+            this.executeInDebugMode(callstack => this.emit('_debug.findOne', callstack, selector, options, returnValue));
+            return returnValue;
+        };
+        const maybePromise = cursor.fetch();
+        return (maybePromise instanceof Promise
+            ? maybePromise.then(handleItems)
+            : handleItems(maybePromise));
+    }
+    batch(callback) {
+        if (this.batchOperationInProgress)
+            return callback();
+        this.batchOperationInProgress = true;
+        const afterBatch = () => {
+            this.batchOperationInProgress = false;
+            this.postBatchCallbacks.forEach(callback_ => callback_());
+            this.postBatchCallbacks.clear();
+        };
+        let maybePromise;
+        try {
+            maybePromise = callback();
+        }
+        catch (error) {
+            // A synchronously throwing callback must not leave the batch flag
+            // stuck at `true` — that would defer every requery forever (see the
+            // rejection branch below).
+            afterBatch();
+            throw error;
+        }
+        if (maybePromise && typeof maybePromise.then === 'function') {
+            return maybePromise.then(() => afterBatch(), (error) => {
+                // Rejections need the same cleanup as fulfillment — otherwise
+                // `batchOperationInProgress` stays `true`, deferred post-batch
+                // callbacks (e.g. reactive requeries) are never flushed and
+                // reactivity silently freezes for the rest of the session.
+                afterBatch();
+                throw error;
+            });
+        }
+        else {
+            afterBatch();
+        }
+    }
+    onPostBatch(callback) {
+        if (this.isDisposed)
+            throw new Error('Collection is disposed');
+        if (this.batchOperationInProgress) {
+            this.postBatchCallbacks.add(callback);
+            return;
+        }
+        return callback();
+    }
+    /**
+     * Inserts a single item into the collection. Generates a unique ID if not provided.
+     * @param item - The item to insert.
+     * @returns The ID of the inserted item.
+     * @throws {Error} If the collection is disposed or the item has an invalid ID.
+     */
+    async insert(item) {
+        if (this.isDisposed)
+            throw new Error('Collection is disposed');
+        if (!item)
+            throw new Error('Invalid item');
+        const primaryKeyGenerator = this.options.primaryKeyGenerator ?? randomId_1.default;
+        const itemWithId = {
+            id: primaryKeyGenerator(item),
+            ...item,
+        };
+        this.emit('validate', itemWithId);
+        const newItem = await this.withPushState(() => this.backend.insert(itemWithId));
+        this.emit('added', newItem);
+        this.emit('insert', newItem);
+        this.executeInDebugMode(callstack => this.emit('_debug.insert', callstack, newItem));
+        return newItem.id;
+    }
+    /**
+     * Inserts multiple items into the collection. Generates unique IDs for items if not provided.
+     * @param items - The items to insert.
+     * @returns An array of IDs of the inserted items.
+     * @throws {Error} If the collection is disposed or the items are invalid.
+     */
+    async insertMany(items) {
+        if (this.isDisposed)
+            throw new Error('Collection is disposed');
+        if (!items)
+            throw new Error('Invalid items');
+        if (items.length === 0)
+            return [];
+        const ids = [];
+        await this.batch(async () => {
+            await Promise.all(items.map(async (item) => {
+                ids.push(await this.insert(item));
+            }));
+        });
+        return ids;
+    }
+    /**
+     * Updates a single item in the collection that matches the given selector.
+     * @param selector - The criteria to select the item to update.
+     * @param modifier - The modifications to apply to the item.
+     * @param [options] - Optional settings for the update operation.
+     * @param [options.upsert] - If `true`, creates a new item if no item matches the selector.
+     * @returns The number of items updated (0 or 1).
+     * @throws {Error} If the collection is disposed or invalid arguments are provided.
+     */
+    async updateOne(selector, modifier, options) {
+        if (this.isDisposed)
+            throw new Error('Collection is disposed');
+        if (!selector)
+            throw new Error('Invalid selector');
+        if (!modifier)
+            throw new Error('Invalid modifier');
+        const { $setOnInsert, ...restModifier } = modifier;
+        // Reading the item back before writing it is worth a round trip to the data layer only when
+        // something is waiting to inspect it: a validator gets to refuse the write, and it can only do
+        // that beforehand. Otherwise the backend's own answer says everything there is to know — what
+        // it returns is what changed, and an empty answer is what turns an upsert into an insert.
+        if (this.listenerCount('validate') > 0) {
+            const item = await this.getItem(selector, { async: true });
+            if (item != null)
+                this.emit('validate', (0, modify_1.default)((0, deepClone_1.default)(item), restModifier));
+        }
+        const changes = await this.withPushState(() => this.backend.updateOne(selector, modifier));
+        if (changes.length === 0) {
+            if (!options?.upsert)
+                return 0; // no item found, and upsert is not enabled
+            const newItem = (0, modify_1.default)({}, {
+                ...restModifier,
+                $set: {
+                    ...$setOnInsert,
+                    ...restModifier.$set,
+                },
+            });
+            await this.insert(newItem);
+            return 1;
+        }
+        changes.forEach(item => this.emit('changed', item, restModifier));
+        this.emit('updateOne', selector, modifier);
+        this.executeInDebugMode(callstack => this.emit('_debug.updateOne', callstack, selector, modifier));
+        return changes.length;
+    }
+    /**
+     * Updates multiple items in the collection that match the given selector.
+     * @param selector - The criteria to select the items to update.
+     * @param modifier - The modifications to apply to the items.
+     * @param [options] - Optional settings for the update operation.
+     * @param [options.upsert] - If `true`, creates new items if no items match the selector.
+     * @returns The number of items updated.
+     * @throws {Error} If the collection is disposed or invalid arguments are provided.
+     */
+    async updateMany(selector, modifier, options) {
+        if (this.isDisposed)
+            throw new Error('Collection is disposed');
+        if (!selector)
+            throw new Error('Invalid selector');
+        if (!modifier)
+            throw new Error('Invalid modifier');
+        const { $setOnInsert, ...restModifier } = modifier;
+        // See `updateOne`: the items are only fetched up front for the sake of a validator.
+        if (this.listenerCount('validate') > 0) {
+            const items = await this.getItems(selector, { async: true });
+            items.forEach((item) => {
+                this.emit('validate', (0, modify_1.default)((0, deepClone_1.default)(item), restModifier));
+            });
+        }
+        const changes = await this.withPushState(() => this.backend.updateMany(selector, modifier));
+        if (changes.length === 0) {
+            if (!options?.upsert)
+                return 0; // no items found, and upsert is not enabled
+            const newItem = (0, modify_1.default)({}, {
+                ...restModifier,
+                $set: {
+                    ...$setOnInsert,
+                    ...restModifier.$set,
+                },
+            });
+            await this.insert(newItem);
+            return 1;
+        }
+        changes.forEach((item) => {
+            this.emit('changed', item, restModifier);
+        });
+        this.emit('updateMany', selector, modifier);
+        this.executeInDebugMode(callstack => this.emit('_debug.updateMany', callstack, selector, modifier));
+        return changes.length;
+    }
+    /**
+     * Replaces a single item in the collection that matches the given selector.
+     * @param selector - The criteria to select the item to replace.
+     * @param replacement - The item to replace the selected item with.
+     * @param [options] - Optional settings for the replace operation.
+     * @param [options.upsert] - If `true`, creates a new item if no item matches the selector.
+     * @returns The number of items replaced (0 or 1).
+     * @throws {Error} If the collection is disposed or invalid arguments are provided.
+     */
+    async replaceOne(selector, replacement, options) {
+        if (this.isDisposed)
+            throw new Error('Collection is disposed');
+        if (!selector)
+            throw new Error('Invalid selector');
+        // See `updateOne`: the item is only fetched up front for the sake of a validator.
+        if (this.listenerCount('validate') > 0) {
+            const item = await this.getItem(selector, { async: true });
+            if (item != null)
+                this.emit('validate', { id: item.id, ...replacement });
+        }
+        const changes = await this.withPushState(() => this.backend.replaceOne(selector, replacement));
+        if (changes.length === 0) {
+            if (!options?.upsert)
+                return 0; // no item found, and upsert is not enabled
+            await this.insert(replacement);
+            return 1;
+        }
+        changes.forEach(item => this.emit('changed', item, replacement));
+        this.emit('replaceOne', selector, replacement);
+        this.executeInDebugMode(callstack => this.emit('_debug.replaceOne', callstack, selector, replacement));
+        return changes.length;
+    }
+    /**
+     * Removes a single item from the collection that matches the given selector.
+     * @param selector - The criteria to select the item to remove.
+     * @returns The number of items removed (0 or 1).
+     * @throws {Error} If the collection is disposed or invalid arguments are provided.
+     */
+    async removeOne(selector) {
+        if (this.isDisposed)
+            throw new Error('Collection is disposed');
+        if (!selector)
+            throw new Error('Invalid selector');
+        const removedItems = await this.withPushState(() => this.backend.removeOne(selector));
+        this.emit('removed', removedItems[0]);
+        this.emit('removeOne', selector);
+        this.executeInDebugMode(callstack => this.emit('_debug.removeOne', callstack, selector));
+        return removedItems.length;
+    }
+    /**
+     * Removes multiple items from the collection that match the given selector.
+     * @param selector - The criteria to select the items to remove.
+     * @returns The number of items removed.
+     * @throws {Error} If the collection is disposed or invalid arguments are provided.
+     */
+    async removeMany(selector) {
+        if (this.isDisposed)
+            throw new Error('Collection is disposed');
+        if (!selector)
+            throw new Error('Invalid selector');
+        const removedItems = await this.withPushState(() => this.backend.removeMany(selector));
+        removedItems.forEach((item) => {
+            this.emit('removed', item);
+        });
+        this.emit('removeMany', selector);
+        this.executeInDebugMode(callstack => this.emit('_debug.removeMany', callstack, selector));
+        return removedItems.length;
+    }
+}
+exports.default = Collection;