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

package/dist/cjs/entities/EntityStore.js

@@ -2,478 +2,350 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EntityStore = void 0;
 const common_1 = require("@verdant-web/common");
+const Entity_js_1 = require("./Entity.js");
+const Disposable_js_1 = require("../utils/Disposable.js");
+const EntityMetadata_js_1 = require("./EntityMetadata.js");
+const OperationBatcher_js_1 = require("./OperationBatcher.js");
+const QueryableStorage_js_1 = require("../queries/QueryableStorage.js");
+const weak_event_1 = require("weak-event");
 const utils_js_1 = require("../files/utils.js");
-const idb_js_1 = require("../idb.js");
-const DocumentFamiliyCache_js_1 = require("./DocumentFamiliyCache.js");
-const DEFAULT_BATCH_KEY = '@@default';
-class EntityStore {
-    get log() {
-        return this.context.log;
-    }
-    get db() {
-        return this.context.documentDb;
-    }
-    get undoHistory() {
-        return this.context.undoHistory;
-    }
-    get schema() {
-        return this.context.schema;
-    }
-    constructor({ context, meta, batchTimeout = 200, files, }) {
-        this.documentFamilyCaches = new Map();
-        this.unsubscribes = [];
-        this._disposed = false;
-        this.currentBatchKey = DEFAULT_BATCH_KEY;
-        this.setContext = (context) => {
-            this.context = context;
+var AbortReason;
+(function (AbortReason) {
+    AbortReason[AbortReason["Reset"] = 0] = "Reset";
+})(AbortReason || (AbortReason = {}));
+class EntityStore extends Disposable_js_1.Disposable {
+    constructor({ ctx, meta, files, }) {
+        super();
+        this.events = {
+            add: new weak_event_1.WeakEvent(),
+            replace: new weak_event_1.WeakEvent(),
+            resetAll: new weak_event_1.WeakEvent(),
         };
-        this.getDocumentSchema = (oid) => {
-            const { collection } = (0, common_1.decomposeOid)(oid);
-            if (!this.schema.collections[collection]) {
-                this.log('warn', `Missing schema for collection: ${collection}`);
-                return { schema: null, readonlyKeys: [] };
-            }
-            const schema = this.schema.collections[collection];
-            return {
-                readonlyKeys: [schema.primaryKey],
-                schema: {
-                    type: 'object',
-                    properties: schema.fields,
-                },
-            };
-        };
-        this.refreshFamilyCache = async (familyCache, dropUnconfirmed = false, dropAll = false) => {
-            // avoid writing to disposed db
-            if (this._disposed) {
-                this.context.log('debug', `EntityStore is disposed, not refreshing ${familyCache.oid} cache`);
+        this.cache = new Map();
+        this.pendingEntityPromises = new Map();
+        // halts the current data queue processing
+        this.abortDataQueueController = new AbortController();
+        this.ongoingResetPromise = null;
+        this.entityFinalizationRegistry = new FinalizationRegistry((oid) => {
+            this.ctx.log('debug', 'Entity GC', oid);
+        });
+        // internal-ish API to load remote / stored data
+        this.addData = async (data) => {
+            if (this.disposed) {
+                this.ctx.log('warn', 'EntityStore is disposed, not adding incoming data');
                 return;
             }
-            // metadata must be loaded from database to initialize family cache
-            const transaction = this.meta.createTransaction([
-                'baselines',
-                'operations',
-            ]);
-            const baselines = [];
-            const operations = [];
-            await Promise.all([
-                this.meta.baselines.iterateOverAllForDocument(familyCache.oid, (baseline) => {
-                    baselines.push(baseline);
-                }, {
-                    transaction,
-                    mode: 'readwrite',
-                }),
-                this.meta.operations.iterateOverAllOperationsForDocument(familyCache.oid, (op) => {
-                    op.confirmed = true;
-                    operations.push(op);
-                }, { transaction, mode: 'readwrite' }),
-            ]);
-            familyCache.reset({
-                operations,
-                baselines,
-                dropExistingUnconfirmed: dropUnconfirmed,
-                dropAll,
-            });
-        };
-        this.openFamilyCache = async (oid) => {
-            const documentOid = (0, common_1.getOidRoot)(oid);
-            let familyCache = this.documentFamilyCaches.get(documentOid);
-            if (!familyCache) {
-                this.context.log('debug', 'opening family cache for', documentOid);
-                // metadata must be loaded from database to initialize family cache
-                familyCache = new DocumentFamiliyCache_js_1.DocumentFamilyCache({
-                    oid: documentOid,
-                    store: this,
-                    context: this.context,
+            // for resets - abort any other changes, reset everything,
+            // then proceed
+            if (data.reset) {
+                this.ctx.log('info', 'Resetting local store to replicate remote synced data - dropping any current transactions');
+                // cancel any other ongoing data - it will all
+                // be replaced by the reset
+                this.abortDataQueueController.abort(AbortReason.Reset);
+                this.abortDataQueueController = new AbortController();
+                this.ongoingResetPromise = this.resetData().finally(() => {
+                    this.ongoingResetPromise = null;
                 });
-                // PROBLEM: because the next line is async, it yields to
-                // queued promises which may need data from this cache,
-                // but the cache is empty. But if we move the set to
-                // after the async, we can clobber an existing cache
-                // with race conditions...
-                // So as an attempt to fix that, I've added a promise
-                // on DocumentFamilyCache which I manually resolve
-                // with setInitialized, then await initializedPromise
-                // further down even if there was a cache hit.
-                // Surely there is a better pattern for this.
-                // FIXME:
-                this.documentFamilyCaches.set(documentOid, familyCache);
-                await this.refreshFamilyCache(familyCache);
-                familyCache.setInitialized();
-                // this.unsubscribes.push(
-                // 	familyCache.subscribe('change:*', this.onEntityChange),
-                // );
-                // TODO: cleanup cache when all documents are disposed
             }
-            await familyCache.initializedPromise;
-            return familyCache;
-        };
-        this.onEntityChange = async (oid) => {
-            // queueMicrotask(() => this.writeDocumentToStorage(oid));
+            // await either the reset we just started, or any that was
+            // in progress when this data came in.
+            if (this.ongoingResetPromise) {
+                this.ctx.log('debug', 'Waiting for ongoing reset to complete');
+                await this.ongoingResetPromise;
+                this.ctx.log('debug', 'Ongoing reset complete');
+            }
+            await this.processData(data);
         };
-        this.writeDocumentToStorage = async (oid) => {
-            if (this._disposed) {
-                this.log('warn', 'EntityStore is disposed, not writing to storage');
+        this.resetData = async () => {
+            if (this.disposed) {
+                this.ctx.log('warn', 'EntityStore is disposed, not resetting local data');
                 return;
             }
-            const rootOid = (0, common_1.getOidRoot)(oid);
-            const { id, collection } = (0, common_1.decomposeOid)(rootOid);
-            const entity = await this.get(rootOid);
-            if (this._disposed) {
-                this.log('warn', 'EntityStore is disposed, not writing to storage');
+            await this.meta.reset();
+            await this.queryableStorage.reset();
+            this.events.resetAll.invoke(this);
+        };
+        this.processData = async (data) => {
+            var _a, _b, _c;
+            if (this.disposed) {
+                this.ctx.log('warn', 'EntityStore is disposed, not processing incoming data');
                 return;
             }
-            const snapshot = entity === null || entity === void 0 ? void 0 : entity.getSnapshot();
-            if (snapshot) {
-                const stored = (0, common_1.getIndexValues)(this.schema.collections[collection], snapshot);
-                try {
-                    const tx = this.db.transaction(collection, 'readwrite');
-                    const store = tx.objectStore(collection);
-                    await (0, idb_js_1.storeRequestPromise)(store.put(stored));
-                    this.log('info', '📝', 'wrote', collection, id, 'to storage', stored);
+            const baselines = (_a = data === null || data === void 0 ? void 0 : data.baselines) !== null && _a !== void 0 ? _a : [];
+            const operations = (_b = data === null || data === void 0 ? void 0 : data.operations) !== null && _b !== void 0 ? _b : [];
+            this.ctx.log('debug', 'Processing incoming data', {
+                operations: operations.length,
+                baselines: baselines.length,
+                reset: !!data.reset,
+            });
+            const allDocumentOids = Array.from(new Set(baselines
+                .map((b) => (0, common_1.getOidRoot)(b.oid))
+                .concat(operations.map((o) => (0, common_1.getOidRoot)(o.oid)))));
+            const baselinesGroupedByOid = (0, common_1.groupBaselinesByRootOid)(baselines);
+            const operationsGroupedByOid = (0, common_1.groupPatchesByRootOid)(operations);
+            this.ctx.log('debug', 'Applying data to live entities');
+            // synchronously add/replace data in any open entities via eventing
+            for (const oid of allDocumentOids) {
+                const baselines = baselinesGroupedByOid[oid];
+                const operations = (_c = operationsGroupedByOid[oid]) !== null && _c !== void 0 ? _c : [];
+                const groupedOperations = (0, common_1.groupPatchesByOid)(operations);
+                // what happens if an entity is being hydrated
+                // while this is happening? - we wait for the hydration promise
+                // to complete, then invoke the event
+                const event = data.reset ? this.events.replace : this.events.add;
+                const hydrationPromise = this.pendingEntityPromises.get(oid);
+                if (hydrationPromise) {
+                    hydrationPromise.then(() => {
+                        event.invoke(this, {
+                            oid,
+                            baselines,
+                            operations: groupedOperations,
+                            isLocal: false,
+                        });
+                    });
                 }
-                catch (err) {
-                    // if the document can't be written, something's very wrong :(
-                    // log the error and move on...
-                    this.log("⚠️ CRITICAL: possibly corrupt data couldn't be written to queryable storage. This is probably a bug in verdant! Please report at https://github.com/a-type/verdant/issues", '\n', 'Invalid data:', JSON.stringify(stored));
+                else {
+                    if (this.cache.has(oid)) {
+                        this.ctx.log('debug', 'Cache has', oid, ', an event should follow.');
+                    }
+                    event.invoke(this, {
+                        oid,
+                        baselines,
+                        operations: groupedOperations,
+                        isLocal: false,
+                    });
                 }
             }
-            else {
-                const tx = this.db.transaction(collection, 'readwrite');
-                const store = tx.objectStore(collection);
-                await (0, idb_js_1.storeRequestPromise)(store.delete(id));
-                this.log('info', '❌', 'deleted', collection, id, 'from storage');
+            const abortOptions = {
+                abort: this.abortDataQueueController.signal,
+            };
+            // then, asynchronously add to the database
+            await this.meta.insertData(data, abortOptions);
+            // FIXME: entities hydrated here are not seeing
+            // the operations just inserted above!!
+            // IDEA: can we coordinate here with hydrate promises
+            // based on affected OIDs?
+            // recompute all affected documents for querying
+            const entities = await Promise.all(allDocumentOids.map(async (oid) => {
+                const entity = await this.hydrate(oid, abortOptions);
+                // if the entity is not found, we return a stub that
+                // indicates it's deleted and should be cleared
+                return (entity !== null && entity !== void 0 ? entity : {
+                    oid,
+                    getSnapshot() {
+                        return null;
+                    },
+                });
+            }));
+            try {
+                await this.queryableStorage.saveEntities(entities, abortOptions);
             }
-        };
-        this.get = async (oid) => {
-            const familyCache = await this.openFamilyCache(oid);
-            const { schema, readonlyKeys } = this.getDocumentSchema(oid);
-            if (!schema) {
-                return null;
+            catch (err) {
+                if (this.disposed) {
+                    this.ctx.log('warn', 'Error saving entities to queryable storage - EntityStore is disposed', err);
+                }
+                else {
+                    this.ctx.log('error', 'Error saving entities to queryable storage', err);
+                }
             }
-            return familyCache.getEntity({ oid, fieldSchema: schema, readonlyKeys });
         };
-        /**
-         * Advanced usage!
-         * Immediately returns an entity if it exists in the memory cache. An
-         * entity would be cached if it has been retrieved by a live query.
-         */
-        this.getCached = (oid) => {
-            const cache = this.documentFamilyCaches.get(oid);
-            if (cache) {
-                const { schema, readonlyKeys } = this.getDocumentSchema(oid);
-                if (!schema) {
+        // internal-ish API for creating Entities from OIDs
+        // when query results come in
+        this.hydrate = async (oid, opts) => {
+            if (!(0, common_1.isRootOid)(oid)) {
+                throw new Error('Cannot hydrate non-root entity');
+            }
+            if (this.cache.has(oid)) {
+                this.ctx.log('debug', 'Hydrating entity from cache', oid);
+                const cached = this.cache.get(oid);
+                if (cached) {
+                    const entity = cached.deref();
+                    if (entity) {
+                        if (entity.deleted) {
+                            return null;
+                        }
+                        return entity;
+                    }
+                    else {
+                        this.ctx.log('debug', "Removing GC'd entity from cache", oid);
+                        this.cache.delete(oid);
+                    }
+                }
+            }
+            // we don't want to hydrate two entities in parallel, so
+            // we use a promise to ensure that only one is ever
+            // constructed at a time
+            const pendingPromise = this.pendingEntityPromises.get(oid);
+            if (!pendingPromise) {
+                this.ctx.log('debug', 'Hydrating entity from storage', oid);
+                const entity = this.constructEntity(oid);
+                if (!entity) {
                     return null;
                 }
-                return cache.getEntity({ oid, fieldSchema: schema, readonlyKeys });
+                const pendingPromise = this.loadEntity(entity, opts);
+                pendingPromise.finally(() => {
+                    this.pendingEntityPromises.delete(oid);
+                });
+                this.pendingEntityPromises.set(oid, pendingPromise);
+                return pendingPromise;
+            }
+            else {
+                this.ctx.log('debug', 'Waiting for entity hydration', oid);
+                return pendingPromise;
             }
-            return null;
         };
+        this.destroy = async () => {
+            this.dispose();
+            await this.batcher.flushAll();
+        };
+        // public APIs for manipulating entities
         /**
-         * Creates a new document and returns an Entity for it. The created
-         * document is submitted to storage and sync.
+         * Creates a new Entity with the given initial data.
          */
-        this.create = async (initial, oid, options) => {
-            // remove all OID associations from initial data
+        this.create = async (initial, oid, { undoable = true } = {}) => {
+            this.ctx.log('debug', 'Creating new entity', oid);
+            const { collection } = (0, common_1.decomposeOid)(oid);
+            // remove any OID associations from the initial data
             (0, common_1.removeOidsFromAllSubObjects)(initial);
-            // first grab any file and replace them with refs
+            // grab files and replace them with refs
             const processed = (0, utils_js_1.processValueFiles)(initial, this.files.add);
             (0, common_1.assignOid)(processed, oid);
-            const operations = this.meta.patchCreator.createInitialize(processed, oid);
-            const familyCache = await this.openFamilyCache(oid);
-            familyCache.insertLocalOperations(operations);
-            // don't enqueue these, submit as distinct operation.
-            // we do this so it can be immediately queryable from storage...
-            // only holding it in memory would introduce lag before it shows up
-            // in other queries.
-            await this.submitOperations(operations, options);
-            const { schema, readonlyKeys } = this.getDocumentSchema(oid);
-            if (!schema) {
-                throw new Error(`Cannot create a document in the ${(0, common_1.decomposeOid)(oid).collection} collection; it is not defined in the current schema version.`);
+            // creating a new Entity with no data, then preloading the operations
+            const entity = this.constructEntity(oid);
+            if (!entity) {
+                throw new Error(`Could not put new document: no schema exists for collection ${collection}`);
             }
-            return familyCache.getEntity({ oid, fieldSchema: schema, readonlyKeys });
-        };
-        this.addOperationsToOpenCaches = async (operations, info) => {
-            const operationsByOid = (0, common_1.groupPatchesByRootOid)(operations);
-            const oids = Object.keys(operationsByOid);
-            oids.forEach((oid) => {
-                const familyCache = this.documentFamilyCaches.get(oid);
-                if (familyCache) {
-                    this.log('adding', info.confirmed ? 'confirmed' : 'unconfirmed', 'operations to cache', oid, operationsByOid[oid].length);
-                    if (info.isLocal) {
-                        familyCache.insertLocalOperations(operationsByOid[oid]);
-                    }
-                    else {
-                        familyCache.insertOperations(operationsByOid[oid], info);
-                    }
-                }
+            const operations = this.meta.patchCreator.createInitialize(processed, oid);
+            await this.batcher.commitOperations(operations, {
+                undoable: !!undoable,
+                source: entity,
+            });
+            // TODO: what happens if you create an entity with an OID that already
+            // exists?
+            // we still need to synchronously add the initial operations to the Entity
+            // even though they are flowing through the system
+            // TODO: this could be better aligned to avoid grouping here
+            const operationsGroupedByOid = (0, common_1.groupPatchesByOid)(operations);
+            this.events.add.invoke(this, {
+                operations: operationsGroupedByOid,
+                isLocal: true,
+                oid,
             });
+            this.cache.set(oid, this.ctx.weakRef(entity));
+            return entity;
         };
-        this.addBaselinesToOpenCaches = async (baselines, info) => {
-            const baselinesByOid = (0, common_1.groupBaselinesByRootOid)(baselines);
-            const oids = Object.keys(baselinesByOid);
+        this.deleteAll = async (oids, options) => {
+            this.ctx.log('info', 'Deleting documents', oids);
+            (0, common_1.assert)(oids.every((oid) => oid === (0, common_1.getOidRoot)(oid)), 'Only root documents may be deleted via client methods');
+            const allOids = await Promise.all(oids.flatMap(async (oid) => {
+                var _a;
+                const entity = await this.hydrate(oid);
+                return (_a = entity === null || entity === void 0 ? void 0 : entity.__getFamilyOids__()) !== null && _a !== void 0 ? _a : [];
+            }));
+            // remove the entities from cache
             oids.forEach((oid) => {
-                const cache = this.documentFamilyCaches.get(oid);
-                if (cache) {
-                    this.log('adding', 'baselines to cache', oid, baselinesByOid[oid].length);
-                    cache.insertBaselines(baselinesByOid[oid], info);
-                }
+                this.cache.delete(oid);
+                this.ctx.log('debug', 'Deleted document from cache', oid);
+            });
+            // create the delete patches and wait for them to be applied
+            const operations = this.meta.patchCreator.createDeleteAll(allOids.flat());
+            await this.batcher.commitOperations(operations, {
+                undoable: (options === null || options === void 0 ? void 0 : options.undoable) === undefined ? true : options.undoable,
             });
         };
-        this.addDataToOpenCaches = ({ baselines, operations, reset, isLocal, }) => {
-            var _a, _b, _c, _d;
-            const baselinesByDocumentOid = (0, common_1.groupBaselinesByRootOid)(baselines);
-            const operationsByDocumentOid = (0, common_1.groupPatchesByRootOid)(operations);
-            const allDocumentOids = Array.from(new Set(Object.keys(baselinesByDocumentOid).concat(Object.keys(operationsByDocumentOid))));
-            for (const oid of allDocumentOids) {
-                const familyCache = this.documentFamilyCaches.get(oid);
-                if (familyCache) {
-                    familyCache.addData({
-                        operations: operationsByDocumentOid[oid] || [],
-                        baselines: baselinesByDocumentOid[oid] || [],
-                        reset,
-                        isLocal,
-                    });
-                    this.log('debug', 'Added data to cache for', oid, (_b = (_a = operationsByDocumentOid[oid]) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0, 'operations', (_d = (_c = baselinesByDocumentOid[oid]) === null || _c === void 0 ? void 0 : _c.length) !== null && _d !== void 0 ? _d : 0, 'baselines');
-                }
-                else {
-                    this.log('debug', 'Could not add data to cache for', oid, 'because it is not open');
-                }
-            }
-            return allDocumentOids;
+        this.delete = async (oid, options) => {
+            return this.deleteAll([oid], options);
         };
-        this.addData = async ({ operations, baselines, reset, }) => {
-            if (this._disposed) {
-                this.log('warn', 'EntityStore is disposed, not adding data');
-                return;
-            }
-            // convert operations to tagged operations with confirmed = false
-            // while we process and store them. this is in-place so as to
-            // not allocate a bunch of objects...
-            const taggedOperations = operations;
-            for (const op of taggedOperations) {
-                op.confirmed = false;
-            }
-            let allDocumentOids = [];
-            // in a reset scenario, it only makes things confusing if we
-            // optimistically apply incoming operations, since the local
-            // history is out of sync
-            if (reset) {
-                this.log('Resetting local store to replicate remote synced data', baselines.length, 'baselines, and', operations.length, 'operations');
-                await this.meta.reset();
-                await this.resetStoredDocuments();
-                allDocumentOids = Array.from(new Set(baselines
-                    .map((b) => (0, common_1.getOidRoot)(b.oid))
-                    .concat(operations.map((o) => (0, common_1.getOidRoot)(o.oid)))));
-            }
-            else {
-                // first, synchronously add data to any open caches for immediate change propagation
-                allDocumentOids = this.addDataToOpenCaches({
-                    operations: taggedOperations,
-                    baselines,
-                    reset,
-                });
-            }
-            // then, asynchronously add data to storage
-            await this.meta.insertRemoteBaselines(baselines);
-            await this.meta.insertRemoteOperations(operations);
-            if (reset) {
-                await this.refreshAllCaches(true, true);
-            }
-            // recompute all affected documents for querying
-            for (const oid of allDocumentOids) {
-                await this.writeDocumentToStorage(oid);
+        this.getCollectionSchema = (collectionName) => {
+            const schema = this.ctx.schema.collections[collectionName];
+            if (!schema) {
+                this.ctx.log('warn', `Missing schema for collection: ${collectionName}`);
+                return {
+                    schema: null,
+                    readonlyKeys: [],
+                };
             }
-            // notify active queries
-            const affectedCollections = Array.from(new Set(allDocumentOids.map((oid) => (0, common_1.decomposeOid)(oid).collection)));
-            this.context.log('changes to collections', affectedCollections);
-            this.context.entityEvents.emit('collectionsChanged', affectedCollections);
-        };
-        this.addLocalOperations = async (operations) => {
-            this.log('Adding local operations', operations.length);
-            this.addOperationsToOpenCaches(operations, {
-                isLocal: true,
-                confirmed: false,
-            });
-            this.operationBatcher.add({
-                key: this.currentBatchKey,
-                items: operations,
-            });
-        };
-        this.batch = ({ undoable = true, batchName = (0, common_1.generateId)(), max = null, timeout = this.defaultBatchTimeout, } = {}) => {
-            const internalBatch = this.operationBatcher.add({
-                key: batchName,
-                max,
-                timeout,
-                items: [],
-                userData: { undoable },
-            });
-            const externalApi = {
-                run: (fn) => {
-                    // while the provided function runs, operations are forwarded
-                    // to the new batch instead of default. this relies on the function
-                    // being synchronous.
-                    this.currentBatchKey = batchName;
-                    fn();
-                    this.currentBatchKey = DEFAULT_BATCH_KEY;
-                    return externalApi;
-                },
-                flush: async () => {
-                    // before running a batch, the default operations must be flushed
-                    // this better preserves undo history behavior...
-                    // if we left the default batch open while flushing a named batch,
-                    // then the default batch would be flushed after the named batch,
-                    // and the default batch could contain operations both prior and
-                    // after the named batch. this would result in a confusing undo
-                    // history where the first undo might reverse changes before and
-                    // after a set of other changes.
-                    await this.operationBatcher.flush(DEFAULT_BATCH_KEY);
-                    return internalBatch.flush();
-                },
-                discard: () => {
-                    this.operationBatcher.discard(batchName);
+            return {
+                // convert to object schema for compatibility
+                schema: {
+                    type: 'object',
+                    nullable: false,
+                    properties: schema.fields,
                 },
+                readonlyKeys: [schema.primaryKey],
             };
-            return externalApi;
         };
         /**
-         * @deprecated use `batch` instead
+         * Constructs an entity from an OID, but does not load it.
          */
-        this.flushPatches = async () => {
-            await this.operationBatcher.flush(this.currentBatchKey);
-        };
-        this.flushAllBatches = async () => {
-            await Promise.all(this.operationBatcher.flushAll());
-        };
-        this.flushOperations = async (operations, batchKey, meta) => {
-            if (!operations.length)
-                return;
-            this.log('Flushing operations', operations.length, 'to storage / sync');
-            // rewrite timestamps of all operations to now - this preserves
-            // the linear history of operations which are sent to the server.
-            // even if multiple batches are spun up in parallel and flushed
-            // after delay, the final operations in each one should reflect
-            // when the batch flushed, not when the changes were made.
-            // This also corresponds to user-observed behavior, since unconfirmed
-            // operations are applied universally after confirmed operations locally,
-            // so even operations which were made before a remote operation but
-            // have not been confirmed yet will appear to come after the remote one
-            // despite the provisional timestamp being earlier (see DocumentFamilyCache#computeView)
-            for (const op of operations) {
-                op.timestamp = this.meta.now;
-            }
-            await this.submitOperations(operations, meta);
-        };
-        this.submitOperations = async (operations, { undoable = true } = {}) => {
-            if (undoable) {
-                // FIXME: this is too slow and needs to be optimized.
-                this.undoHistory.addUndo(await this.createUndo(operations));
-            }
-            await this.meta.insertLocalOperation(operations);
-            // confirm the operations
-            this.addDataToOpenCaches({ operations, baselines: [] });
-            // recompute all affected documents for querying
-            const allDocumentOids = Array.from(new Set(operations.map((op) => (0, common_1.getOidRoot)(op.oid))));
-            for (const oid of allDocumentOids) {
-                await this.writeDocumentToStorage(oid);
-            }
-            // TODO: find a more efficient and straightforward way to update affected
-            // queries. Move to Metadata?
-            const affectedCollections = new Set(operations.map(({ oid }) => (0, common_1.decomposeOid)(oid).collection));
-            this.context.log('changes to collections', affectedCollections);
-            this.context.entityEvents.emit('collectionsChanged', Array.from(affectedCollections));
-        };
-        this.getInverseOperations = async (ops) => {
-            const grouped = (0, common_1.groupPatchesByIdentifier)(ops);
-            const inverseOps = [];
-            const getNow = () => this.meta.now;
-            for (const [oid, patches] of Object.entries(grouped)) {
-                const familyCache = await this.openFamilyCache(oid);
-                let { view, deleted } = familyCache.computeConfirmedView(oid);
-                const inverse = (0, common_1.getUndoOperations)(oid, view, patches, getNow);
-                inverseOps.unshift(...inverse);
-            }
-            return inverseOps;
-        };
-        this.createUndo = async (ops) => {
-            const inverseOps = await this.getInverseOperations(ops);
-            return async () => {
-                const redo = await this.createUndo(inverseOps);
-                await this.submitOperations(inverseOps.map((op) => {
-                    op.timestamp = this.meta.now;
-                    return op;
-                }), 
-                // undos should not generate their own undo operations
-                // since they already calculate redo as the inverse.
-                { undoable: false });
-                return redo;
-            };
-        };
-        this.delete = async (oid, options) => {
-            (0, common_1.assert)(oid === (0, common_1.getOidRoot)(oid), 'Only root documents may be deleted via client methods');
-            // we need to get all sub-object oids to delete alongside the root
-            const allOids = await this.meta.getAllDocumentRelatedOids(oid);
-            const patches = this.meta.patchCreator.createDeleteAll(allOids);
-            // don't enqueue these, submit as distinct operation
-            await this.submitOperations(patches, options);
-        };
-        this.deleteAll = async (oids, options) => {
-            const allOids = await Promise.all(oids.map((oid) => this.meta.getAllDocumentRelatedOids(oid)));
-            const patches = this.meta.patchCreator.createDeleteAll(allOids.flat());
-            // don't enqueue these, submit as distinct operation
-            await this.submitOperations(patches, options);
-        };
-        this.reset = async () => {
-            this.context.log('warn', 'Resetting local database');
-            await this.resetStoredDocuments();
-            await this.refreshAllCaches(true);
-            // this.context.entityEvents.emit(
-            // 	'collectionsChanged',
-            // 	Object.keys(this.schema.collections),
-            // );
-        };
-        this.destroy = async () => {
-            this._disposed = true;
-            for (const unsubscribe of this.unsubscribes) {
-                unsubscribe();
+        this.constructEntity = (oid) => {
+            const { collection } = (0, common_1.decomposeOid)(oid);
+            const { schema, readonlyKeys } = this.getCollectionSchema(collection);
+            if (!schema) {
+                return null;
             }
-            for (const cache of this.documentFamilyCaches.values()) {
-                cache.dispose();
+            if (this.disposed) {
+                throw new Error('Cannot hydrate entity after store has been disposed');
             }
-            this.documentFamilyCaches.clear();
-            await this.flushAllBatches();
-        };
-        this.handleRebase = (baselines) => {
-            this.log('debug', 'Reacting to rebases', baselines.length);
-            // update any open caches with new baseline. this will automatically
-            // drop operations before the baseline.
-            this.addBaselinesToOpenCaches(baselines, { isLocal: true });
+            const metadataFamily = new EntityMetadata_js_1.EntityFamilyMetadata({
+                ctx: this.ctx,
+                onPendingOperations: this.onPendingOperations,
+                rootOid: oid,
+            });
+            // this is created synchronously so it's immediately available
+            // to begin capturing incoming data.
+            return new Entity_js_1.Entity({
+                ctx: this.ctx,
+                oid,
+                schema,
+                readonlyKeys,
+                files: this.files,
+                metadataFamily: metadataFamily,
+                patchCreator: this.meta.patchCreator,
+                events: this.events,
+            });
         };
-        this.resetStoredDocuments = async () => {
-            const tx = this.db.transaction(Object.keys(this.schema.collections), 'readwrite');
-            for (const collection of Object.keys(this.schema.collections)) {
-                const store = tx.objectStore(collection);
-                await (0, idb_js_1.storeRequestPromise)(store.clear());
-            }
+        this.onPendingOperations = (operations) => {
+            this.batcher.addOperations(operations);
         };
-        this.refreshAllCaches = async (dropUnconfirmed = false, dropAll = false) => {
-            for (const [_, cache] of this.documentFamilyCaches) {
-                await this.refreshFamilyCache(cache, dropUnconfirmed, dropAll);
+        /**
+         * Loads initial Entity data from storage
+         */
+        this.loadEntity = async (entity, opts) => {
+            const { operations, baselines } = await this.meta.getDocumentData(entity.oid, opts);
+            if (!baselines.length && !Object.keys(operations).length) {
+                this.ctx.log('debug', 'No data found for entity', entity.oid);
+                return null;
             }
+            this.ctx.log('debug', 'Loaded entity from storage', entity.oid);
+            this.events.replace.invoke(this, {
+                oid: entity.oid,
+                baselines,
+                operations,
+                isLocal: false,
+            });
+            // only set the cache after loading.
+            // TODO: is this cache/promise stuff redundant?
+            this.cache.set(entity.oid, this.ctx.weakRef(entity));
+            this.entityFinalizationRegistry.register(entity, entity.oid);
+            return entity;
         };
-        this.context = context;
-        this.defaultBatchTimeout = batchTimeout;
+        this.ctx = ctx;
         this.meta = meta;
         this.files = files;
-        this.operationBatcher = new common_1.Batcher(this.flushOperations);
-        // initialize default batch
-        this.operationBatcher.add({
-            key: DEFAULT_BATCH_KEY,
-            items: [],
-            max: 100,
-            timeout: batchTimeout,
-            userData: { undoable: true },
+        this.queryableStorage = new QueryableStorage_js_1.QueryableStorage({ ctx });
+        this.batcher = new OperationBatcher_js_1.OperationBatcher({
+            ctx,
+            meta,
+            entities: this,
         });
-        this.unsubscribes.push(this.meta.subscribe('rebase', this.handleRebase));
+    }
+    // expose batch APIs
+    get batch() {
+        return this.batcher.batch;
+    }
+    get flushAllBatches() {
+        return this.batcher.flushAll;
     }
 }
 exports.EntityStore = EntityStore;