@mocanvas/store 1.0.0

package/dist/index.js

@@ -0,0 +1,1261 @@
+import { nanoid } from 'nanoid';
+import { generateKeyBetween, generateNKeysBetween } from 'fractional-indexing';
+import { computed, unsafe__withoutCapture, atom, transact } from '@mocanvas/state';
+
+// src/ids.ts
+var UNIQUE_ID_LENGTH = 21;
+function uniqueId(size = UNIQUE_ID_LENGTH) {
+  return nanoid(size);
+}
+var RecordType = class _RecordType {
+  constructor(typeName, config) {
+    this.config = config;
+    this.typeName = typeName;
+    this.scope = config.scope;
+    this.validator = config.validator;
+    this.ephemeralKeys = config.ephemeralKeys;
+    const ephemeral = /* @__PURE__ */ new Set();
+    if (config.ephemeralKeys) {
+      for (const [key, value] of Object.entries(config.ephemeralKeys)) {
+        if (value) ephemeral.add(key);
+      }
+    }
+    this.ephemeralKeySet = ephemeral;
+  }
+  config;
+  typeName;
+  scope;
+  validator;
+  ephemeralKeys;
+  ephemeralKeySet;
+  /** Create a new record with defaults applied. A fresh id is generated when none is given. */
+  create(properties) {
+    const result = {
+      ...this.config.createDefaultProperties(),
+      ...properties
+    };
+    if (result["id"] === void 0) result["id"] = this.createId();
+    result["typeName"] = this.typeName;
+    return result;
+  }
+  /** Shallow-clone a record (props/meta are shared). */
+  clone(record) {
+    return { ...record };
+  }
+  /** Make an id of this type: `${typeName}:${uniquePart}`. */
+  createId(customUniquePart) {
+    return `${this.typeName}:${customUniquePart ?? uniqueId()}`;
+  }
+  /** Recover the unique part of an id of this type. */
+  parseId(id) {
+    if (!this.isId(id)) {
+      throw new Error(`Id ${JSON.stringify(id)} is not a ${this.typeName} id`);
+    }
+    return id.slice(this.typeName.length + 1);
+  }
+  isId(id) {
+    if (typeof id !== "string") return false;
+    if (id.length <= this.typeName.length + 1) return false;
+    if (id.charCodeAt(this.typeName.length) !== 58) return false;
+    return id.startsWith(this.typeName);
+  }
+  isInstance(record) {
+    return typeof record === "object" && record !== null && record.typeName === this.typeName;
+  }
+  /**
+   * Return a new RecordType whose `create()` fills in the given defaults, so
+   * those properties become optional for callers.
+   */
+  withDefaultProperties(createDefaultProperties) {
+    return new _RecordType(this.typeName, {
+      scope: this.scope,
+      validator: this.validator,
+      ephemeralKeys: this.ephemeralKeys,
+      createDefaultProperties
+    });
+  }
+  /** Run the validator (if any). Throws on invalid input. */
+  validate(record, recordBefore) {
+    if (!this.validator) return record;
+    if (recordBefore !== void 0 && this.validator.validateUsingKnownGoodVersion) {
+      return this.validator.validateUsingKnownGoodVersion(recordBefore, record);
+    }
+    return this.validator.validate(record);
+  }
+};
+function createRecordType(typeName, config) {
+  return new RecordType(typeName, {
+    scope: config.scope,
+    validator: config.validator,
+    ephemeralKeys: config.ephemeralKeys,
+    createDefaultProperties: () => ({})
+  });
+}
+function parseRecordId(id) {
+  const colon = id.indexOf(":");
+  if (colon <= 0 || colon === id.length - 1) {
+    throw new Error(`Malformed record id ${JSON.stringify(id)}`);
+  }
+  return { typeName: id.slice(0, colon), uniquePart: id.slice(colon + 1) };
+}
+function isRecordLike(value) {
+  return typeof value === "object" && value !== null && typeof value.id === "string" && typeof value.typeName === "string";
+}
+var ZERO_INDEX_KEY = "a0";
+function assertOrdered(below, above) {
+  if (below !== void 0 && above !== void 0 && !(below < above)) {
+    throw new Error(`Index keys out of order: ${JSON.stringify(below)} must be below ${JSON.stringify(above)}`);
+  }
+}
+function getIndexBetween(below, above) {
+  assertOrdered(below, above);
+  return generateKeyBetween(below ?? null, above ?? null);
+}
+function getIndexAbove(below) {
+  return generateKeyBetween(below ?? null, null);
+}
+function getIndexBelow(above) {
+  return generateKeyBetween(null, above ?? null);
+}
+function getIndicesBetween(below, above, n) {
+  assertOrdered(below, above);
+  return generateNKeysBetween(below ?? null, above ?? null, n);
+}
+function getIndicesAbove(below, n) {
+  return generateNKeysBetween(below ?? null, null, n);
+}
+function getIndicesBelow(above, n) {
+  return generateNKeysBetween(null, above ?? null, n);
+}
+function getIndices(n, start = ZERO_INDEX_KEY) {
+  if (n <= 0) return [];
+  validateIndexKey(start);
+  return [start, ...getIndicesAbove(start, n - 1)];
+}
+function sortByIndex(items) {
+  return items.map((item, i) => [item, i]).sort(([a, ai], [b, bi]) => {
+    if (a.index < b.index) return -1;
+    if (a.index > b.index) return 1;
+    return ai - bi;
+  }).map(([item]) => item);
+}
+function compareIndexKeys(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+var BASE_62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+var IS_DIGIT = new Uint8Array(128);
+for (let i = 0; i < BASE_62.length; i++) IS_DIGIT[BASE_62.charCodeAt(i)] = 1;
+function integerPartLength(head) {
+  if (head >= 97 && head <= 122) return head - 97 + 2;
+  if (head >= 65 && head <= 90) return 90 - head + 2;
+  return -1;
+}
+function validateIndexKey(key) {
+  const fail = (why) => {
+    throw new Error(`Invalid index key ${JSON.stringify(key)}: ${why}`);
+  };
+  if (typeof key !== "string" || key.length === 0) fail("empty");
+  const intLen = integerPartLength(key.charCodeAt(0));
+  if (intLen < 0) fail("bad head marker");
+  if (key.length < intLen) fail(`integer part needs ${intLen - 1} digits`);
+  for (let i = 1; i < key.length; i++) {
+    const c = key.charCodeAt(i);
+    if (c > 127 || IS_DIGIT[c] !== 1) fail(`bad digit at ${i}`);
+  }
+  if (key.length > intLen && key.endsWith("0")) fail("fraction ends in 0");
+}
+function isIndexKey(key) {
+  if (typeof key !== "string") return false;
+  try {
+    validateIndexKey(key);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/zkey.ts
+var BASE_622 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+var HEADS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+var ZKEY_SIGNIFICANT_DIGITS = 10;
+var DIGIT_VALUE = new Int8Array(128).fill(-1);
+for (let i = 0; i < BASE_622.length; i++) DIGIT_VALUE[BASE_622.charCodeAt(i)] = i;
+var HEAD_RANK = new Int8Array(128).fill(-1);
+for (let i = 0; i < HEADS.length; i++) HEAD_RANK[HEADS.charCodeAt(i)] = i;
+var B = 62n;
+var B10 = B ** BigInt(ZKEY_SIGNIFICANT_DIGITS);
+var MASK_32 = 0xffffffffn;
+function indexKeyToZKey(key) {
+  if (key.length === 0) throw new Error("Cannot convert an empty index key");
+  const headRank = HEAD_RANK[key.charCodeAt(0)] ?? -1;
+  if (headRank < 0) throw new Error(`Invalid index key head in ${JSON.stringify(key)}`);
+  let fraction = 0n;
+  const n = Math.min(key.length - 1, ZKEY_SIGNIFICANT_DIGITS);
+  for (let i = 0; i < n; i++) {
+    const d = DIGIT_VALUE[key.charCodeAt(i + 1)] ?? -1;
+    if (d < 0) throw new Error(`Invalid index key digit in ${JSON.stringify(key)}`);
+    fraction = fraction * B + BigInt(d);
+  }
+  for (let i = n; i < ZKEY_SIGNIFICANT_DIGITS; i++) fraction *= B;
+  const value = BigInt(headRank) * B10 + fraction;
+  const lo = Number(value & MASK_32);
+  const hi = Number(value >> 32n & MASK_32);
+  return [lo, hi];
+}
+function zKeyToBigInt([lo, hi]) {
+  return BigInt(hi) << 32n | BigInt(lo);
+}
+function compareZKeys(a, b) {
+  if (a[1] !== b[1]) return a[1] < b[1] ? -1 : 1;
+  if (a[0] !== b[0]) return a[0] < b[0] ? -1 : 1;
+  return 0;
+}
+
+// src/RecordsDiff.ts
+function createEmptyRecordsDiff() {
+  return { added: {}, updated: {}, removed: {} };
+}
+function isRecordsDiffEmpty(diff) {
+  for (const _ in diff.added) return false;
+  for (const _ in diff.updated) return false;
+  for (const _ in diff.removed) return false;
+  return true;
+}
+function reverseRecordsDiff(diff) {
+  const result = createEmptyRecordsDiff();
+  for (const id in diff.added) {
+    result.removed[id] = diff.added[id];
+  }
+  for (const id in diff.removed) {
+    result.added[id] = diff.removed[id];
+  }
+  for (const id in diff.updated) {
+    const [from, to] = diff.updated[id];
+    result.updated[id] = [to, from];
+  }
+  return result;
+}
+function applyChangeToDiff(target, id, before, after) {
+  if (before === void 0 && after === void 0) return;
+  if (id in target.added) {
+    if (after === void 0) {
+      delete target.added[id];
+    } else {
+      target.added[id] = after;
+    }
+    return;
+  }
+  if (id in target.updated) {
+    const [from] = target.updated[id];
+    if (after === void 0) {
+      delete target.updated[id];
+      target.removed[id] = from;
+    } else if (from === after) {
+      delete target.updated[id];
+    } else {
+      target.updated[id] = [from, after];
+    }
+    return;
+  }
+  if (id in target.removed) {
+    const original = target.removed[id];
+    if (after === void 0) return;
+    delete target.removed[id];
+    if (original !== after) target.updated[id] = [original, after];
+    return;
+  }
+  if (before === void 0) {
+    if (after !== void 0) target.added[id] = after;
+  } else if (after === void 0) {
+    target.removed[id] = before;
+  } else if (before !== after) {
+    target.updated[id] = [before, after];
+  }
+}
+function squashRecordDiffsMutable(target, diff) {
+  for (const id in diff.added) {
+    applyChangeToDiff(target, id, void 0, diff.added[id]);
+  }
+  for (const id in diff.updated) {
+    const [from, to] = diff.updated[id];
+    applyChangeToDiff(target, id, from, to);
+  }
+  for (const id in diff.removed) {
+    applyChangeToDiff(target, id, diff.removed[id], void 0);
+  }
+}
+function squashRecordDiffs(diffs) {
+  const result = createEmptyRecordsDiff();
+  for (const diff of diffs) squashRecordDiffsMutable(result, diff);
+  return result;
+}
+function cloneRecordsDiff(diff) {
+  return {
+    added: { ...diff.added },
+    updated: { ...diff.updated },
+    removed: { ...diff.removed }
+  };
+}
+
+// src/migrate.ts
+function createMigrationIds(sequenceId, versions) {
+  const result = {};
+  for (const [name, version] of Object.entries(versions)) {
+    result[name] = `${sequenceId}/${version}`;
+  }
+  return result;
+}
+function parseMigrationId(id) {
+  const slash = id.lastIndexOf("/");
+  if (slash <= 0) throw new Error(`Malformed migration id ${JSON.stringify(id)}`);
+  const version = Number(id.slice(slash + 1));
+  if (!Number.isInteger(version) || version < 1) {
+    throw new Error(`Malformed migration id ${JSON.stringify(id)}: version must be a positive integer`);
+  }
+  return { sequenceId: id.slice(0, slash), version };
+}
+function createMigrationSequence(options) {
+  const { sequenceId, retroactive = true, sequence } = options;
+  if (!sequenceId || sequenceId.includes("/")) {
+    throw new Error(`Invalid sequenceId ${JSON.stringify(sequenceId)}: must be non-empty and not contain "/"`);
+  }
+  sequence.forEach((migration, i) => {
+    const id = migration.id;
+    const parsed = parseMigrationId(id);
+    if (parsed.sequenceId !== sequenceId) {
+      throw new Error(`Migration ${id} does not belong to sequence ${sequenceId}`);
+    }
+    if (parsed.version !== i + 1) {
+      throw new Error(`Migration ${id} is out of order: expected version ${i + 1}`);
+    }
+    const scope = migration.scope;
+    if (scope !== "record" && scope !== "store") {
+      throw new Error(`Migration ${id} has invalid scope ${JSON.stringify(scope)}`);
+    }
+  });
+  return { sequenceId, retroactive, sequence: [...sequence] };
+}
+function createRecordMigrationSequence(options) {
+  const { recordType, filter } = options;
+  const combinedFilter = (record) => record.typeName === recordType && (filter ? filter(record) : true);
+  return createMigrationSequence({
+    sequenceId: options.sequenceId,
+    retroactive: options.retroactive,
+    sequence: options.sequence.map(
+      (m) => ({ id: m.id, scope: "record", filter: combinedFilter, up: m.up, down: m.down })
+    )
+  });
+}
+function applyRecordMigration(migration, record, direction) {
+  if (migration.filter && !migration.filter(record)) return record;
+  const fn = direction === "up" ? migration.up : migration.down;
+  if (!fn) throw new Error(`Migration ${migration.id} has no ${direction} function`);
+  const result = fn(record);
+  return result === void 0 ? record : result;
+}
+function applyMigrationToStore(migration, store, direction) {
+  if (migration.scope === "store") {
+    const fn = direction === "up" ? migration.up : migration.down;
+    if (!fn) throw new Error(`Migration ${migration.id} has no ${direction} function`);
+    const result = fn(store);
+    return result === void 0 ? store : result;
+  }
+  for (const id in store) {
+    const record = store[id];
+    const next = applyRecordMigration(migration, record, direction);
+    if (next !== record) store[id] = next;
+  }
+  return store;
+}
+
+// src/StoreSchema.ts
+var StoreSchema = class _StoreSchema {
+  constructor(types, options) {
+    this.types = types;
+    this.options = options;
+    const byName = /* @__PURE__ */ new Map();
+    for (const [name, type] of Object.entries(types)) {
+      if (type.typeName !== name) {
+        throw new Error(`Record type registered under "${name}" has typeName "${type.typeName}"`);
+      }
+      byName.set(name, type);
+    }
+    this.typeByName = byName;
+    const migrations = {};
+    const sorted = [];
+    const seenIds = /* @__PURE__ */ new Set();
+    for (const sequence of options.migrations ?? []) {
+      if (migrations[sequence.sequenceId]) {
+        throw new Error(`Duplicate migration sequence "${sequence.sequenceId}"`);
+      }
+      migrations[sequence.sequenceId] = sequence;
+      for (const migration of sequence.sequence) {
+        if (seenIds.has(migration.id)) throw new Error(`Duplicate migration id "${migration.id}"`);
+        seenIds.add(migration.id);
+        sorted.push(migration);
+      }
+    }
+    this.migrations = migrations;
+    this.sortedMigrations = sorted;
+  }
+  types;
+  options;
+  static create(types, options) {
+    return new _StoreSchema(types, options ?? {});
+  }
+  migrations;
+  /** All migrations in application order (sequence registration order, then version). */
+  sortedMigrations;
+  typeByName;
+  getType(typeName) {
+    return this.typeByName.get(typeName);
+  }
+  /** Scope of a record type; unknown types are treated as `document`. */
+  getScope(typeName) {
+    return this.typeByName.get(typeName)?.scope ?? "document";
+  }
+  /**
+   * Validate a record, delegating to its record type's validator. Records of
+   * unknown types are passed through untouched so that foreign data survives
+   * a load/save round-trip.
+   */
+  validateRecord(store, record, phase, recordBefore) {
+    const type = this.typeByName.get(record.typeName);
+    if (!type) return record;
+    try {
+      return type.validate(record, recordBefore);
+    } catch (error) {
+      if (this.options.onValidationFailure) {
+        return this.options.onValidationFailure({
+          error,
+          store,
+          record,
+          phase,
+          recordBefore: recordBefore ?? null
+        });
+      }
+      throw error;
+    }
+  }
+  /** The current version of every sequence. */
+  serialize() {
+    const sequences = {};
+    for (const sequence of Object.values(this.migrations)) {
+      sequences[sequence.sequenceId] = sequence.sequence.length;
+    }
+    return { schemaVersion: 2, sequences };
+  }
+  /** A schema at version 0 of every sequence (all migrations still pending). */
+  serializeEarliestVersion() {
+    const sequences = {};
+    for (const sequence of Object.values(this.migrations)) sequences[sequence.sequenceId] = 0;
+    return { schemaVersion: 2, sequences };
+  }
+  /**
+   * The migrations that must run to bring data saved under `persistedSchema`
+   * up to this schema, in order. Sequences the persisted schema knows but we
+   * do not are ignored with a warning.
+   */
+  getMigrationsSince(persistedSchema) {
+    if (persistedSchema.schemaVersion !== 2) {
+      return {
+        type: "error",
+        reason: `Unsupported schema version ${String(persistedSchema.schemaVersion)}`
+      };
+    }
+    const persisted = persistedSchema.sequences ?? {};
+    for (const sequenceId of Object.keys(persisted)) {
+      if (!this.migrations[sequenceId]) {
+        console.warn(`[store] ignoring unknown migration sequence "${sequenceId}" in persisted schema`);
+      }
+    }
+    const result = [];
+    for (const sequence of Object.values(this.migrations)) {
+      const persistedVersion = persisted[sequence.sequenceId];
+      let startAt;
+      if (persistedVersion === void 0) {
+        if (!sequence.retroactive) continue;
+        startAt = 0;
+      } else {
+        if (!Number.isInteger(persistedVersion) || persistedVersion < 0) {
+          return { type: "error", reason: `Invalid version ${String(persistedVersion)} for sequence "${sequence.sequenceId}"` };
+        }
+        if (persistedVersion > sequence.sequence.length) {
+          return {
+            type: "error",
+            reason: `Sequence "${sequence.sequenceId}" is at version ${persistedVersion} but this schema only knows ${sequence.sequence.length}: data comes from a newer version`
+          };
+        }
+        startAt = persistedVersion;
+      }
+      for (let i = startAt; i < sequence.sequence.length; i++) result.push(sequence.sequence[i]);
+    }
+    return { type: "success", value: result };
+  }
+  /**
+   * Migrate a single record. Only record-scoped migrations can be applied;
+   * encountering a store-scoped one is an error. `down` runs the migrations
+   * in reverse (from this schema to `persistedSchema`).
+   */
+  migratePersistedRecord(record, persistedSchema, direction = "up") {
+    const migrations = this.getMigrationsSince(persistedSchema);
+    if (migrations.type === "error") return migrations;
+    const ordered = direction === "up" ? migrations.value : [...migrations.value].reverse();
+    let current = structuredClone(record);
+    try {
+      for (const migration of ordered) {
+        if (migration.scope !== "record") {
+          return { type: "error", reason: `Migration ${migration.id} is store-scoped and cannot be applied to a single record` };
+        }
+        if (direction === "down" && !migration.down) {
+          return { type: "error", reason: `Migration ${migration.id} has no down migration` };
+        }
+        current = applyRecordMigration(migration, current, direction);
+      }
+    } catch (error) {
+      return { type: "error", reason: `Migration failed: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    return { type: "success", value: current };
+  }
+  /**
+   * Bring a whole persisted store up to date. The input is not mutated.
+   * Records of types this schema does not know are preserved as-is.
+   */
+  migrateStoreSnapshot(snapshot) {
+    const migrations = this.getMigrationsSince(snapshot.schema);
+    if (migrations.type === "error") return migrations;
+    let store = structuredClone(snapshot.store);
+    if (migrations.value.length === 0) return { type: "success", value: store };
+    try {
+      for (const migration of migrations.value) {
+        store = applyMigrationToStore(migration, store, "up");
+      }
+    } catch (error) {
+      return { type: "error", reason: `Migration failed: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    for (const id in store) {
+      const record = store[id];
+      if (!record || record.id !== id) {
+        return { type: "error", reason: `Migration produced a record whose id does not match its key (${id})` };
+      }
+    }
+    return { type: "success", value: store };
+  }
+};
+
+// src/Store.ts
+var StoreSideEffects = class {
+  byType = /* @__PURE__ */ new Map();
+  operationComplete = /* @__PURE__ */ new Set();
+  enabled = true;
+  isEnabled() {
+    return this.enabled;
+  }
+  setIsEnabled(enabled) {
+    this.enabled = enabled;
+  }
+  sets(typeName) {
+    let sets = this.byType.get(typeName);
+    if (!sets) {
+      sets = {
+        beforeCreate: /* @__PURE__ */ new Set(),
+        afterCreate: /* @__PURE__ */ new Set(),
+        beforeChange: /* @__PURE__ */ new Set(),
+        afterChange: /* @__PURE__ */ new Set(),
+        beforeDelete: /* @__PURE__ */ new Set(),
+        afterDelete: /* @__PURE__ */ new Set()
+      };
+      this.byType.set(typeName, sets);
+    }
+    return sets;
+  }
+  add(typeName, kind, handler) {
+    const set = this.sets(typeName)[kind];
+    set.add(handler);
+    return () => {
+      set.delete(handler);
+    };
+  }
+  /** Register several handlers for several types at once. Returns a disposer for all of them. */
+  register(handlers) {
+    const disposers = [];
+    for (const [typeName, h] of Object.entries(handlers)) {
+      if (!h) continue;
+      if (h.beforeCreate) disposers.push(this.add(typeName, "beforeCreate", h.beforeCreate));
+      if (h.afterCreate) disposers.push(this.add(typeName, "afterCreate", h.afterCreate));
+      if (h.beforeChange) disposers.push(this.add(typeName, "beforeChange", h.beforeChange));
+      if (h.afterChange) disposers.push(this.add(typeName, "afterChange", h.afterChange));
+      if (h.beforeDelete) disposers.push(this.add(typeName, "beforeDelete", h.beforeDelete));
+      if (h.afterDelete) disposers.push(this.add(typeName, "afterDelete", h.afterDelete));
+    }
+    return () => disposers.forEach((d) => d());
+  }
+  registerBeforeCreateHandler(typeName, handler) {
+    return this.add(typeName, "beforeCreate", handler);
+  }
+  registerAfterCreateHandler(typeName, handler) {
+    return this.add(typeName, "afterCreate", handler);
+  }
+  registerBeforeChangeHandler(typeName, handler) {
+    return this.add(typeName, "beforeChange", handler);
+  }
+  registerAfterChangeHandler(typeName, handler) {
+    return this.add(typeName, "afterChange", handler);
+  }
+  registerBeforeDeleteHandler(typeName, handler) {
+    return this.add(typeName, "beforeDelete", handler);
+  }
+  registerAfterDeleteHandler(typeName, handler) {
+    return this.add(typeName, "afterDelete", handler);
+  }
+  registerOperationCompleteHandler(handler) {
+    this.operationComplete.add(handler);
+    return () => {
+      this.operationComplete.delete(handler);
+    };
+  }
+  /** @internal */
+  handleBeforeCreate(record, source) {
+    const sets = this.byType.get(record.typeName);
+    if (!sets) return record;
+    let result = record;
+    for (const handler of sets.beforeCreate) result = handler(result, source);
+    return result;
+  }
+  /** @internal */
+  handleAfterCreate(record, source) {
+    const sets = this.byType.get(record.typeName);
+    if (!sets) return;
+    for (const handler of sets.afterCreate) handler(record, source);
+  }
+  /** @internal */
+  handleBeforeChange(prev, next, source) {
+    const sets = this.byType.get(next.typeName);
+    if (!sets) return next;
+    let result = next;
+    for (const handler of sets.beforeChange) result = handler(prev, result, source);
+    return result;
+  }
+  /** @internal */
+  handleAfterChange(prev, next, source) {
+    const sets = this.byType.get(next.typeName);
+    if (!sets) return;
+    for (const handler of sets.afterChange) handler(prev, next, source);
+  }
+  /** @internal Returns false when a handler vetoed the delete. */
+  handleBeforeDelete(record, source) {
+    const sets = this.byType.get(record.typeName);
+    if (!sets) return true;
+    for (const handler of sets.beforeDelete) {
+      if (handler(record, source) === false) return false;
+    }
+    return true;
+  }
+  /** @internal */
+  handleAfterDelete(record, source) {
+    const sets = this.byType.get(record.typeName);
+    if (!sets) return;
+    for (const handler of sets.afterDelete) handler(record, source);
+  }
+  /** @internal */
+  handleOperationComplete(source) {
+    for (const handler of this.operationComplete) handler(source);
+  }
+};
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function shallowEqualObjects(a, b) {
+  if (a === b) return true;
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const key of aKeys) {
+    if (!(key in b) || a[key] !== b[key]) return false;
+  }
+  return true;
+}
+function isRecordShallowEqual(a, b) {
+  if (a === b) return true;
+  const ao = a;
+  const bo = b;
+  const aKeys = Object.keys(ao);
+  const bKeys = Object.keys(bo);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const key of aKeys) {
+    if (!(key in bo)) return false;
+    const av = ao[key];
+    const bv = bo[key];
+    if (av === bv) continue;
+    if ((key === "props" || key === "meta") && isPlainObject(av) && isPlainObject(bv)) {
+      if (!shallowEqualObjects(av, bv)) return false;
+      continue;
+    }
+    return false;
+  }
+  return true;
+}
+function freezeRecord(record) {
+  const r = record;
+  if (isPlainObject(r["props"]) && !Object.isFrozen(r["props"])) Object.freeze(r["props"]);
+  if (isPlainObject(r["meta"]) && !Object.isFrozen(r["meta"])) Object.freeze(r["meta"]);
+  return Object.freeze(record);
+}
+var StoreQueries = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  idsCache = /* @__PURE__ */ new Map();
+  recordsCache = /* @__PURE__ */ new Map();
+  /** The set of ids of every record of `typeName`. Maintained incrementally. */
+  ids(typeName) {
+    let c = this.idsCache.get(typeName);
+    if (!c) {
+      const index = this.store.getTypeIndex(typeName);
+      c = computed(`store:${this.store.id}:ids:${typeName}`, () => {
+        index.epoch.get();
+        return new Set(index.live);
+      });
+      this.idsCache.set(typeName, c);
+    }
+    return c;
+  }
+  /** Every record of `typeName`, in insertion order. */
+  records(typeName) {
+    let c = this.recordsCache.get(typeName);
+    if (!c) {
+      const ids = this.ids(typeName);
+      c = computed(`store:${this.store.id}:records:${typeName}`, () => {
+        const result = [];
+        for (const id of ids.get()) {
+          const record = this.store.get(id);
+          if (record !== void 0) result.push(record);
+        }
+        return result;
+      });
+      this.recordsCache.set(typeName, c);
+    }
+    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;
+    });
+  }
+  /** Non-reactive filter over the records of `typeName`. */
+  exec(typeName, predicate) {
+    return unsafe__withoutCapture(() => this.records(typeName).get().filter(predicate));
+  }
+};
+var Store = class {
+  id;
+  schema;
+  props;
+  scopedTypes;
+  sideEffects = new StoreSideEffects();
+  query;
+  /** Bumped once per completed operation that changed something. */
+  history;
+  records = /* @__PURE__ */ new Map();
+  typeIndexes = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  pendingEntries = [];
+  extractStack = [];
+  depth = 0;
+  source = "user";
+  runCallbacks = true;
+  inOperationComplete = false;
+  disposed = false;
+  constructor(options) {
+    this.id = options.id ?? uniqueId();
+    this.schema = options.schema;
+    this.props = options.props;
+    this.history = atom(`store:${this.id}:history`, 0);
+    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)) {
+      scoped[type.scope].add(type.typeName);
+    }
+    this.scopedTypes = scoped;
+    if (options.initialData) {
+      const records = Object.values(options.initialData);
+      this.atomic(() => this.put(records, "initialize"), { runCallbacks: false });
+    }
+  }
+  /* ---- reading ---------------------------------------------------------- */
+  /** @internal */
+  getTypeIndex(typeName) {
+    let index = this.typeIndexes.get(typeName);
+    if (!index) {
+      index = { live: /* @__PURE__ */ new Set(), epoch: atom(`store:${this.id}:index:${typeName}`, 0) };
+      this.typeIndexes.set(typeName, index);
+    }
+    return index;
+  }
+  /** Get a record (reactive: subscribes to the record, or to its type's membership when absent). */
+  get(id) {
+    const a = this.records.get(id);
+    if (a) return a.get();
+    this.getTypeIndex(typeNameOfId(id)).epoch.get();
+    return void 0;
+  }
+  /** Get a record without registering a reactive dependency. */
+  unsafeGetWithoutCapture(id) {
+    const a = this.records.get(id);
+    return a ? unsafe__withoutCapture(() => a.get()) : void 0;
+  }
+  has(id) {
+    return this.get(id) !== void 0;
+  }
+  /** All records (reactive over every record and every type's membership). */
+  allRecords() {
+    for (const index of this.typeIndexes.values()) index.epoch.get();
+    const result = [];
+    for (const a of this.records.values()) {
+      const record = a.get();
+      if (record !== void 0) result.push(record);
+    }
+    return result;
+  }
+  /** Scope of a record type; unknown types are `document`. */
+  getScope(typeName) {
+    return this.schema.getScope(typeName);
+  }
+  /* ---- writing ---------------------------------------------------------- */
+  /**
+   * Insert or update records. Records are validated, passed through `before*`
+   * side effects, frozen, and written. `after*` side effects run once every
+   * record in the call has been written.
+   */
+  put(records, phaseOverride) {
+    this.atomic(() => {
+      const source = this.source;
+      const callbacks = this.runCallbacks && this.sideEffects.isEnabled();
+      const created = [];
+      const changed = [];
+      for (const record of records) {
+        const id = record.id;
+        const existing = this.records.get(id);
+        const before = existing?.get();
+        if (before !== void 0) {
+          if (before === record) continue;
+          let next = this.schema.validateRecord(this, record, phaseOverride ?? "updateRecord", before);
+          if (callbacks) next = this.sideEffects.handleBeforeChange(before, next, source);
+          if (next === before || isRecordShallowEqual(before, next)) continue;
+          if (next.id !== id) {
+            throw new Error(`Cannot change the id of a record (${id} -> ${next.id})`);
+          }
+          freezeRecord(next);
+          if (before.typeName !== next.typeName) {
+            this.removeFromIndex(before.typeName, id);
+            this.addToIndex(next.typeName, id);
+          }
+          existing.set(next);
+          this.recordChange(id, before, next);
+          changed.push([before, next]);
+        } else {
+          let next = this.schema.validateRecord(this, record, phaseOverride ?? "createRecord", void 0);
+          if (callbacks) next = this.sideEffects.handleBeforeCreate(next, source);
+          if (next.id !== id) {
+            throw new Error(`Cannot change the id of a record (${id} -> ${next.id})`);
+          }
+          freezeRecord(next);
+          const a = existing ?? atom(`store:${this.id}:record:${id}`, void 0);
+          a.set(next);
+          this.records.set(id, a);
+          this.addToIndex(next.typeName, id);
+          this.recordChange(id, void 0, next);
+          created.push(next);
+        }
+      }
+      if (callbacks) {
+        for (const record of created) this.sideEffects.handleAfterCreate(record, source);
+        for (const [prev, next] of changed) this.sideEffects.handleAfterChange(prev, next, source);
+      }
+    });
+  }
+  /** Remove records by id. Missing ids are ignored. `beforeDelete` handlers may veto. */
+  remove(ids) {
+    this.atomic(() => {
+      const source = this.source;
+      const callbacks = this.runCallbacks && this.sideEffects.isEnabled();
+      const toRemove = [];
+      for (const id of ids) {
+        const a = this.records.get(id);
+        if (!a) continue;
+        const record = a.get();
+        if (record === void 0) continue;
+        if (callbacks && !this.sideEffects.handleBeforeDelete(record, source)) continue;
+        toRemove.push(record);
+      }
+      const removed = [];
+      for (const record of toRemove) {
+        const a = this.records.get(record.id);
+        if (!a) continue;
+        const current = a.get();
+        if (current === void 0) continue;
+        a.set(void 0);
+        this.records.delete(record.id);
+        this.removeFromIndex(current.typeName, record.id);
+        this.recordChange(record.id, current, void 0);
+        removed.push(current);
+      }
+      if (callbacks) {
+        for (const record of removed) this.sideEffects.handleAfterDelete(record, source);
+      }
+    });
+  }
+  /** Remove every record. */
+  clear() {
+    this.remove(Array.from(this.records.keys()));
+  }
+  /**
+   * Update one record with a function. No-op when the record does not exist.
+   */
+  update(id, updater) {
+    const current = this.unsafeGetWithoutCapture(id);
+    if (current === void 0) return;
+    this.put([updater(current)]);
+  }
+  /* ---- transactions ----------------------------------------------------- */
+  /**
+   * Run `fn` as one operation: side effects' `operationComplete` handlers run
+   * once at the end, and listeners get a single squashed history entry.
+   */
+  atomic(fn, options) {
+    const prevSource = this.source;
+    const prevRunCallbacks = this.runCallbacks;
+    if (options?.source !== void 0) this.source = options.source;
+    if (options?.runCallbacks !== void 0) this.runCallbacks = options.runCallbacks;
+    const source = this.source;
+    const runCallbacks = this.runCallbacks;
+    this.depth++;
+    try {
+      return transact(() => unsafe__withoutCapture(fn));
+    } finally {
+      this.depth--;
+      if (this.depth === 0) {
+        try {
+          this.completeOperation(source, runCallbacks);
+        } finally {
+          this.source = prevSource;
+          this.runCallbacks = prevRunCallbacks;
+        }
+      } else {
+        this.source = prevSource;
+        this.runCallbacks = prevRunCallbacks;
+      }
+    }
+  }
+  /** Changes made inside `fn` are reported to listeners with source `remote`. */
+  mergeRemoteChanges(fn) {
+    this.atomic(fn, { source: "remote" });
+  }
+  /** Run `fn` and return the squashed diff of everything it changed. Listeners are still notified. */
+  extractingChanges(fn) {
+    const diff = createEmptyRecordsDiff();
+    this.extractStack.push(diff);
+    try {
+      this.atomic(fn);
+    } finally {
+      this.extractStack.pop();
+    }
+    return diff;
+  }
+  /**
+   * Apply a diff (e.g. from `extractingChanges` or `reverseRecordsDiff`).
+   * With `ignoreEphemeralKeys`, ephemeral keys of updated records keep their
+   * current store values instead of the diff's.
+   */
+  applyDiff(diff, options) {
+    const runCallbacks = options?.runCallbacks ?? true;
+    const ignoreEphemeralKeys = options?.ignoreEphemeralKeys ?? false;
+    this.atomic(
+      () => {
+        const toPut = [];
+        for (const id in diff.added) toPut.push(diff.added[id]);
+        for (const id in diff.updated) {
+          let [, to] = diff.updated[id];
+          if (ignoreEphemeralKeys) {
+            const current = this.unsafeGetWithoutCapture(id);
+            const type = this.schema.getType(to.typeName);
+            if (current !== void 0 && type && type.ephemeralKeySet.size > 0) {
+              const merged = { ...to };
+              const cur = current;
+              for (const key of type.ephemeralKeySet) {
+                if (key in cur) merged[key] = cur[key];
+                else delete merged[key];
+              }
+              to = merged;
+            }
+          }
+          toPut.push(to);
+        }
+        this.put(toPut);
+        const toRemove = Object.keys(diff.removed);
+        if (toRemove.length > 0) this.remove(toRemove);
+      },
+      { runCallbacks }
+    );
+  }
+  /* ---- listening -------------------------------------------------------- */
+  /**
+   * Subscribe to history entries. Called after each outermost operation with
+   * the squashed changes, filtered by source and record scope.
+   */
+  listen(onHistory, filters) {
+    const listener = {
+      onHistory,
+      filters: { source: filters?.source ?? "all", scope: filters?.scope ?? "all" }
+    };
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /* ---- persistence ------------------------------------------------------ */
+  /** Plain-object snapshot of the records in `scope` (default `document`). */
+  serialize(scope = "document") {
+    const result = {};
+    unsafe__withoutCapture(() => {
+      for (const [id, a] of this.records) {
+        const record = a.get();
+        if (record === void 0) continue;
+        if (scope === "all" || this.getScope(record.typeName) === scope) result[id] = record;
+      }
+    });
+    return result;
+  }
+  getStoreSnapshot(scope = "document") {
+    return { store: this.serialize(scope), 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
+   * snapshot are removed unless the snapshot contains them; other scopes are
+   * left alone. Side effects do not run; listeners are notified.
+   */
+  loadStoreSnapshot(snapshot) {
+    const migrated = this.schema.migrateStoreSnapshot(snapshot);
+    if (migrated.type === "error") {
+      throw new Error(`Failed to migrate snapshot: ${migrated.reason}`);
+    }
+    const incoming = migrated.value;
+    const records = Object.values(incoming);
+    this.atomic(
+      () => {
+        const scopes = /* @__PURE__ */ new Set(["document"]);
+        for (const record of records) scopes.add(this.getScope(record.typeName));
+        const toRemove = [];
+        for (const [id, a] of this.records) {
+          const record = a.get();
+          if (record === void 0) continue;
+          if (scopes.has(this.getScope(record.typeName)) && !(id in incoming)) toRemove.push(id);
+        }
+        this.remove(toRemove);
+        this.put(records, "initialize");
+      },
+      { runCallbacks: false }
+    );
+  }
+  /* ---- derived caches --------------------------------------------------- */
+  /**
+   * A per-record derived value, recomputed only when that record changes.
+   * Entries are dropped automatically when records are removed.
+   */
+  createComputedCache(name, derive, options) {
+    const cache = /* @__PURE__ */ new WeakMap();
+    return {
+      get: (id) => {
+        const a = this.records.get(id);
+        if (!a) {
+          this.getTypeIndex(typeNameOfId(id)).epoch.get();
+          return void 0;
+        }
+        let c = cache.get(a);
+        if (!c) {
+          c = computed(
+            `${name}:${id}`,
+            () => {
+              const record = a.get();
+              return record === void 0 ? void 0 : derive(record);
+            },
+            options?.isEqual ? { isEqual: (x, y) => x === void 0 || y === void 0 ? x === y : options.isEqual(x, y) } : void 0
+          );
+          cache.set(a, c);
+        }
+        return c.get();
+      }
+    };
+  }
+  /* ---- lifecycle -------------------------------------------------------- */
+  isDisposed() {
+    return this.disposed;
+  }
+  dispose() {
+    this.disposed = true;
+    this.listeners.clear();
+  }
+  /* ---- internals -------------------------------------------------------- */
+  addToIndex(typeName, id) {
+    const index = this.getTypeIndex(typeName);
+    if (index.live.has(id)) return;
+    index.live.add(id);
+    index.epoch.update((n) => n + 1);
+  }
+  removeFromIndex(typeName, id) {
+    const index = this.typeIndexes.get(typeName);
+    if (!index || !index.live.delete(id)) return;
+    index.epoch.update((n) => n + 1);
+  }
+  recordChange(id, before, after) {
+    const last = this.pendingEntries[this.pendingEntries.length - 1];
+    let entry;
+    if (last && last.source === this.source) {
+      entry = last;
+    } else {
+      entry = { changes: createEmptyRecordsDiff(), source: this.source };
+      this.pendingEntries.push(entry);
+    }
+    applyChangeToDiff(entry.changes, id, before, after);
+    for (const diff of this.extractStack) applyChangeToDiff(diff, id, before, after);
+  }
+  completeOperation(source, runCallbacks) {
+    if (!this.pendingEntries.some((e) => !isRecordsDiffEmpty(e.changes))) {
+      this.pendingEntries = [];
+      return;
+    }
+    if (runCallbacks && this.sideEffects.isEnabled() && !this.inOperationComplete) {
+      this.inOperationComplete = true;
+      const prevSource = this.source;
+      this.source = source;
+      this.depth++;
+      try {
+        transact(() => unsafe__withoutCapture(() => this.sideEffects.handleOperationComplete(source)));
+      } finally {
+        this.depth--;
+        this.source = prevSource;
+        this.inOperationComplete = false;
+      }
+    }
+    this.history.update((n) => n + 1);
+    this.flushHistory();
+  }
+  flushHistory() {
+    const entries = this.pendingEntries;
+    this.pendingEntries = [];
+    if (this.listeners.size === 0) return;
+    for (const entry of entries) {
+      if (isRecordsDiffEmpty(entry.changes)) continue;
+      for (const listener of Array.from(this.listeners)) {
+        if (listener.filters.source !== "all" && listener.filters.source !== entry.source) continue;
+        const changes = listener.filters.scope === "all" ? entry.changes : this.filterDiffByScope(entry.changes, listener.filters.scope);
+        if (isRecordsDiffEmpty(changes)) continue;
+        listener.onHistory({ changes, source: entry.source });
+      }
+    }
+  }
+  filterDiffByScope(diff, scope) {
+    const result = createEmptyRecordsDiff();
+    for (const id in diff.added) {
+      const record = diff.added[id];
+      if (this.getScope(record.typeName) === scope) result.added[id] = record;
+    }
+    for (const id in diff.updated) {
+      const pair = diff.updated[id];
+      if (this.getScope(pair[1].typeName) === scope) result.updated[id] = pair;
+    }
+    for (const id in diff.removed) {
+      const record = diff.removed[id];
+      if (this.getScope(record.typeName) === scope) result.removed[id] = record;
+    }
+    return result;
+  }
+};
+function typeNameOfId(id) {
+  const colon = id.indexOf(":");
+  return colon > 0 ? id.slice(0, colon) : parseRecordId(id).typeName;
+}
+
+// src/tldr.ts
+var TLDR_FILE_FORMAT_VERSION = 1;
+function isPlainObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isSerializedSchema(value) {
+  return isPlainObject2(value) && typeof value["schemaVersion"] === "number";
+}
+function parseTldrFile(json) {
+  let data = json;
+  if (typeof json === "string") {
+    try {
+      data = JSON.parse(json);
+    } catch (cause) {
+      return { ok: false, error: "notATldrFile", cause };
+    }
+  }
+  if (!isPlainObject2(data)) return { ok: false, error: "notATldrFile" };
+  if (!("tldrawFileFormatVersion" in data)) {
+    const legacyDocument = data["document"];
+    if (isPlainObject2(legacyDocument) && ("pages" in legacyDocument || "version" in legacyDocument)) {
+      return { ok: false, error: "v1File" };
+    }
+    return { ok: false, error: "notATldrFile" };
+  }
+  const version = data["tldrawFileFormatVersion"];
+  if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
+    return { ok: false, error: "notATldrFile" };
+  }
+  if (version > TLDR_FILE_FORMAT_VERSION) return { ok: false, error: "futureVersion" };
+  if (!isSerializedSchema(data["schema"])) return { ok: false, error: "notATldrFile" };
+  const records = data["records"];
+  if (!Array.isArray(records)) return { ok: false, error: "invalidRecords" };
+  const seen = /* @__PURE__ */ new Set();
+  for (const record of records) {
+    if (!isRecordLike(record)) return { ok: false, error: "invalidRecords" };
+    if (seen.has(record.id)) return { ok: false, error: "invalidRecords" };
+    seen.add(record.id);
+  }
+  return { ok: true, schema: data["schema"], records };
+}
+function sortKeysDeep(value) {
+  if (Array.isArray(value)) return value.map(sortKeysDeep);
+  if (isPlainObject2(value)) {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      const v = value[key];
+      if (v !== void 0) out[key] = sortKeysDeep(v);
+    }
+    return out;
+  }
+  return value;
+}
+function serializeTldrFile(schema, records) {
+  const envelope = {
+    tldrawFileFormatVersion: TLDR_FILE_FORMAT_VERSION,
+    schema: sortKeysDeep(schema),
+    records: records.map(sortKeysDeep)
+  };
+  return JSON.stringify(envelope, null, 2);
+}
+function tldrFileToStoreSnapshot(file) {
+  const store = {};
+  for (const record of file.records) store[record.id] = record;
+  return { store, schema: file.schema };
+}
+function storeSnapshotToTldrFile(snapshot) {
+  const records = Object.values(snapshot.store).sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+  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 };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map