@mocanvas/store 1.0.0 → 4.0.0

package/dist/index.js

@@ -1,6 +1,7 @@
 import { nanoid } from 'nanoid';
 import { generateKeyBetween, generateNKeysBetween } from 'fractional-indexing';
-import { computed, unsafe__withoutCapture, atom, transact } from '@mocanvas/state';
+import { computed, unsafe__withoutCapture, isUninitialized, RESET_VALUE, withDiff, atom, transact } from '@mocanvas/state';
+export { AtomMap, AtomSet } from '@mocanvas/state';
 
 // src/ids.ts
 var UNIQUE_ID_LENGTH = 21;
@@ -368,6 +369,25 @@ function applyMigrationToStore(migration, store, direction) {
   return store;
 }
 
+// src/legacy.ts
+function isSerializedSchemaV1(schema) {
+  return schema.schemaVersion === 1;
+}
+var MigrationFailureReason = {
+  /** The persisted schema names a sequence version higher than this schema knows. */
+  TargetVersionTooNew: "target-version-too-new",
+  /** The persisted data is older than the oldest migration that survives. */
+  TargetVersionTooOld: "target-version-too-old",
+  /** A record's type is not registered in this schema and cannot be migrated. */
+  UnrecognizedType: "unrecognized-type",
+  /** A migration function threw. */
+  MigrationError: "migration-error",
+  /** The persisted schema itself is malformed. */
+  IncompatibleSubtype: "incompatible-subtype",
+  /** The persisted schema version is not one this store understands. */
+  UnknownSchemaVersion: "unknown-schema-version"
+};
+
 // src/StoreSchema.ts
 var StoreSchema = class _StoreSchema {
   constructor(types, options) {
@@ -437,7 +457,7 @@ var StoreSchema = class _StoreSchema {
       throw error;
     }
   }
-  /** The current version of every sequence. */
+  /** The current version of every sequence. Always the v2 shape — mocanvas never writes v1. */
   serialize() {
     const sequences = {};
     for (const sequence of Object.values(this.migrations)) {
@@ -457,13 +477,21 @@ var StoreSchema = class _StoreSchema {
    * do not are ignored with a warning.
    */
   getMigrationsSince(persistedSchema) {
+    if (isSerializedSchemaV1(persistedSchema)) {
+      return {
+        type: "error",
+        reason: "Schema version 1 (per-record-type versions) predates migration sequences and cannot be migrated automatically"
+      };
+    }
     if (persistedSchema.schemaVersion !== 2) {
       return {
         type: "error",
         reason: `Unsupported schema version ${String(persistedSchema.schemaVersion)}`
       };
     }
-    const persisted = persistedSchema.sequences ?? {};
+    return this.migrationsSince(persistedSchema.sequences ?? {});
+  }
+  migrationsSince(persisted) {
     for (const sequenceId of Object.keys(persisted)) {
       if (!this.migrations[sequenceId]) {
         console.warn(`[store] ignoring unknown migration sequence "${sequenceId}" in persisted schema`);
@@ -543,6 +571,36 @@ var StoreSchema = class _StoreSchema {
   }
 };
 
+// src/query.ts
+function matchesQueryValue(matcher, value) {
+  if ("eq" in matcher) return Object.is(matcher.eq, value);
+  if ("neq" in matcher) return !Object.is(matcher.neq, value);
+  return typeof value === "number" && value > matcher.gt;
+}
+function matchesQuery(query, record) {
+  for (const key of Object.keys(query)) {
+    const matcher = query[key];
+    if (matcher === void 0) continue;
+    if (!matchesQueryValue(matcher, record[key])) return false;
+  }
+  return true;
+}
+function getIndexablePropertyOf(query) {
+  for (const key of Object.keys(query)) {
+    const matcher = query[key];
+    if (matcher && "eq" in matcher) return key;
+  }
+  return void 0;
+}
+function applyCollectionDiff(set, diff) {
+  if (diff.removed) for (const value of diff.removed) set.delete(value);
+  if (diff.added) for (const value of diff.added) set.add(value);
+  return set;
+}
+function isCollectionDiffEmpty(diff) {
+  return (diff.added?.size ?? 0) === 0 && (diff.removed?.size ?? 0) === 0;
+}
+
 // src/Store.ts
 var StoreSideEffects = class {
   byType = /* @__PURE__ */ new Map();
@@ -703,6 +761,9 @@ function freezeRecord(record) {
   if (isPlainObject(r["meta"]) && !Object.isFrozen(r["meta"])) Object.freeze(r["meta"]);
   return Object.freeze(record);
 }
+function toPredicate(filter) {
+  return typeof filter === "function" ? filter : (record) => matchesQuery(filter, record);
+}
 var StoreQueries = class {
   constructor(store) {
     this.store = store;
@@ -710,8 +771,21 @@ var StoreQueries = class {
   store;
   idsCache = /* @__PURE__ */ new Map();
   recordsCache = /* @__PURE__ */ new Map();
-  /** The set of ids of every record of `typeName`. Maintained incrementally. */
-  ids(typeName) {
+  indexCache = /* @__PURE__ */ new Map();
+  historyCache = /* @__PURE__ */ new Map();
+  /**
+   * The set of ids of every record of `typeName`, optionally narrowed by a
+   * filter. Maintained incrementally.
+   */
+  ids(typeName, filter) {
+    if (filter) {
+      const records = this.records(typeName, filter);
+      return computed(`store:${this.store.id}:ids:${typeName}:filtered`, () => {
+        const set = /* @__PURE__ */ new Set();
+        for (const record of records.get()) set.add(record.id);
+        return set;
+      });
+    }
     let c = this.idsCache.get(typeName);
     if (!c) {
       const index = this.store.getTypeIndex(typeName);
@@ -723,8 +797,16 @@ var StoreQueries = class {
     }
     return c;
   }
-  /** Every record of `typeName`, in insertion order. */
-  records(typeName) {
+  /**
+   * Every record of `typeName`, in insertion order, optionally narrowed by a
+   * filter.
+   *
+   * A {@link QueryExpression} with an `eq` clause is answered from the index on
+   * that property, so a page with ten thousand shapes does not have to be
+   * walked to find the twelve on one frame.
+   */
+  records(typeName, filter) {
+    if (filter) return this.filteredRecords(typeName, filter);
     let c = this.recordsCache.get(typeName);
     if (!c) {
       const ids = this.ids(typeName);
@@ -740,19 +822,166 @@ var StoreQueries = class {
     }
     return c;
   }
-  /** The first record of `typeName` matching `predicate` (or the first record, when omitted). */
-  record(typeName, predicate) {
-    const records = this.records(typeName);
-    return computed(`store:${this.store.id}:record:${typeName}`, () => {
-      const all = records.get();
-      if (!predicate) return all[0];
-      for (const record of all) if (predicate(record)) return record;
-      return void 0;
-    });
+  filteredRecords(typeName, filter) {
+    const predicate = toPredicate(filter);
+    const indexedProperty = typeof filter === "function" ? void 0 : getIndexablePropertyOf(filter);
+    if (indexedProperty !== void 0) {
+      const clause = filter[indexedProperty];
+      const wanted = clause && "eq" in clause ? clause.eq : void 0;
+      const index = this.index(typeName, indexedProperty);
+      return computed(`store:${this.store.id}:records:${typeName}:${String(indexedProperty)}`, () => {
+        const bucket = index.get().get(wanted);
+        if (!bucket) return [];
+        const result = [];
+        for (const id of bucket) {
+          const record = this.store.get(id);
+          if (record !== void 0 && predicate(record)) result.push(record);
+        }
+        return result;
+      });
+    }
+    const all = this.records(typeName);
+    return computed(`store:${this.store.id}:records:${typeName}:filtered`, () => all.get().filter(predicate));
+  }
+  /** The first record of `typeName` matching `filter` (or the first record, when omitted). */
+  record(typeName, filter) {
+    const records = filter ? this.filteredRecords(typeName, filter) : this.records(typeName);
+    return computed(`store:${this.store.id}:record:${typeName}`, () => records.get()[0]);
   }
   /** Non-reactive filter over the records of `typeName`. */
-  exec(typeName, predicate) {
-    return unsafe__withoutCapture(() => this.records(typeName).get().filter(predicate));
+  exec(typeName, filter) {
+    return unsafe__withoutCapture(() => this.filteredRecords(typeName, filter).get());
+  }
+  /**
+   * A live index from the values of one property to the ids of the records
+   * holding them.
+   *
+   * The index is cached per type and property, and it carries diffs: a
+   * dependent that already built something from it can ask
+   * `index.getDiffSince(epoch)` and patch, instead of walking the whole map
+   * again. That is what makes "every shape whose parentId is this frame" cheap
+   * enough to recompute on every pointer move.
+   */
+  index(typeName, property) {
+    const key = `${typeName}:${property}`;
+    const cached = this.indexCache.get(key);
+    if (cached) return cached;
+    const history = this.filterHistory(typeName);
+    const index = computed(
+      `store:${this.store.id}:index:${key}`,
+      (previous, lastComputedEpoch) => {
+        if (isUninitialized(previous)) {
+          history.get();
+          return this.buildIndex(typeName, property);
+        }
+        const diffs = history.getDiffSince(lastComputedEpoch);
+        if (diffs === RESET_VALUE) return this.buildIndex(typeName, property);
+        const nextMap = new Map(previous);
+        const indexDiff = /* @__PURE__ */ new Map();
+        let changed = false;
+        const remove = (value, id) => {
+          const bucket = nextMap.get(value);
+          if (!bucket?.has(id)) return;
+          const next = new Set(bucket);
+          next.delete(id);
+          if (next.size === 0) nextMap.delete(value);
+          else nextMap.set(value, next);
+          const entry = indexDiff.get(value) ?? {};
+          (entry.removed ??= /* @__PURE__ */ new Set()).add(id);
+          indexDiff.set(value, entry);
+          changed = true;
+        };
+        const add = (value, id) => {
+          const bucket = nextMap.get(value);
+          if (bucket?.has(id)) return;
+          nextMap.set(value, new Set(bucket).add(id));
+          const entry = indexDiff.get(value) ?? {};
+          (entry.added ??= /* @__PURE__ */ new Set()).add(id);
+          indexDiff.set(value, entry);
+          changed = true;
+        };
+        for (const diff of diffs) {
+          for (const id in diff.added) {
+            const record = diff.added[id];
+            if (record?.typeName === typeName) add(record[property], record.id);
+          }
+          for (const id in diff.updated) {
+            const [before, after] = diff.updated[id];
+            if (after.typeName !== typeName) continue;
+            if (Object.is(before[property], after[property])) continue;
+            remove(before[property], before.id);
+            add(after[property], after.id);
+          }
+          for (const id in diff.removed) {
+            const record = diff.removed[id];
+            if (record?.typeName === typeName) remove(record[property], record.id);
+          }
+        }
+        if (!changed) return previous;
+        return withDiff(nextMap, indexDiff);
+      },
+      { historyLength: 128 }
+    );
+    this.indexCache.set(key, index);
+    return index;
+  }
+  buildIndex(typeName, property) {
+    const map = /* @__PURE__ */ new Map();
+    for (const record of this.records(typeName).get()) {
+      const value = record[property];
+      const bucket = map.get(value);
+      if (bucket) bucket.add(record.id);
+      else map.set(value, /* @__PURE__ */ new Set([record.id]));
+    }
+    return map;
+  }
+  /**
+   * The store's history, narrowed to one record type.
+   *
+   * Its *value* is only a counter — what it is for is the diffs it carries.
+   * `filterHistory("shape").getDiffSince(epoch)` is every change to shapes
+   * since `epoch`, with changes to other record types dropped, which is how a
+   * derived collection stays incremental without re-reading the store.
+   */
+  filterHistory(typeName) {
+    const cached = this.historyCache.get(typeName);
+    if (cached) return cached;
+    const filtered = computed(
+      `store:${this.store.id}:history:${typeName}`,
+      (previous, lastComputedEpoch) => {
+        const epoch = this.store.history.get();
+        if (isUninitialized(previous)) return epoch;
+        const diffs = this.store.history.getDiffSince(lastComputedEpoch);
+        if (diffs === RESET_VALUE) return epoch;
+        const merged = createEmptyRecordsDiff();
+        let any = false;
+        for (const diff of diffs) {
+          for (const id in diff.added) {
+            const record = diff.added[id];
+            if (record.typeName !== typeName) continue;
+            merged.added[id] = record;
+            any = true;
+          }
+          for (const id in diff.updated) {
+            const pair = diff.updated[id];
+            if (pair[1].typeName !== typeName) continue;
+            merged.updated[id] = pair;
+            any = true;
+          }
+          for (const id in diff.removed) {
+            const record = diff.removed[id];
+            if (record.typeName !== typeName) continue;
+            merged.removed[id] = record;
+            any = true;
+          }
+        }
+        if (!any) return previous;
+        return withDiff(epoch, merged);
+      },
+      { historyLength: 128 }
+    );
+    this.historyCache.set(typeName, filtered);
+    return filtered;
   }
 };
 var Store = class {
@@ -762,7 +991,15 @@ var Store = class {
   scopedTypes;
   sideEffects = new StoreSideEffects();
   query;
-  /** Bumped once per completed operation that changed something. */
+  /**
+   * Bumped once per completed operation that changed something.
+   *
+   * The counter itself carries no information; the diffs do. The atom keeps a
+   * bounded history of the squashed {@link RecordsDiff} of each operation, so a
+   * derived collection can ask `history.getDiffSince(epoch)` and patch itself
+   * instead of rebuilding. `store.query.filterHistory(typeName)` is the same
+   * thing narrowed to one record type.
+   */
   history;
   records = /* @__PURE__ */ new Map();
   typeIndexes = /* @__PURE__ */ new Map();
@@ -774,11 +1011,22 @@ var Store = class {
   runCallbacks = true;
   inOperationComplete = false;
   disposed = false;
+  /**
+   * The diff of the operation currently being committed, handed to the history
+   * atom's `computeDiff` as it is written. The atom only sees two counter
+   * values, so the diff has to be staged here for the one write that follows.
+   */
+  pendingHistoryDiff = null;
   constructor(options) {
     this.id = options.id ?? uniqueId();
     this.schema = options.schema;
     this.props = options.props;
-    this.history = atom(`store:${this.id}:history`, 0);
+    this.history = atom(`store:${this.id}:history`, 0, {
+      // 128 operations is deep enough that a dependent which rendered a frame
+      // ago can still patch, and shallow enough that the buffer costs nothing.
+      historyLength: 128,
+      computeDiff: () => this.pendingHistoryDiff ?? RESET_VALUE
+    });
     this.query = new StoreQueries(this);
     const scoped = { document: /* @__PURE__ */ new Set(), session: /* @__PURE__ */ new Set(), presence: /* @__PURE__ */ new Set() };
     for (const type of Object.values(this.schema.types)) {
@@ -1037,6 +1285,28 @@ var Store = class {
   getStoreSnapshot(scope = "document") {
     return { store: this.serialize(scope), schema: this.schema.serialize() };
   }
+  /**
+   * Bring a snapshot saved by an older document up to this store's schema,
+   * without loading it.
+   *
+   * Every migration sequence the schema knows is run — including the ones
+   * `createStore` derives from the shape and binding utils, so a board saved
+   * before a prop existed is backfilled here rather than failing validation on
+   * load. The input is not mutated: the result is a new snapshot carrying this
+   * schema's serialized version, ready for {@link Store.loadStoreSnapshot} (or
+   * for a caller that wants to inspect the migrated records first).
+   *
+   * A snapshot that cannot be migrated — an unknown schema version, a sequence
+   * from a NEWER build than this one, a migration that throws — raises rather
+   * than returning half-migrated data, so a caller can fail closed on it.
+   */
+  migrateSnapshot(snapshot) {
+    const migrated = this.schema.migrateStoreSnapshot(snapshot);
+    if (migrated.type === "error") {
+      throw new Error(`Failed to migrate snapshot: ${migrated.reason}`);
+    }
+    return { store: migrated.value, schema: this.schema.serialize() };
+  }
   /**
    * Replace the store's contents with a snapshot (migrating it first).
    * Existing records in `document` scope and in every scope present in the
@@ -1146,9 +1416,20 @@ var Store = class {
         this.inOperationComplete = false;
       }
     }
-    this.history.update((n) => n + 1);
+    this.pendingHistoryDiff = this.squashPendingEntries();
+    try {
+      this.history.update((n) => n + 1);
+    } finally {
+      this.pendingHistoryDiff = null;
+    }
     this.flushHistory();
   }
+  /** One diff describing everything the operation just committed changed. */
+  squashPendingEntries() {
+    const diffs = this.pendingEntries.map((entry) => entry.changes).filter((diff) => !isRecordsDiffEmpty(diff));
+    if (diffs.length === 1) return diffs[0];
+    return squashRecordDiffs(diffs);
+  }
   flushHistory() {
     const entries = this.pendingEntries;
     this.pendingEntries = [];
@@ -1256,6 +1537,119 @@ function storeSnapshotToTldrFile(snapshot) {
   return serializeTldrFile(snapshot.schema, records);
 }
 
-export { RecordType, Store, StoreQueries, StoreSchema, StoreSideEffects, TLDR_FILE_FORMAT_VERSION, UNIQUE_ID_LENGTH, ZERO_INDEX_KEY, ZKEY_SIGNIFICANT_DIGITS, applyChangeToDiff, applyMigrationToStore, applyRecordMigration, cloneRecordsDiff, compareIndexKeys, compareZKeys, createEmptyRecordsDiff, createMigrationIds, createMigrationSequence, createRecordMigrationSequence, createRecordType, freezeRecord, getIndexAbove, getIndexBelow, getIndexBetween, getIndices, getIndicesAbove, getIndicesBelow, getIndicesBetween, indexKeyToZKey, isIndexKey, isRecordLike, isRecordShallowEqual, isRecordsDiffEmpty, parseMigrationId, parseRecordId, parseTldrFile, reverseRecordsDiff, serializeTldrFile, sortByIndex, squashRecordDiffs, squashRecordDiffsMutable, storeSnapshotToTldrFile, tldrFileToStoreSnapshot, uniqueId, validateIndexKey, zKeyToBigInt };
+// src/computedCache.ts
+function storeOf(context) {
+  if (context instanceof Store) return context;
+  const store = context?.store;
+  if (store instanceof Store) return store;
+  throw new Error("createComputedCache: context is neither a Store nor an object holding one");
+}
+function createComputedCache(name, derive, options) {
+  const perContext = /* @__PURE__ */ new WeakMap();
+  return {
+    get(context, id) {
+      const key = context;
+      if (key === null || typeof key !== "object" && typeof key !== "function") {
+        throw new Error("createComputedCache: context must be an object");
+      }
+      let cache = perContext.get(key);
+      if (!cache) {
+        const areRecordsEqual = options?.areRecordsEqual;
+        const previous = /* @__PURE__ */ new Map();
+        const derivation = areRecordsEqual ? (record) => {
+          const next = record;
+          const last = previous.get(record.id);
+          if (last && areRecordsEqual(last.record, next)) return last.result;
+          const result = derive(context, next);
+          previous.set(record.id, { record: next, result });
+          return result;
+        } : (record) => derive(context, record);
+        cache = storeOf(context).createComputedCache(
+          name,
+          derivation,
+          options?.isEqual ? { isEqual: options.isEqual } : void 0
+        );
+        perContext.set(key, cache);
+      }
+      return cache.get(id);
+    }
+  };
+}
+
+// src/devFreeze.ts
+var IS_DEV = typeof process !== "undefined" && typeof process.env === "object" && process.env["NODE_ENV"] !== "production";
+function devFreeze(object) {
+  if (!IS_DEV) return object;
+  return deepFreeze(object);
+}
+function deepFreeze(object) {
+  if (object === null || typeof object !== "object") return object;
+  if (Object.isFrozen(object)) return object;
+  Object.freeze(object);
+  for (const value of Object.values(object)) deepFreeze(value);
+  if (Array.isArray(object)) for (const value of object) deepFreeze(value);
+  return object;
+}
+function assertIdType(id, type) {
+  if (!type.isId(id)) {
+    throw new Error(`Expected ${type.typeName} id, got ${JSON.stringify(id)}`);
+  }
+}
+
+// src/storage.ts
+function createInMemoryStorage() {
+  const records = /* @__PURE__ */ new Map();
+  let schema;
+  return {
+    get: (id) => records.get(id),
+    getAll: () => [...records.values()],
+    set: (record) => {
+      records.set(record.id, record);
+    },
+    delete: (id) => {
+      records.delete(id);
+    },
+    clear: () => records.clear(),
+    getSchema: () => schema,
+    setSchema: (next) => {
+      schema = next;
+    }
+  };
+}
+
+// src/graphemes.ts
+var segmenter;
+var segmenterChecked = false;
+function getSegmenter() {
+  if (!segmenterChecked) {
+    segmenterChecked = true;
+    try {
+      if (typeof Intl !== "undefined" && typeof Intl.Segmenter === "function") {
+        segmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" });
+      }
+    } catch {
+      segmenter = void 0;
+    }
+  }
+  return segmenter;
+}
+function* iterateGraphemes(str) {
+  const seg = getSegmenter();
+  if (seg) {
+    for (const { segment } of seg.segment(str)) yield segment;
+    return;
+  }
+  for (const codePoint of str) yield codePoint;
+}
+function getGraphemes(str) {
+  return [...iterateGraphemes(str)];
+}
+function getGraphemeLength(str) {
+  let n = 0;
+  for (const _ of iterateGraphemes(str)) n++;
+  return n;
+}
+
+export { MigrationFailureReason, RecordType, Store, StoreQueries, StoreSchema, StoreSideEffects, TLDR_FILE_FORMAT_VERSION, UNIQUE_ID_LENGTH, ZERO_INDEX_KEY, ZKEY_SIGNIFICANT_DIGITS, applyChangeToDiff, applyCollectionDiff, applyMigrationToStore, applyRecordMigration, assertIdType, cloneRecordsDiff, compareIndexKeys, compareZKeys, createComputedCache, createEmptyRecordsDiff, createInMemoryStorage, createMigrationIds, createMigrationSequence, createRecordMigrationSequence, createRecordType, devFreeze, freezeRecord, getGraphemeLength, getGraphemes, getIndexAbove, getIndexBelow, getIndexBetween, getIndexablePropertyOf, getIndices, getIndicesAbove, getIndicesBelow, getIndicesBetween, indexKeyToZKey, isCollectionDiffEmpty, isIndexKey, isRecordLike, isRecordShallowEqual, isRecordsDiffEmpty, isSerializedSchemaV1, iterateGraphemes, matchesQuery, matchesQueryValue, parseMigrationId, parseRecordId, parseTldrFile, reverseRecordsDiff, serializeTldrFile, sortByIndex, squashRecordDiffs, squashRecordDiffsMutable, storeSnapshotToTldrFile, tldrFileToStoreSnapshot, uniqueId, validateIndexKey, zKeyToBigInt };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map