realm/dist/Collection.js

Realm by MongoDB is an offline-first mobile database: an alternative to SQLite and key-value stores

"use strict";
////////////////////////////////////////////////////////////////////////////
//
// Copyright 2022 Realm Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
////////////////////////////////////////////////////////////////////////////
Object.defineProperty(exports, "__esModule", { value: true });
exports.Collection = void 0;
const internal_1 = require("./internal");
/**
 * Abstract base class containing methods shared by Realm {@link List}, {@link Dictionary} and {@link Results}.
 *
 * A {@link Collection} always reflect the current state of the Realm. The one exception to this is
 * when using `for...in` or `for...of` enumeration, which will always enumerate over the
 * objects which matched the query when the enumeration is begun, even if some of them are
 * deleted or modified to be excluded by the filter during the enumeration.
 * @since 0.11.0
 */
class Collection {
    /** @internal */
    listeners;
    /** @internal */
    constructor(addListener) {
        if (arguments.length === 0) {
            throw new internal_1.IllegalConstructorError("Collection");
        }
        this.listeners = new internal_1.Listeners({
            add: addListener,
            remove(token) {
                token.unregister();
            },
        });
        // Make the internal properties non-enumerable
        Object.defineProperty(this, "listeners", {
            enumerable: false,
            configurable: false,
            writable: false,
        });
    }
    /**
     * Add a listener `callback` which will be called when a **live** collection instance changes.
     * @param callback - A function to be called when changes occur.
     * @param callback.collection - The collection instance that changed,
     * @param callback.changes - An object with information about the changes.
     * @param callback.changes.insertions - The indices in the collection where objects were inserted.
     * @param callback.changes.newModifications - The indices in the collection where objects were modified.
     * @param callback.changes.oldModifications - The indices in the collection where objects were modified.
     * @param callback.changes.deletions - The indices in the collection where objects were deleted.
     * @param keyPaths - Indicates a lower bound on the changes relevant for the listener. This is a lower bound, since if multiple listeners are added (each with their own `keyPaths`) the union of these key-paths will determine the changes that are considered relevant for all listeners registered on the collection. In other words: A listener might fire more than the key-paths specify, if other listeners with different key-paths are present.
     * @note `deletions and `oldModifications` report the indices in the collection before the change happened,
     * while `insertions` and `newModifications` report the indices into the new version of the collection.
     * @throws A {@link TypeAssertionError} if `callback` is not a function.
     * @example
     * wines.addListener((collection, changes) => {
     *  // collection === wines
     *  console.log(`${changes.insertions.length} insertions`);
     *  console.log(`${changes.oldModifications.length} oldModifications`);
     *  console.log(`${changes.newModifications.length} newModifications`);
     *  console.log(`${changes.deletions.length} deletions`);
     *  console.log(`new size of collection: ${collection.length}`);
     * });
     * @example
     * wines.addListener((collection, changes) => {
     *  console.log("A wine's brand might have changed");
     * }, ["brand"]);
     * @note Adding the listener is an asynchronous operation, so the callback is invoked the first time to notify the caller when the listener has been added.
     * Thus, when the callback is invoked the first time it will contain empty arrays for each property in the `changes` object.
     */
    addListener(callback, keyPaths) {
        internal_1.assert.function(callback, "callback");
        this.listeners.add(callback, typeof keyPaths === "string" ? [keyPaths] : keyPaths);
    }
    /**
     * Remove the listener `callback` from the collection instance.
     * @param callback - Callback function that was previously
     *   added as a listener through the {@link Collection.addListener} method.
     * @throws a {@link TypeAssertionError} If `callback` is not a function.
     */
    removeListener(callback) {
        internal_1.assert.function(callback, "callback");
        this.listeners.remove(callback);
    }
    /**
     * Remove all `callback` listeners from the collection instance.
     */
    removeAllListeners() {
        this.listeners.removeAll();
    }
}
exports.Collection = Collection;
//# sourceMappingURL=Collection.js.map