@verdant-web/store 3.0.0-next.0 → 3.0.0

package/dist/cjs/entities/Entity.js

@@ -1,185 +1,256 @@
 "use strict";
-var _a, _b;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Entity = exports.refreshEntity = exports.DEEP_CHANGE = exports.REBASE = exports.DELETE = exports.ADD_OPERATIONS = void 0;
+exports.Entity = void 0;
 const common_1 = require("@verdant-web/common");
 const utils_js_1 = require("../files/utils.js");
-exports.ADD_OPERATIONS = '@@addOperations';
-exports.DELETE = '@@delete';
-exports.REBASE = '@@rebase';
-const REFRESH = '@@refresh';
-exports.DEEP_CHANGE = '@@deepChange';
-function refreshEntity(entity, info) {
-    return entity[REFRESH](info);
-}
-exports.refreshEntity = refreshEntity;
-class Entity {
-    hasSubscribersToDeepChanges() {
-        return this.events.subscriberCount('changeDeep') > 0;
-    }
-    get hasSubscribers() {
-        var _c, _d;
-        if (this.events.totalSubscriberCount() > 0) {
-            return true;
-        }
-        // even if nobody subscribes directly to this entity, if a parent
-        // has a deep subscription that counts.
-        let parent = (_c = this.parent) === null || _c === void 0 ? void 0 : _c.deref();
-        while (parent) {
-            if (parent.hasSubscribersToDeepChanges()) {
-                return true;
-            }
-            parent = (_d = parent.parent) === null || _d === void 0 ? void 0 : _d.deref();
-        }
-        return false;
-    }
-    get deleted() {
-        return this._deleted;
-    }
-    get value() {
-        return this._current;
-    }
-    get isList() {
-        return Array.isArray(this._current);
-    }
-    get updatedAt() {
-        return this._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;
-    }
-    get uid() {
-        return this.oid;
-    }
-    constructor({ oid, store, fieldSchema, cache, parent, onAllUnsubscribed, readonlyKeys = [], fieldPath = [], }) {
-        // if current is null, the entity was deleted.
-        this._current = null;
-        this._deleted = false;
-        this.cachedSnapshot = null;
-        this.cachedDestructure = null;
+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;
-        this._updatedAt = null;
-        this[_a] = (info) => {
-            const { view, deleted, lastTimestamp } = this.cache.computeView(this.oid);
-            this._current = view;
-            const restored = this._deleted && !deleted;
-            this._deleted = deleted;
-            this.cachedDestructure = null;
-            this._updatedAt = lastTimestamp ? lastTimestamp : null;
-            this.cachedDeepUpdatedAt = null;
-            if (this._deleted) {
-                this.events.emit('delete', info);
-            }
-            else {
-                this.events.emit('change', info);
-                this[exports.DEEP_CHANGE](this, info);
-            }
-            if (restored) {
-                this.cachedSnapshot = null;
-                this.events.emit('restore', info);
+        // 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[_b] = (source, info) => {
-            var _c;
-            this.cachedSnapshot = null;
-            this.cachedDeepUpdatedAt = null;
-            this.events.emit('changeDeep', source, info);
-            const parent = (_c = this.parent) === null || _c === void 0 ? void 0 : _c.deref();
-            if (parent) {
-                parent[exports.DEEP_CHANGE](source, info);
+        this.onReplace = (_store, data) => {
+            if (data.oid === this.oid) {
+                this.replaceAllData(data);
             }
         };
-        this.getChildFieldSchema = (key) => {
-            if (this.fieldSchema.type === 'object') {
-                return this.fieldSchema.properties[key];
+        this.onResetAll = () => {
+            this.resetAllData();
+        };
+        this.childIsNull = (child) => {
+            if (child instanceof Entity) {
+                const childView = child.view;
+                return childView === null || childView === undefined;
             }
-            else if (this.fieldSchema.type === 'array') {
-                return this.fieldSchema.items;
+            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;
             }
-            else if (this.fieldSchema.type === 'map') {
-                return this.fieldSchema.values;
+            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 if (this.fieldSchema.type === 'any') {
-                return this.fieldSchema;
+            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;
             }
-            throw new Error('Invalid field schema');
         };
-        this.dispose = () => {
-            this.events.dispose();
+        /**
+         * 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.subscribe = (event, callback) => {
-            const unsubscribe = this.events.subscribe(event, callback);
-            return unsubscribe;
+        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.addPatches = (patches) => {
-            this.store.addLocalOperations(patches);
+        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.cloneCurrent = () => {
-            if (this._current === undefined) {
-                return undefined;
+        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);
+                }
             }
-            return (0, common_1.cloneDeep)(this._current);
         };
-        this.getSubObject = (oid, key) => {
-            const fieldSchema = this.getChildFieldSchema(key);
-            // this is a failure case, but trying to be graceful about it...
-            // @ts-ignore
-            // if (!fieldSchema) return null;
-            return this.cache.getEntity({
+        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,
-                fieldSchema,
+                schema,
+                entityFamily: this.entityFamily,
+                metadataFamily: this.metadataFamily,
                 parent: this,
-                fieldKey: key,
+                ctx: this.ctx,
+                files: this.files,
+                fieldPath: [...this.fieldPath, key],
+                patchCreator: this.patchCreator,
+                events: this.events,
             });
         };
-        this.wrapValue = (value, key) => {
-            if ((0, common_1.isObjectRef)(value)) {
-                const oid = value.id;
-                const subObject = this.getSubObject(oid, key);
-                if (subObject) {
-                    return subObject;
-                }
-                throw new Error(`CACHE MISS: Subobject ${oid} does not exist on ${this.oid}`);
-            }
-            else if ((0, common_1.isFileRef)(value)) {
-                const file = this.store.getFile(value.id);
-                if (file) {
+        // 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[exports.DEEP_CHANGE](this, {
-                            isLocal: false,
-                        });
+                        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;
             }
-            return value;
         };
         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.
@@ -194,331 +265,427 @@ class Entity {
             // referenced in multiple entities, which could mean introduction
             // of foreign OIDs, or one object being assigned different OIDs
             // with unexpected results.
-            if (!(value instanceof File)) {
+            if (!(0, utils_js_1.isFile)(value)) {
                 value = (0, common_1.cloneDeep)(value, false);
             }
-            const fieldSchema = this.getChildFieldSchema(key);
+            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);
+                }
             }
-            const validationError = (0, common_1.validateEntityField)(fieldSchema, value, [
-                ...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);
-            }
-            return (0, utils_js_1.processValueFiles)(value, this.store.addFile);
-        };
-        this.get = (key) => {
-            if (this.value === undefined || this.value === null) {
-                throw new Error('Cannot access deleted entity');
-            }
-            const value = this.value[key];
-            return this.wrapValue(value, key);
+            return (0, utils_js_1.processValueFiles)(value, this.files.add);
         };
-        this.getAll = () => {
-            if (this.value === undefined || this.value === null) {
-                throw new Error('Cannot access deleted entity');
+        this.getDeleteMode = (key) => {
+            if (this.readonlyKeys.includes(key)) {
+                return false;
             }
-            if (this.cachedDestructure)
-                return this.cachedDestructure;
-            let result;
-            if (Array.isArray(this.value)) {
-                result = this.value.map((value, index) => this.wrapValue(value, index));
+            // any is always deletable, and map values
+            if (this.schema.type === 'any' || this.schema.type === 'map') {
+                return 'delete';
             }
-            else {
-                result = {};
-                for (const key in this.value) {
-                    result[key] = this.get(key);
+            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';
             }
-            this.cachedDestructure = result;
-            return result;
+            // no other types are deletable
+            return false;
         };
         /**
-         * Returns a copy of the entity and all sub-objects as
-         * a plain object or array.
+         * 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.getSnapshot = () => {
-            var _c;
-            if (!this.value) {
-                return null;
-            }
-            if (this.deleted) {
-                return null;
+        this.getItemRefValue = (item) => {
+            if (item instanceof Entity) {
+                return (0, common_1.createRef)(item.oid);
             }
-            if (this.cachedSnapshot) {
-                return this.cachedSnapshot;
+            if (item instanceof index_js_1.EntityFile) {
+                return (0, common_1.createFileRef)(item.id);
             }
-            let snapshot;
-            if (Array.isArray(this.value)) {
-                snapshot = this.value.map((item, idx) => {
-                    var _c;
-                    if ((0, common_1.isObjectRef)(item)) {
-                        return (_c = this.getSubObject(item.id, idx)) === null || _c === void 0 ? void 0 : _c.getSnapshot();
-                    }
-                    else if ((0, common_1.isFileRef)(item)) {
-                        return this.getFileSnapshot(item);
-                    }
-                    return item;
-                });
+            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 {
-                snapshot = Object.assign({}, this.value);
-                for (const [key, value] of Object.entries(snapshot)) {
-                    if ((0, common_1.isObjectRef)(value)) {
-                        snapshot[key] = (_c = this.getSubObject(value.id, key)) === null || _c === void 0 ? void 0 : _c.getSnapshot();
-                    }
-                    else if ((0, common_1.isFileRef)(value)) {
-                        snapshot[key] = this.getFileSnapshot(value);
-                    }
-                }
+                return item;
             }
-            (0, common_1.assignOid)(snapshot, this.oid);
-            this.cachedSnapshot = snapshot;
-            return snapshot;
+        };
+        this.set = (key, value) => {
+            assertNotSymbol(key);
+            this.addPendingOperations(this.patchCreator.createSet(this.oid, key, this.processInputValue(value, key)));
         };
         /**
-         * Object methods
+         * Returns a destructured version of this Entity, where child
+         * Entities are accessible at their respective keys.
          */
-        this.keys = () => {
-            return Object.keys(this.value || {});
-        };
-        this.entries = () => {
-            return Object.entries(this.getAll());
-        };
-        this.values = () => {
-            return Object.values(this.getAll());
-        };
-        this.set = (key, value) => {
-            if (this.readonlyKeys.includes(key)) {
-                throw new Error(`Cannot set readonly key ${key.toString()}`);
-            }
-            this.addPatches(this.store.patchCreator.createSet(this.oid, key, this.processInputValue(value, key)));
+        this.getAll = () => {
+            return this.view;
         };
         this.delete = (key) => {
-            if (Array.isArray(this.value)) {
-                this.addPatches(this.store.patchCreator.createListDelete(this.oid, key, 1));
+            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
+                // 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} - the property is not marked as optional in the schema`);
+                    throw new Error(`Cannot delete key ${key.toString()} - the property is not marked as optional in the schema.`);
                 }
                 if (deleteMode === 'delete') {
-                    this.addPatches(this.store.patchCreator.createRemove(this.oid, key));
+                    this.addPendingOperations(this.patchCreator.createRemove(this.oid, key));
                 }
                 else {
-                    this.addPatches(this.store.patchCreator.createSet(this.oid, key, null));
+                    this.addPendingOperations(this.patchCreator.createSet(this.oid, key, null));
                 }
             }
         };
-        this.getDeleteMode = (key) => {
-            if (this.readonlyKeys.includes(key)) {
-                return false;
-            }
-            // 'any' is always deletable, and map values can be removed completely
-            if (this.fieldSchema.type === 'any' || this.fieldSchema.type === 'map') {
-                return 'delete';
-            }
-            if (this.fieldSchema.type === 'object') {
-                const property = this.fieldSchema.properties[key];
-                if (!property) {
-                    // huh, trying to delete a field that isn't specified
-                    // in the schema. we should use 'delete' mode.
-                    return 'delete';
-                }
-                if (property.type === 'any')
-                    return 'delete';
-                // map can't be nullable
-                // TODO: should it be?
-                if (property.type === 'map')
-                    return false;
-                // nullable properties can only be set null
-                if (property.nullable)
-                    return 'null';
-            }
-            // no other parent objects support deleting
-            return false;
+        // 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);
         };
-        /** @deprecated - renamed to delete */
-        this.remove = this.delete.bind(this);
-        this.update = (value, { replaceSubObjects = false, merge = true, } = {
-            /**
-             * If true, merged sub-objects will be replaced entirely if there's
-             * ambiguity about their identity.
-             */
-            replaceSubObjects: false,
-            /**
-             * If false, omitted keys will erase their respective fields.
-             */
-            merge: true,
-        }) => {
-            if (!merge &&
-                this.fieldSchema.type !== 'any' &&
-                this.fieldSchema.type !== 'map') {
+        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.');
             }
-            for (const [key, field] of Object.entries(value)) {
+            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 = this.getChildFieldSchema(key);
+                const fieldSchema = (0, common_1.getChildFieldSchema)(this.schema, key);
                 if (fieldSchema) {
                     (0, common_1.traverseCollectionFieldsAndApplyDefaults)(field, fieldSchema);
                 }
+                changes[key] = this.processInputValue(field, key);
             }
-            const withoutFiles = (0, utils_js_1.processValueFiles)(value, this.store.addFile);
-            this.addPatches(this.store.patchCreator.createDiff(this.getSnapshot(), (0, common_1.assignOid)(withoutFiles, this.oid), {
+            this.addPendingOperations(this.patchCreator.createDiff(this.getSnapshot(), changes, {
                 mergeUnknownObjects: !replaceSubObjects,
                 defaultUndefined: merge,
             }));
         };
-        /**
-         * List methods
-         */
-        /**
-         * 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 (typeof item === 'object') {
-                const itemOid = (0, common_1.maybeGetOid)(item);
-                if (!itemOid || !this.cache.hasOid(itemOid)) {
-                    throw new Error(`Cannot move object ${JSON.stringify(item)} which does not exist in this list`);
-                }
-                return itemOid;
-            }
-            else {
-                return item;
-            }
-        };
         this.push = (value) => {
-            this.addPatches(this.store.patchCreator.createListPush(this.oid, this.processInputValue(value, this.value.length)));
+            this.addPendingOperations(this.patchCreator.createListPush(this.oid, this.processInputValue(value, this.view.length)));
         };
         this.insert = (index, value) => {
-            this.addPatches(this.store.patchCreator.createListInsert(this.oid, index, this.processInputValue(value, index)));
+            this.addPendingOperations(this.patchCreator.createListInsert(this.oid, index, this.processInputValue(value, index)));
         };
         this.move = (from, to) => {
-            this.addPatches(this.store.patchCreator.createListMoveByIndex(this.oid, from, to));
+            this.addPendingOperations(this.patchCreator.createListMoveByIndex(this.oid, from, to));
         };
         this.moveItem = (item, to) => {
             const itemRef = this.getItemRefValue(item);
-            if ((0, common_1.isObjectRef)(itemRef)) {
-                this.addPatches(this.store.patchCreator.createListMoveByRef(this.oid, itemRef, to));
+            if ((0, common_1.isRef)(itemRef)) {
+                this.addPendingOperations(this.patchCreator.createListMoveByRef(this.oid, itemRef, to));
             }
             else {
-                const index = this.value.indexOf(itemRef);
-                this.addPatches(this.store.patchCreator.createListMoveByIndex(this.oid, index, to));
+                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.addPatches(this.store.patchCreator.createListRemove(this.oid, this.getItemRefValue(item)));
+            this.addPendingOperations(this.patchCreator.createListRemove(this.oid, this.getItemRefValue(item)));
         };
         this.removeFirst = (item) => {
-            this.addPatches(this.store.patchCreator.createListRemove(this.oid, this.getItemRefValue(item), 'first'));
+            this.addPendingOperations(this.patchCreator.createListRemove(this.oid, this.getItemRefValue(item), 'first'));
         };
         this.removeLast = (item) => {
-            this.addPatches(this.store.patchCreator.createListRemove(this.oid, this.getItemRefValue(item), 'last'));
-        };
-        this.add = (item) => {
-            this.addPatches(this.store.patchCreator.createListAdd(this.oid, this.processInputValue(item, this.value.length)));
-        };
-        this.has = (item) => {
-            if (typeof item === 'object') {
-                return this.value.some((val) => {
-                    if ((0, common_1.isObjectRef)(val))
-                        return val.id === (0, common_1.maybeGetOid)(item);
-                    // Sets of files don't work right now, there's no way to compare them
-                    // effectively.
-                    if ((0, common_1.isFileRef)(val))
-                        return false;
-                    return false;
-                });
-            }
-            return this.value.includes(item);
-        };
-        // additional access methods
-        this.getAsWrapped = () => {
-            if (!this.isList)
-                throw new Error('Cannot map items of a non-list');
-            return this.value.map(this.wrapValue);
+            this.addPendingOperations(this.patchCreator.createListRemove(this.oid, this.getItemRefValue(item), 'last'));
         };
         this.map = (callback) => {
-            return this.getAsWrapped().map(callback);
+            return this.view.map(callback);
         };
         this.filter = (callback) => {
-            return this.getAsWrapped().filter((val, index) => {
-                return callback(val, index);
-            });
+            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.getAsWrapped().forEach(callback);
+            this.view.forEach(callback);
         };
         this.some = (predicate) => {
-            return this.getAsWrapped().some(predicate);
+            return this.view.some(predicate);
         };
         this.every = (predicate) => {
-            return this.getAsWrapped().every(predicate);
+            return this.view.every(predicate);
         };
         this.find = (predicate) => {
-            return this.getAsWrapped().find(predicate);
+            return this.view.find(predicate);
         };
-        this.includes = (item) => {
-            return this.has(item);
+        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;
-        const { collection } = (0, common_1.decomposeOid)(oid);
-        this.collection = collection;
-        this.store = store;
-        this.fieldSchema = fieldSchema;
-        this.fieldPath = fieldPath;
-        this.readonlyKeys = readonlyKeys;
-        this.cache = cache;
-        this.parent = parent && this.cache.weakRef(parent);
-        const { view, deleted, lastTimestamp } = this.cache.computeView(oid);
-        this._current = view;
-        this._deleted = deleted;
-        this._updatedAt = lastTimestamp ? lastTimestamp : null;
-        this.cachedDeepUpdatedAt = null;
-        this.events = new common_1.EventSubscriber(() => {
-            if (!this.hasSubscribers) {
-                onAllUnsubscribed === null || onAllUnsubscribed === void 0 ? void 0 : onAllUnsubscribed();
-            }
-        });
-        if (this.oid.includes('.') && !this.parent) {
-            throw new Error('Parent must be provided for sub entities');
+        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);
         }
-        (0, common_1.assert)(!!fieldSchema, 'Field schema must be provided');
     }
-    getFileSnapshot(item) {
-        const file = this.store.getFile(item.id);
-        if (file.url) {
-            return { id: item.id, url: file.url };
+    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();
         }
-        else if (file.loading || file.failed) {
-            return { id: item.id, url: undefined };
+        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 {
-            return { id: item.id, url: null };
+            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.value.length;
+        return this.view.length;
     }
     // list implements an iterator which maps items to wrapped
     // versions
-    [(_a = REFRESH, _b = exports.DEEP_CHANGE, Symbol.iterator)]() {
+    [Symbol.iterator]() {
+        var _a;
         let index = 0;
+        let length = (_a = this.view) === null || _a === void 0 ? void 0 : _a.length;
         return {
             next: () => {
-                if (index < this.value.length) {
+                if (index < length) {
                     return {
                         value: this.get(index++),
                         done: false,
@@ -533,4 +700,12 @@ class Entity {
     }
 }
 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