@verdant-web/store 3.3.1 → 3.4.0-next.0

package/dist/cjs/entities/Entity.js

@@ -1,711 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Entity = void 0;
-const common_1 = require("@verdant-web/common");
-const utils_js_1 = require("../files/utils.js");
-const index_js_1 = require("../index.js");
-const EntityCache_js_1 = require("./EntityCache.js");
-class Entity extends common_1.EventSubscriber {
-    constructor({ oid, schema, entityFamily: childCache, parent, ctx, metadataFamily, readonlyKeys, files, patchCreator, events, }) {
-        super();
-        this.fieldPath = [];
-        // an internal representation of this Entity.
-        // if present, this is the cached, known value. If null,
-        // the entity is deleted. If undefined, we need to recompute
-        // the view.
-        this._viewData = undefined;
-        this.validationError = undefined;
-        this.cachedDeepUpdatedAt = null;
-        // only used for root entities to track delete/restore state.
-        this.wasDeletedLastChange = false;
-        this.cachedView = undefined;
-        this.onAdd = (_store, data) => {
-            if (data.oid === this.oid) {
-                this.addConfirmedData(data);
-            }
-        };
-        this.onReplace = (_store, data) => {
-            if (data.oid === this.oid) {
-                this.replaceAllData(data);
-            }
-        };
-        this.onResetAll = () => {
-            this.resetAllData();
-        };
-        this.childIsNull = (child) => {
-            if (child instanceof Entity) {
-                const childView = child.view;
-                return childView === null || childView === undefined;
-            }
-            return child === null || child === undefined;
-        };
-        /**
-         * Pruning - when entities have invalid children, we 'prune' that
-         * data up to the nearest prunable point - a nullable field,
-         * or a list.
-         */
-        this.validate = (0, common_1.memoByKeys)(() => {
-            var _a;
-            this.validationError =
-                (_a = (0, common_1.validateEntityField)({
-                    field: this.schema,
-                    value: this.rawView,
-                    fieldPath: this.fieldPath,
-                    depth: 1,
-                })) !== null && _a !== void 0 ? _a : undefined;
-            return this.validationError;
-        }, () => [this.viewData]);
-        this.viewWithMappedChildren = (mapper) => {
-            const view = this.view;
-            if (!view) {
-                return null;
-            }
-            if (Array.isArray(view)) {
-                const mapped = view.map((value) => {
-                    if (value instanceof Entity || value instanceof index_js_1.EntityFile) {
-                        return mapper(value);
-                    }
-                    else {
-                        return value;
-                    }
-                });
-                (0, common_1.assignOid)(mapped, this.oid);
-                return mapped;
-            }
-            else {
-                const mapped = Object.entries(view).reduce((acc, [key, value]) => {
-                    if (value instanceof Entity || value instanceof index_js_1.EntityFile) {
-                        acc[key] = mapper(value);
-                    }
-                    else {
-                        acc[key] = value;
-                    }
-                    return acc;
-                }, {});
-                (0, common_1.assignOid)(mapped, this.oid);
-                return mapped;
-            }
-        };
-        /**
-         * A current snapshot of this Entity's data, including nested
-         * Entities.
-         */
-        this.getSnapshot = () => {
-            return this.viewWithMappedChildren((child) => child.getSnapshot());
-        };
-        // change management methods (internal use only)
-        this.addPendingOperations = (operations) => {
-            this.ctx.log('debug', 'Entity: adding pending operations', this.oid);
-            const changes = this.metadataFamily.addPendingData(operations);
-            for (const change of changes) {
-                this.change(change);
-            }
-        };
-        this.addConfirmedData = (data) => {
-            this.ctx.log('debug', 'Entity: adding confirmed data', this.oid);
-            const changes = this.metadataFamily.addConfirmedData(data);
-            for (const change of changes) {
-                this.change(change);
-            }
-        };
-        this.replaceAllData = (data) => {
-            this.ctx.log('debug', 'Entity: replacing all data', this.oid);
-            const changes = this.metadataFamily.replaceAllData(data);
-            for (const change of changes) {
-                this.change(change);
-            }
-        };
-        this.resetAllData = () => {
-            this.ctx.log('debug', 'Entity: resetting all data', this.oid);
-            this.cachedDeepUpdatedAt = null;
-            this.cachedView = undefined;
-            this._viewData = undefined;
-            const changes = this.metadataFamily.replaceAllData({});
-            for (const change of changes) {
-                this.change(change);
-            }
-        };
-        this.change = (ev) => {
-            if (ev.oid === this.oid) {
-                // reset cached view
-                this._viewData = undefined;
-                this.cachedView = undefined;
-                // chain deepChanges to parents
-                this.deepChange(this, ev);
-                // emit the change, it's for us
-                this.ctx.log('Emitting change event', this.oid);
-                this.emit('change', { isLocal: ev.isLocal });
-                // for root entities, we need to go ahead and decide if we're
-                // deleted or not - so queries can exclude us if we are.
-                if (!this.parent) {
-                    // newly deleted - emit event
-                    if (this.deleted && !this.wasDeletedLastChange) {
-                        this.ctx.log('debug', 'Entity deleted', this.oid);
-                        this.emit('delete', { isLocal: ev.isLocal });
-                        this.wasDeletedLastChange = true;
-                    }
-                    else if (!this.deleted && this.wasDeletedLastChange) {
-                        this.ctx.log('debug', 'Entity restored', this.oid);
-                        // newly restored - emit event
-                        this.emit('restore', { isLocal: ev.isLocal });
-                        this.wasDeletedLastChange = false;
-                    }
-                }
-            }
-            else {
-                // forward it to the correct family member. if none exists
-                // in cache, no one will hear it anyways.
-                const other = this.entityFamily.getCached(ev.oid);
-                if (other && other instanceof Entity) {
-                    other.change(ev);
-                }
-            }
-        };
-        this.deepChange = (target, ev) => {
-            var _a;
-            // reset cached deep updated at timestamp; either this
-            // entity or children have changed
-            this.cachedDeepUpdatedAt = null;
-            // reset this flag to recompute snapshot data - children
-            // or self has changed. new pruning needs to happen.
-            this.cachedView = undefined;
-            this.ctx.log('debug', 'Deep change detected at', this.oid, 'reset cached view');
-            this.ctx.log('debug', 'Emitting deep change event', this.oid);
-            this.emit('changeDeep', target, ev);
-            (_a = this.parent) === null || _a === void 0 ? void 0 : _a.deepChange(target, ev);
-        };
-        this.getChild = (key, oid) => {
-            const schema = (0, common_1.getChildFieldSchema)(this.schema, key);
-            if (!schema) {
-                throw new Error(`No schema for key ${String(key)} in ${JSON.stringify(this.schema)}`);
-            }
-            return this.entityFamily.get({
-                oid,
-                schema,
-                entityFamily: this.entityFamily,
-                metadataFamily: this.metadataFamily,
-                parent: this,
-                ctx: this.ctx,
-                files: this.files,
-                fieldPath: [...this.fieldPath, key],
-                patchCreator: this.patchCreator,
-                events: this.events,
-            });
-        };
-        // generic entity methods
-        /**
-         * Gets a value from this Entity. If the value
-         * is an object, it will be wrapped in another
-         * Entity.
-         */
-        this.get = (key) => {
-            assertNotSymbol(key);
-            const view = this.rawView;
-            if (!view) {
-                throw new Error(`Cannot access data at key ${key} on deleted entity ${this.oid}`);
-            }
-            const child = view[key];
-            const schema = (0, common_1.getChildFieldSchema)(this.schema, key);
-            if (!schema) {
-                throw new Error(`No schema for key ${String(key)} in ${JSON.stringify(this.schema)}`);
-            }
-            if ((0, common_1.isRef)(child)) {
-                if ((0, common_1.isFileRef)(child)) {
-                    if (schema.type !== 'file') {
-                        throw new Error(`Expected file schema for key ${String(key)}, got ${schema.type}`);
-                    }
-                    const file = this.files.get(child.id, {
-                        downloadRemote: !!schema.downloadRemote,
-                    });
-                    // FIXME: this seems bad and inconsistent
-                    file.subscribe('change', () => {
-                        this.deepChange(this, { isLocal: false, oid: this.oid });
-                    });
-                    return file;
-                }
-                else {
-                    return this.getChild(key, child.id);
-                }
-            }
-            else {
-                // prune invalid primitive fields
-                if ((0, common_1.validateEntityField)({
-                    field: schema,
-                    value: child,
-                    fieldPath: [...this.fieldPath, key],
-                    depth: 1,
-                    requireDefaults: true,
-                })) {
-                    if ((0, common_1.hasDefault)(schema)) {
-                        return (0, common_1.getDefault)(schema);
-                    }
-                    if ((0, common_1.isNullable)(schema)) {
-                        return null;
-                    }
-                    return undefined;
-                }
-                return child;
-            }
-        };
-        this.processInputValue = (value, key) => {
-            if (this.readonlyKeys.includes(key)) {
-                throw new Error(`Cannot set readonly key ${key.toString()}`);
-            }
-            // disassociate incoming OIDs on values and generally break object
-            // references. cloning doesn't work on files so those are
-            // filtered out.
-            // The goal here is to be safe about a bunch of cases that could
-            // result in corrupt data, like...
-            // ent1.set('objField', ent2.get('objField'))
-            // or
-            // var shared = { foo: 'bar' };
-            // ent1.set('objField', shared);
-            // ent2.set('objField', shared);
-            // ... each of these would result in the same object being
-            // referenced in multiple entities, which could mean introduction
-            // of foreign OIDs, or one object being assigned different OIDs
-            // with unexpected results.
-            if (!(0, utils_js_1.isFile)(value)) {
-                value = (0, common_1.cloneDeep)(value, false);
-            }
-            const fieldSchema = (0, common_1.getChildFieldSchema)(this.schema, key);
-            if (fieldSchema) {
-                (0, common_1.traverseCollectionFieldsAndApplyDefaults)(value, fieldSchema);
-                const validationError = (0, common_1.validateEntityField)({
-                    field: fieldSchema,
-                    value,
-                    fieldPath: [...this.fieldPath, key],
-                });
-                if (validationError) {
-                    // TODO: is it a good idea to throw an error here? a runtime error won't be that helpful,
-                    // but also we don't really want invalid data supplied.
-                    throw new Error(validationError.message);
-                }
-            }
-            return (0, utils_js_1.processValueFiles)(value, this.files.add);
-        };
-        this.getDeleteMode = (key) => {
-            if (this.readonlyKeys.includes(key)) {
-                return false;
-            }
-            // any is always deletable, and map values
-            if (this.schema.type === 'any' || this.schema.type === 'map') {
-                return 'delete';
-            }
-            if (this.schema.type === 'object') {
-                const property = this.schema.properties[key];
-                if (!property) {
-                    // huh, the property doesn't exist. it's ok to
-                    // remove I suppose.
-                    return 'delete';
-                }
-                if (property.type === 'any')
-                    return 'delete';
-                // map can't be nullable. should it be?
-                if (property.type === 'map')
-                    return false;
-                if (property.nullable)
-                    return 'null';
-            }
-            // no other types are deletable
-            return false;
-        };
-        /**
-         * Returns the referent value of an item in the list, used for
-         * operations which act on items. if the item is an object,
-         * it will attempt to create an OID reference to it. If it
-         * is a primitive, it will return the primitive.
-         */
-        this.getItemRefValue = (item) => {
-            if (item instanceof Entity) {
-                return (0, common_1.createRef)(item.oid);
-            }
-            if (item instanceof index_js_1.EntityFile) {
-                return (0, common_1.createFileRef)(item.id);
-            }
-            if (typeof item === 'object') {
-                const itemOid = (0, common_1.maybeGetOid)(item);
-                if (!itemOid || !this.entityFamily.has(itemOid)) {
-                    throw new Error(`Cannot move object ${JSON.stringify(item)} which does not exist in this list`);
-                }
-                return (0, common_1.createRef)(itemOid);
-            }
-            else {
-                return item;
-            }
-        };
-        this.set = (key, value) => {
-            assertNotSymbol(key);
-            this.addPendingOperations(this.patchCreator.createSet(this.oid, key, this.processInputValue(value, key)));
-        };
-        /**
-         * Returns a destructured version of this Entity, where child
-         * Entities are accessible at their respective keys.
-         */
-        this.getAll = () => {
-            return this.view;
-        };
-        this.delete = (key) => {
-            if (this.isList) {
-                assertNumber(key);
-                this.addPendingOperations(this.patchCreator.createListDelete(this.oid, key));
-            }
-            else {
-                // the key must be deletable - i.e. optional in the schema.
-                const deleteMode = this.getDeleteMode(key);
-                if (!deleteMode) {
-                    throw new Error(`Cannot delete key ${key.toString()} - the property is not marked as optional in the schema.`);
-                }
-                if (deleteMode === 'delete') {
-                    this.addPendingOperations(this.patchCreator.createRemove(this.oid, key));
-                }
-                else {
-                    this.addPendingOperations(this.patchCreator.createSet(this.oid, key, null));
-                }
-            }
-        };
-        // object entity methods
-        this.keys = () => {
-            if (!this.view)
-                return [];
-            return Object.keys(this.view);
-        };
-        this.entries = () => {
-            if (!this.view)
-                return [];
-            return Object.entries(this.view);
-        };
-        this.values = () => {
-            if (!this.view)
-                return [];
-            return Object.values(this.view);
-        };
-        this.update = (data, { merge = true, replaceSubObjects = false, } = {}) => {
-            if (!merge && this.schema.type !== 'any' && this.schema.type !== 'map') {
-                throw new Error('Cannot use .update without merge if the field has a strict schema type. merge: false is only available on "any" or "map" types.');
-            }
-            const changes = {};
-            (0, common_1.assignOid)(changes, this.oid);
-            for (const [key, field] of Object.entries(data)) {
-                if (this.readonlyKeys.includes(key)) {
-                    throw new Error(`Cannot set readonly key ${key.toString()}`);
-                }
-                const fieldSchema = (0, common_1.getChildFieldSchema)(this.schema, key);
-                if (fieldSchema) {
-                    (0, common_1.traverseCollectionFieldsAndApplyDefaults)(field, fieldSchema);
-                }
-                changes[key] = this.processInputValue(field, key);
-            }
-            this.addPendingOperations(this.patchCreator.createDiff(this.getSnapshot(), changes, {
-                mergeUnknownObjects: !replaceSubObjects,
-                defaultUndefined: merge,
-            }));
-        };
-        this.push = (value) => {
-            this.addPendingOperations(this.patchCreator.createListPush(this.oid, this.processInputValue(value, this.view.length)));
-        };
-        this.insert = (index, value) => {
-            this.addPendingOperations(this.patchCreator.createListInsert(this.oid, index, this.processInputValue(value, index)));
-        };
-        this.move = (from, to) => {
-            this.addPendingOperations(this.patchCreator.createListMoveByIndex(this.oid, from, to));
-        };
-        this.moveItem = (item, to) => {
-            const itemRef = this.getItemRefValue(item);
-            if ((0, common_1.isRef)(itemRef)) {
-                this.addPendingOperations(this.patchCreator.createListMoveByRef(this.oid, itemRef, to));
-            }
-            else {
-                const index = this.view.indexOf(item);
-                if (index === -1) {
-                    throw new Error(`Cannot move item ${JSON.stringify(item)} which does not exist in this list`);
-                }
-                this.move(index, to);
-            }
-        };
-        this.add = (value) => {
-            this.addPendingOperations(this.patchCreator.createListAdd(this.oid, this.processInputValue(value, this.view.length)));
-        };
-        this.removeAll = (item) => {
-            this.addPendingOperations(this.patchCreator.createListRemove(this.oid, this.getItemRefValue(item)));
-        };
-        this.removeFirst = (item) => {
-            this.addPendingOperations(this.patchCreator.createListRemove(this.oid, this.getItemRefValue(item), 'first'));
-        };
-        this.removeLast = (item) => {
-            this.addPendingOperations(this.patchCreator.createListRemove(this.oid, this.getItemRefValue(item), 'last'));
-        };
-        this.map = (callback) => {
-            return this.view.map(callback);
-        };
-        this.filter = (callback) => {
-            return this.view.filter(callback);
-        };
-        this.has = (value) => {
-            if (!this.isList) {
-                throw new Error('has() is only available on list entities');
-            }
-            const itemRef = this.getItemRefValue(value);
-            if ((0, common_1.isRef)(itemRef)) {
-                return this.view.some((item) => {
-                    if ((0, common_1.isRef)(item)) {
-                        return (0, common_1.compareRefs)(item, itemRef);
-                    }
-                });
-            }
-            else {
-                return this.view.includes(value);
-            }
-        };
-        this.forEach = (callback) => {
-            this.view.forEach(callback);
-        };
-        this.some = (predicate) => {
-            return this.view.some(predicate);
-        };
-        this.every = (predicate) => {
-            return this.view.every(predicate);
-        };
-        this.find = (predicate) => {
-            return this.view.find(predicate);
-        };
-        this.includes = this.has;
-        // TODO: make these escape hatches unnecessary
-        this.__getViewData__ = (oid, type) => {
-            return this.metadataFamily.get(oid).computeView(type === 'confirmed');
-        };
-        this.__getFamilyOids__ = () => this.metadataFamily.getAllOids();
-        (0, common_1.assert)(!!oid, 'oid is required');
-        this.oid = oid;
-        this.readonlyKeys = readonlyKeys || [];
-        this.ctx = ctx;
-        this.files = files;
-        this.schema = schema;
-        this.entityFamily =
-            childCache ||
-                new EntityCache_js_1.EntityCache({
-                    initial: [this],
-                });
-        this.patchCreator = patchCreator;
-        this.metadataFamily = metadataFamily;
-        this.events = events;
-        this.parent = parent;
-        // TODO: should any but the root entity be listening to these?
-        if (!this.parent) {
-            events.add.attach(this.onAdd);
-            events.replace.attach(this.onReplace);
-            events.resetAll.attach(this.onResetAll);
-        }
-    }
-    get metadata() {
-        return this.metadataFamily.get(this.oid);
-    }
-    /**
-     * The view of this Entity, not including nested
-     * entities (that's the snapshot - see #getSnapshot())
-     *
-     * Nested entities are represented by refs.
-     */
-    get viewData() {
-        if (this._viewData === undefined) {
-            this._viewData = this.metadata.computeView();
-            this.validate();
-        }
-        return this._viewData;
-    }
-    /** convenience getter for viewData.view */
-    get rawView() {
-        return this.viewData.view;
-    }
-    /**
-     * An Entity's View includes the rendering of its underlying data,
-     * connecting of children where refs were, and validation
-     * and pruning according to schema.
-     */
-    get view() {
-        if (this.cachedView !== undefined) {
-            return this.cachedView;
-        }
-        if (this.viewData.deleted) {
-            return null;
-        }
-        // can't use invalid data - but this should be bubbled up to
-        // a prune point
-        const rawView = this.rawView;
-        const viewIsWrongType = (!rawView && !(0, common_1.isNullable)(this.schema)) ||
-            (this.schema.type === 'array' && !Array.isArray(rawView)) ||
-            ((this.schema.type === 'object' || this.schema.type === 'map') &&
-                !(0, common_1.isObject)(rawView));
-        if (viewIsWrongType) {
-            // this will cover lists and maps, too.
-            if ((0, common_1.hasDefault)(this.schema)) {
-                return (0, common_1.getDefault)(this.schema);
-            }
-            // force null - invalid - will require parent prune
-            return null;
-        }
-        this.cachedView = this.isList ? [] : {};
-        (0, common_1.assignOid)(this.cachedView, this.oid);
-        if (Array.isArray(rawView)) {
-            const schema = (0, common_1.getChildFieldSchema)(this.schema, 0);
-            if (!schema) {
-                /**
-                 * PRUNE - this is a prune point. we can't continue
-                 * to render this data, so we'll just return [].
-                 * This skips the loop.
-                 */
-                this.ctx.log('error', 'No child field schema for list entity.', this.oid);
-            }
-            else {
-                for (let i = 0; i < rawView.length; i++) {
-                    const child = this.get(i);
-                    if (this.childIsNull(child) && !(0, common_1.isNullable)(schema)) {
-                        this.ctx.log('error', 'Child missing in non-nullable field', this.oid, 'index:', i);
-                        // this item will be pruned.
-                    }
-                    else {
-                        this.cachedView.push(child);
-                    }
-                }
-            }
-        }
-        else if ((0, common_1.isObject)(rawView)) {
-            // iterate over known properties in object-type entities;
-            // for maps, we just iterate over the keys.
-            const keys = this.schema.type === 'object'
-                ? Object.keys(this.schema.properties)
-                : Object.keys(rawView);
-            for (const key of keys) {
-                const schema = (0, common_1.getChildFieldSchema)(this.schema, key);
-                if (!schema) {
-                    /**
-                     * PRUNE - this is a prune point. we can't continue
-                     * to render this data. If this is a map, it will be
-                     * pruned empty. Otherwise, prune moves upward.
-                     *
-                     * This exits the loop.
-                     */
-                    this.ctx.log('error', 'No child field schema for object entity at key', key);
-                    if (this.schema.type === 'map') {
-                        // it's valid to prune here if it's a map
-                        this.cachedView = {};
-                    }
-                    else {
-                        // otherwise prune moves upward
-                        this.cachedView = null;
-                    }
-                    break;
-                }
-                const child = this.get(key);
-                if (this.childIsNull(child) && !(0, common_1.isNullable)(schema)) {
-                    this.ctx.log('error', 'Child entity is missing for non-nullable field', this.oid, 'key:', key);
-                    /**
-                     * PRUNE - this is a prune point. we can't continue
-                     * to render this data. If this is a map, we can ignore
-                     * this value. Otherwise we must prune upward.
-                     * This exits the loop.
-                     */
-                    if (this.schema.type !== 'map') {
-                        this.cachedView = null;
-                        break;
-                    }
-                }
-                else {
-                    this.cachedView[key] = child;
-                }
-            }
-        }
-        return this.cachedView;
-    }
-    get uid() {
-        return this.oid;
-    }
-    get deleted() {
-        return this.viewData.deleted || this.view === null;
-    }
-    get invalid() {
-        return !!this.validate();
-    }
-    get isList() {
-        // have to turn TS off here as our two interfaces both implement
-        // const values for this boolean.
-        return (this.schema.type === 'array' || Array.isArray(this.viewData.view));
-    }
-    get updatedAt() {
-        return this.viewData.updatedAt;
-    }
-    get deepUpdatedAt() {
-        if (this.cachedDeepUpdatedAt)
-            return this.cachedDeepUpdatedAt;
-        // iterate over all children and take the latest timestamp
-        let latest = this.updatedAt;
-        if (this.isList) {
-            this.forEach((child) => {
-                if (child instanceof Entity) {
-                    const childTimestamp = child.deepUpdatedAt;
-                    if (childTimestamp && (!latest || childTimestamp > latest)) {
-                        latest = childTimestamp;
-                    }
-                }
-            });
-        }
-        else {
-            this.values().forEach((child) => {
-                if (child instanceof Entity) {
-                    const childTimestamp = child.deepUpdatedAt;
-                    if (childTimestamp && (!latest || childTimestamp > latest)) {
-                        latest = childTimestamp;
-                    }
-                }
-            });
-        }
-        this.cachedDeepUpdatedAt = latest;
-        return latest;
-    }
-    /**
-     * @internal - this is relevant to Verdant's system, not users.
-     *
-     * Indicates whether this document is from an outdated version
-     * of the schema - which means it cannot be used until it is upgraded.
-     */
-    get isOutdatedVersion() {
-        if (this.parent)
-            return this.parent.isOutdatedVersion;
-        return this.viewData.fromOlderVersion;
-    }
-    // array entity methods
-    get length() {
-        return this.view.length;
-    }
-    // list implements an iterator which maps items to wrapped
-    // versions
-    [Symbol.iterator]() {
-        var _a;
-        let index = 0;
-        let length = (_a = this.view) === null || _a === void 0 ? void 0 : _a.length;
-        return {
-            next: () => {
-                if (index < length) {
-                    return {
-                        value: this.get(index++),
-                        done: false,
-                    };
-                }
-                return {
-                    value: undefined,
-                    done: true,
-                };
-            },
-        };
-    }
-}
-exports.Entity = Entity;
-function assertNotSymbol(key) {
-    if (typeof key === 'symbol')
-        throw new Error("Symbol keys aren't supported");
-}
-function assertNumber(key) {
-    if (typeof key !== 'number')
-        throw new Error('Only number keys are supported in list entities');
-}
-//# sourceMappingURL=Entity.js.map