@mocanvas/store 1.0.0 → 4.0.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { Computed, Atom } from '@mocanvas/state';
+export { AtomMap, AtomSet } from '@mocanvas/state';
 
 /** Length of the unique part of a generated record id. */
 declare const UNIQUE_ID_LENGTH = 21;
@@ -33,8 +34,13 @@ interface StoreValidator<R extends UnknownRecord> {
      * Optional fast path: validate `newRecord` knowing that `knownGoodVersion`
      * is a valid record of the same type. Implementations may skip the parts
      * that did not change.
+     *
+     * Declared as a property that may be `undefined` rather than as an optional
+     * method, so that a validator carrying an explicit `undefined` — which is
+     * what a class with an optional constructor argument produces — still
+     * satisfies this under `exactOptionalPropertyTypes`.
      */
-    validateUsingKnownGoodVersion?(knownGoodVersion: R, newRecord: unknown): R;
+    validateUsingKnownGoodVersion?: ((knownGoodVersion: R, newRecord: unknown) => R) | undefined;
 }
 /** Keys of `R` that hold data (everything except `id` and `typeName`). */
 type RecordDataKeys<R extends UnknownRecord> = Exclude<keyof R, "id" | "typeName">;
@@ -184,6 +190,101 @@ declare function squashRecordDiffs<R extends UnknownRecord>(diffs: readonly Reco
 /** Shallow-copy a diff (entries are shared). */
 declare function cloneRecordsDiff<R extends UnknownRecord>(diff: RecordsDiff<R>): RecordsDiff<R>;
 
+/**
+ * The pre-sequence migration format, and the reasons a migration can fail.
+ *
+ * Before migrations were named sequences, a schema declared one integer version
+ * per record type plus one for the store, and a table of numbered up/down
+ * functions between them. mocanvas never *writes* that format — {@link
+ * SerializedSchemaV1} exists so a document saved by something that did can
+ * still be recognised and loaded, and so a schema written against the old shape
+ * can still be described.
+ *
+ * Nothing here changes what mocanvas persists. See `StoreSchema.serialize`,
+ * which always produces the v2 shape.
+ */
+/**
+ * The persisted schema shape used before migration sequences: a version number
+ * per record type, and one for the store as a whole.
+ *
+ * Read-only as far as mocanvas is concerned. A snapshot carrying one is treated
+ * as knowing none of today's sequences, so every retroactive sequence runs from
+ * the beginning — which is right, because none of them existed when the file
+ * was written.
+ */
+interface SerializedSchemaV1 {
+    schemaVersion: 1;
+    storeVersion: number;
+    recordVersions: Record<string, {
+        version: number;
+    } | {
+        version: number;
+        subTypeVersions: Record<string, number>;
+        subTypeKey: string;
+    }>;
+}
+/** Whether a persisted schema is in the pre-sequence format. */
+declare function isSerializedSchemaV1(schema: {
+    schemaVersion: number;
+}): schema is SerializedSchemaV1;
+/** One numbered step of a {@link LegacyMigrations} table. */
+interface LegacyMigration<Before = any, After = any> {
+    up: (oldState: Before) => After;
+    down: (newState: After) => Before;
+}
+/** The version bounds every legacy migration table declares. */
+interface LegacyBaseMigrationsInfo {
+    firstVersion: number;
+    currentVersion: number;
+    migrators: {
+        [version: number]: LegacyMigration;
+    };
+}
+/**
+ * A legacy migration table: the version range it covers, the numbered steps,
+ * and optionally the sub-type split a record type used (a shape's `type`, say,
+ * each with its own version line).
+ */
+interface LegacyMigrations extends LegacyBaseMigrationsInfo {
+    subTypeKey?: string;
+    subTypeMigrations?: Record<string, LegacyBaseMigrationsInfo>;
+}
+/**
+ * A dependency declared by a standalone migration sequence: it must run after
+ * (or before) another sequence's numbered migration, even though neither owns
+ * the other.
+ *
+ * Ordering between sequences is otherwise registration order, which is fine
+ * until one sequence's `up` reads a field another sequence is still about to
+ * add.
+ */
+interface StandaloneDependsOn {
+    dependsOn: readonly string[];
+}
+/**
+ * Why loading a persisted snapshot failed.
+ *
+ * These are the cases worth telling apart in a UI: "this file is from a newer
+ * version of the app" is a message a user can act on, and
+ * "migrationError" is not.
+ */
+declare const MigrationFailureReason: {
+    /** The persisted schema names a sequence version higher than this schema knows. */
+    readonly TargetVersionTooNew: "target-version-too-new";
+    /** The persisted data is older than the oldest migration that survives. */
+    readonly TargetVersionTooOld: "target-version-too-old";
+    /** A record's type is not registered in this schema and cannot be migrated. */
+    readonly UnrecognizedType: "unrecognized-type";
+    /** A migration function threw. */
+    readonly MigrationError: "migration-error";
+    /** The persisted schema itself is malformed. */
+    readonly IncompatibleSubtype: "incompatible-subtype";
+    /** The persisted schema version is not one this store understands. */
+    readonly UnknownSchemaVersion: "unknown-schema-version";
+};
+/** One of the {@link MigrationFailureReason} values. */
+type MigrationFailureReason = (typeof MigrationFailureReason)[keyof typeof MigrationFailureReason];
+
 /** Serialized records keyed by id. */
 type SerializedStore<R extends UnknownRecord> = Record<IdOf<R>, R>;
 /**
@@ -196,7 +297,15 @@ interface SerializedSchemaV2 {
         [sequenceId: string]: number;
     };
 }
-type SerializedSchema = SerializedSchemaV2;
+/**
+ * A persisted schema, in either format mocanvas can read.
+ *
+ * Only {@link SerializedSchemaV2} is ever *written* — see
+ * `StoreSchema.serialize`. The v1 arm is here so a document saved by an older,
+ * pre-sequence writer is still loadable rather than being rejected as
+ * "unsupported schema version".
+ */
+type SerializedSchema = SerializedSchemaV1 | SerializedSchemaV2;
 type MigrationId = `${string}/${number}`;
 interface RecordMigration {
     readonly id: MigrationId;
@@ -273,6 +382,75 @@ declare function applyRecordMigration(migration: RecordMigration, record: Unknow
 /** Apply one migration (record- or store-scoped) to a whole store in place. */
 declare function applyMigrationToStore(migration: Migration, store: SerializedStore<UnknownRecord>, direction: "up" | "down"): SerializedStore<UnknownRecord>;
 
+/**
+ * What changed in a set: the members added and the members removed.
+ *
+ * Either side may be absent, which means "nothing on that side" — a diff with
+ * neither is a diff that says nothing happened.
+ */
+interface CollectionDiff<T> {
+    added?: Set<T>;
+    removed?: Set<T>;
+}
+/**
+ * How one property of a record is matched.
+ *
+ * SEMANTICS-ASSUMED: three comparisons — equality, inequality and a numeric
+ * greater-than — are what an index can answer without scanning, which is the
+ * whole reason queries are data rather than functions. `gt` is deliberately
+ * numeric: the only ordered property records carry is a number.
+ */
+type QueryValueMatcher<T> = {
+    eq: T;
+} | {
+    neq: T;
+} | {
+    gt: number;
+};
+/**
+ * A query over the records of one type: property name to matcher, every entry
+ * of which must hold (they are ANDed).
+ *
+ * ```ts
+ * store.query.records("shape", () => ({ type: { eq: "geo" }, isLocked: { eq: false } }))
+ * ```
+ */
+type QueryExpression<R extends object> = {
+    [K in keyof R]?: QueryValueMatcher<R[K]>;
+};
+/**
+ * An index over one property of one record type: for each value that property
+ * takes, the ids of the records that hold it.
+ */
+type RSIndexMap<R extends UnknownRecord, Property extends keyof R & string = keyof R & string> = Map<R[Property], Set<IdOf<R>>>;
+/** How an {@link RSIndexMap} changed: per property value, which ids joined and left. */
+type RSIndexDiff<R extends UnknownRecord, Property extends keyof R & string = keyof R & string> = Map<R[Property], CollectionDiff<IdOf<R>>>;
+/**
+ * A live index over one property, as a diff-carrying signal.
+ *
+ * Reading it gives the current {@link RSIndexMap}; asking it for the diffs
+ * since a past epoch gives {@link RSIndexDiff}s that describe how to get from
+ * the old map to the new one.
+ */
+type RSIndex<R extends UnknownRecord, Property extends keyof R & string = keyof R & string> = Computed<RSIndexMap<R, Property>, RSIndexDiff<R, Property>>;
+/** Whether `value` satisfies `matcher`. */
+declare function matchesQueryValue<T>(matcher: QueryValueMatcher<T>, value: T): boolean;
+/** Whether `record` satisfies every entry of `query`. An empty query matches everything. */
+declare function matchesQuery<R extends object>(query: QueryExpression<R>, record: R): boolean;
+/**
+ * The property this query can be answered from an index on, or `undefined`
+ * when none of it is indexable.
+ *
+ * Only an `eq` clause narrows to a single index bucket; `neq` and `gt` still
+ * need every bucket looked at, so they are no better than a scan. The first
+ * `eq` wins — the remaining clauses are checked against the records it yields.
+ */
+declare function getIndexablePropertyOf<R extends object>(query: QueryExpression<R>): (keyof R & string) | undefined;
+/** Apply a {@link CollectionDiff} to a set, in place. */
+declare function applyCollectionDiff<T>(set: Set<T>, diff: CollectionDiff<T>): Set<T>;
+/** Whether a {@link CollectionDiff} describes no change at all. */
+declare function isCollectionDiffEmpty<T>(diff: CollectionDiff<T>): boolean;
+
 type ChangeSource = "user" | "remote";
 interface HistoryEntry<R extends UnknownRecord> {
     changes: RecordsDiff<R>;
@@ -287,6 +465,38 @@ type RecordFromTypeName<R extends UnknownRecord, T extends string> = Extract<R,
     typeName: T;
 }>;
 type StoreRecord<S extends Store<any, any>> = S extends Store<infer R, any> ? R : never;
+/**
+ * Anything that owns a store: a `Store` itself, or an object holding one (an
+ * `Editor`). Written for the helpers that want to accept either without their
+ * callers having to reach for `.store`.
+ */
+type StoreObject<R extends UnknownRecord = UnknownRecord> = Store<R, any> | {
+    store: Store<R, any>;
+};
+/** The record union of whatever store a {@link StoreObject} carries. */
+type StoreObjectRecordType<Context extends StoreObject<any>> = Context extends Store<infer R, any> ? R : Context extends {
+    store: Store<infer R, any>;
+} ? R : never;
+/** A validator per record type, as `StoreSchema` collects them from the record types. */
+type StoreValidators<R extends UnknownRecord> = {
+    [TypeName in R["typeName"]]: StoreValidator<Extract<R, {
+        typeName: TypeName;
+    }>>;
+};
+/**
+ * A record that failed validation, with enough context to say what was being
+ * done to it at the time.
+ *
+ * Thrown rather than returned: a store that keeps going after writing an
+ * invalid record is a store whose next save produces a file nothing can load.
+ */
+interface StoreError {
+    error: Error;
+    phase: "initialize" | "createRecord" | "updateRecord" | "tests";
+    recordBefore?: unknown;
+    recordAfter: unknown;
+    isExistingValidationIssue: boolean;
+}
 interface StoreOptions<R extends UnknownRecord, Props> {
     schema: StoreSchema<R, Props>;
     initialData?: SerializedStore<R> | undefined;
@@ -364,19 +574,61 @@ interface TypeIndex<R extends UnknownRecord> {
     readonly epoch: Atom<number>;
 }
 /** Reactive views over the store's records, cached per type name. */
+/**
+ * How the records of one type are narrowed: a predicate, or a declarative
+ * {@link QueryExpression} the store can answer from an index.
+ *
+ * Prefer the query object. A predicate has to be run against every record of
+ * the type; a query with an `eq` clause is answered from an index bucket.
+ */
+type StoreQueryFilter<Rec extends UnknownRecord> = ((record: Rec) => boolean) | QueryExpression<Rec>;
 declare class StoreQueries<R extends UnknownRecord> {
     private readonly store;
     private readonly idsCache;
     private readonly recordsCache;
+    private readonly indexCache;
+    private readonly historyCache;
     constructor(store: Store<R, any>);
-    /** The set of ids of every record of `typeName`. Maintained incrementally. */
-    ids<T extends R["typeName"]>(typeName: T): Computed<ReadonlySet<IdOf<RecordFromTypeName<R, T>>>>;
-    /** Every record of `typeName`, in insertion order. */
-    records<T extends R["typeName"]>(typeName: T): Computed<RecordFromTypeName<R, T>[]>;
-    /** The first record of `typeName` matching `predicate` (or the first record, when omitted). */
-    record<T extends R["typeName"]>(typeName: T, predicate?: (record: RecordFromTypeName<R, T>) => boolean): Computed<RecordFromTypeName<R, T> | undefined>;
+    /**
+     * The set of ids of every record of `typeName`, optionally narrowed by a
+     * filter. Maintained incrementally.
+     */
+    ids<T extends R["typeName"]>(typeName: T, filter?: StoreQueryFilter<RecordFromTypeName<R, T>>): Computed<ReadonlySet<IdOf<RecordFromTypeName<R, T>>>>;
+    /**
+     * 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<T extends R["typeName"]>(typeName: T, filter?: StoreQueryFilter<RecordFromTypeName<R, T>>): Computed<RecordFromTypeName<R, T>[]>;
+    private filteredRecords;
+    /** The first record of `typeName` matching `filter` (or the first record, when omitted). */
+    record<T extends R["typeName"]>(typeName: T, filter?: StoreQueryFilter<RecordFromTypeName<R, T>>): Computed<RecordFromTypeName<R, T> | undefined>;
     /** Non-reactive filter over the records of `typeName`. */
-    exec<T extends R["typeName"]>(typeName: T, predicate: (record: RecordFromTypeName<R, T>) => boolean): RecordFromTypeName<R, T>[];
+    exec<T extends R["typeName"]>(typeName: T, filter: StoreQueryFilter<RecordFromTypeName<R, T>>): RecordFromTypeName<R, T>[];
+    /**
+     * 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<T extends R["typeName"], Property extends keyof RecordFromTypeName<R, T> & string>(typeName: T, property: Property): RSIndex<RecordFromTypeName<R, T>, Property>;
+    private buildIndex;
+    /**
+     * 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<T extends R["typeName"]>(typeName: T): Computed<number, RecordsDiff<RecordFromTypeName<R, T>>>;
 }
 /**
  * A reactive, transactional collection of records.
@@ -395,8 +647,16 @@ declare class Store<R extends UnknownRecord = UnknownRecord, Props = unknown> {
     };
     readonly sideEffects: StoreSideEffects<R>;
     readonly query: StoreQueries<R>;
-    /** Bumped once per completed operation that changed something. */
-    readonly history: Atom<number>;
+    /**
+     * 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.
+     */
+    readonly history: Atom<number, RecordsDiff<R>>;
     private readonly records;
     private readonly typeIndexes;
     private readonly listeners;
@@ -407,6 +667,12 @@ declare class Store<R extends UnknownRecord = UnknownRecord, Props = unknown> {
     private runCallbacks;
     private inOperationComplete;
     private disposed;
+    /**
+     * 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.
+     */
+    private pendingHistoryDiff;
     constructor(options: StoreOptions<R, Props>);
     /** @internal */
     getTypeIndex(typeName: string): TypeIndex<R>;
@@ -462,6 +728,22 @@ declare class Store<R extends UnknownRecord = UnknownRecord, Props = unknown> {
     /** Plain-object snapshot of the records in `scope` (default `document`). */
     serialize(scope?: RecordScope | "all"): SerializedStore<R>;
     getStoreSnapshot(scope?: RecordScope | "all"): StoreSnapshot<R>;
+    /**
+     * 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: StoreSnapshot<R>): StoreSnapshot<R>;
     /**
      * Replace the store's contents with a snapshot (migrating it first).
      * Existing records in `document` scope and in every scope present in the
@@ -484,6 +766,8 @@ declare class Store<R extends UnknownRecord = UnknownRecord, Props = unknown> {
     private removeFromIndex;
     private recordChange;
     private completeOperation;
+    /** One diff describing everything the operation just committed changed. */
+    private squashPendingEntries;
     private flushHistory;
     private filterDiffByScope;
 }
@@ -537,16 +821,17 @@ declare class StoreSchema<R extends UnknownRecord, Props = unknown> {
      * a load/save round-trip.
      */
     validateRecord(store: Store<R, any>, record: R, phase: StoreValidationPhase, recordBefore: R | undefined): R;
-    /** The current version of every sequence. */
-    serialize(): SerializedSchema;
+    /** The current version of every sequence. Always the v2 shape — mocanvas never writes v1. */
+    serialize(): SerializedSchemaV2;
     /** A schema at version 0 of every sequence (all migrations still pending). */
-    serializeEarliestVersion(): SerializedSchema;
+    serializeEarliestVersion(): SerializedSchemaV2;
     /**
      * 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: SerializedSchema): MigrationResult<Migration[]>;
+    private migrationsSince;
     /**
      * Migrate a single record. Only record-scoped migrations can be applied;
      * encountering a store-scoped one is an error. `down` runs the migrations
@@ -604,4 +889,188 @@ declare function storeSnapshotToTldrFile(snapshot: {
     schema: SerializedSchema;
 }): string;
 
-export { type BaseRecord, type ChangeSource, type EphemeralKeys, type HistoryEntry, type IdOf, type IndexKey, type Migration, type MigrationId, type MigrationResult, type MigrationSequence, type ParseTldrFileResult, type RecordCreateProps, type RecordDataKeys, type RecordFromId, type RecordFromTypeName, type RecordId, type RecordMigration, type RecordScope, RecordType, type RecordTypeConfig, type RecordTypeMap, type RecordsDiff, type SerializedSchema, type SerializedSchemaV2, type SerializedStore, Store, type StoreAfterChangeHandler, type StoreAfterCreateHandler, type StoreAfterDeleteHandler, type StoreBeforeChangeHandler, type StoreBeforeCreateHandler, type StoreBeforeDeleteHandler, type StoreListener, type StoreListenerFilters, type StoreMigration, type StoreOperationCompleteHandler, type StoreOptions, StoreQueries, type StoreRecord, StoreSchema, type StoreSchemaOptions, type StoreSideEffectHandlers, StoreSideEffects, type StoreSnapshot, type StoreValidationFailure, type StoreValidationPhase, type StoreValidator, TLDR_FILE_FORMAT_VERSION, type TldrFile, type TldrFileParseError, UNIQUE_ID_LENGTH, type UnknownRecord, ZERO_INDEX_KEY, ZKEY_SIGNIFICANT_DIGITS, type ZKey, 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 };
+/**
+ * Standalone per-record memos.
+ *
+ * `Store.createComputedCache` already memoizes a value per record, but it is a
+ * method: the cache belongs to one store instance, and the derivation cannot see
+ * anything else. A shape util or binding util usually needs the opposite shape —
+ * one cache declared once at module scope, derived from a record *and* the editor
+ * that owns it, and shared by every store that editor drives.
+ *
+ * `createComputedCache` is that form. The context is passed in at `get` time and
+ * the underlying per-record cache is created lazily, once per context.
+ */
+
+/**
+ * A context a computed cache can read a store from: a store itself, or anything
+ * holding one (an `Editor`).
+ */
+type ComputedCacheContext = Store<any, any> | {
+    readonly store: Store<any, any>;
+};
+/** The handle returned by {@link createComputedCache}. */
+interface ComputedCache<Context, R extends UnknownRecord, Result> {
+    /** The derived value for `id`, or `undefined` if no such record exists. */
+    get(context: Context, id: IdOf<R>): Result | undefined;
+}
+/** Options for {@link createComputedCache}. */
+interface CreateComputedCacheOptions<Result> {
+    /**
+     * Treat two derived values as the same, so dependents are not woken when the
+     * derivation recomputes to an equivalent result.
+     */
+    isEqual?: ((a: Result, b: Result) => boolean) | undefined;
+}
+/**
+ * Declare a per-record memo, keyed by record id, recomputed only when that
+ * record changes.
+ *
+ * ```ts
+ * const bindingsCache = createComputedCache("connection bindings", (editor: Editor, shape: TLShape) =>
+ *   editor.getBindingsFromShape(shape.id, "connection"),
+ * )
+ * bindingsCache.get(editor, shapeId)
+ * ```
+ *
+ * SEMANTICS-ASSUMED: `Context` is unconstrained rather than bound to
+ * {@link ComputedCacheContext}. The consumer annotates the derivation's own
+ * parameter (`(editor: Editor, shape: TLShape) => …`) and that is what `get`
+ * must accept; constraining the type parameter as well would force every caller
+ * to prove `Editor` is structurally a store holder at each call site for no
+ * added safety. The store is resolved at `get` time instead, and a context that
+ * carries none throws immediately rather than silently returning `undefined`.
+ */
+declare function createComputedCache<Context, R extends UnknownRecord, Result>(name: string, derive: (context: Context, record: R) => Result, options?: CreateComputedCacheOpts<Result, R>): ComputedCache<Context, R, Result>;
+/**
+ * Options for {@link createComputedCache}, including the record-level equality
+ * that decides when a derivation is worth re-running at all.
+ */
+type CreateComputedCacheOpts<Result, R extends UnknownRecord = UnknownRecord> = CreateComputedCacheOptions<Result> & {
+    /**
+     * Treat two versions of the *record* as the same, so the derivation is not
+     * re-run when only parts it does not read have changed.
+     *
+     * `isEqual` compares results and can only save the dependents work;
+     * `areRecordsEqual` compares inputs and saves the derivation itself. Use it
+     * when the derivation is expensive and reads only a couple of fields —
+     * geometry from `props`, say, which should not be rebuilt because the shape
+     * moved.
+     */
+    areRecordsEqual?: ((a: R, b: R) => boolean) | undefined;
+};
+
+/**
+ * Two small guards the store leans on: a development-only deep freeze, and an
+ * id assertion that narrows.
+ */
+
+/**
+ * Deep-freeze `object` in development builds, and hand it straight back in
+ * production.
+ *
+ * Records in the store are shared by reference with every consumer that read
+ * them, so mutating one in place skips the whole change pipeline: no diff, no
+ * side effects, no listeners, and an undo that silently does nothing. Freezing
+ * turns that from a bug someone finds a week later into a `TypeError` on the
+ * line that did it. The check is skipped in production because freezing every
+ * record on every write is not free.
+ *
+ * Already-frozen objects are left alone, so re-freezing a record that came out
+ * of the store costs one property read.
+ */
+declare function devFreeze<T>(object: T): T;
+/**
+ * Assert that `id` belongs to `type`, narrowing it to that type's id.
+ *
+ * Record ids are branded strings, so the compiler already stops most mix-ups —
+ * but ids that arrive from outside the program (a URL, a saved file, a sync
+ * message) are plain strings that someone has to vouch for. This is the place
+ * to do that vouching: it throws with the offending id rather than letting a
+ * `page:` id be looked up as a shape and quietly returning `undefined`.
+ *
+ * ```ts
+ * assertIdType(idFromUrl, PageRecordType)
+ * editor.setCurrentPage(idFromUrl) // now typed as TLPageId
+ * ```
+ */
+declare function assertIdType<R extends UnknownRecord>(id: string | undefined, type: RecordType<R, any>): asserts id is IdOf<R>;
+
+/**
+ * The synchronous storage contract a store can be backed by.
+ *
+ * Deliberately synchronous and deliberately tiny: it is the shape an embedded
+ * key-value store (a SQLite table, a `Map`, an in-process test double) already
+ * has, so a host can hand one over without writing an adapter. Anything
+ * asynchronous — a network, IndexedDB — belongs behind a snapshot load and save
+ * rather than behind this.
+ */
+
+/**
+ * Somewhere records can be read from and written to, one at a time, without
+ * awaiting.
+ *
+ * Implementations must be consistent within a call: `getAll` reflects every
+ * `set` and `delete` that has already returned.
+ */
+interface SynchronousRecordStorage<R extends UnknownRecord = UnknownRecord> {
+    /** The record stored under `id`, or `undefined`. */
+    get(id: IdOf<R>): R | undefined;
+    /** Every stored record. Order is not significant. */
+    getAll(): R[];
+    /** Store `record` under its own id, replacing anything already there. */
+    set(record: R): void;
+    /** Remove the record stored under `id`. Removing an absent id is not an error. */
+    delete(id: IdOf<R>): void;
+    /** Remove every record. */
+    clear(): void;
+}
+/**
+ * Record storage that also remembers the schema its records were written
+ * against, so they can be migrated when they are read back.
+ *
+ * Storing records without their schema is the one mistake that cannot be
+ * recovered from later: there is no way to tell which migrations have already
+ * run, and re-running them corrupts the data.
+ */
+interface SynchronousStorage<R extends UnknownRecord = UnknownRecord> extends SynchronousRecordStorage<R> {
+    /** The schema the stored records were written against, or `undefined` when empty. */
+    getSchema(): SerializedSchema | undefined;
+    /** Record the schema the stored records are written against. */
+    setSchema(schema: SerializedSchema): void;
+}
+/**
+ * A {@link SynchronousStorage} backed by a plain `Map`.
+ *
+ * Useful in tests and as the reference implementation of the contract — the
+ * shortest correct answer to "what does a storage have to do?".
+ */
+declare function createInMemoryStorage<R extends UnknownRecord = UnknownRecord>(): SynchronousStorage<R>;
+
+/**
+ * Grapheme cluster iteration.
+ *
+ * "One character" as a person sees it is a grapheme cluster, not a UTF-16 code
+ * unit and not a code point: `👩‍👩‍👧` is one, `é` written as `e` + a combining
+ * accent is one, and a flag emoji is one. Anything that measures, truncates or
+ * steps through text a character at a time has to walk clusters or it will cut a
+ * family emoji in half.
+ */
+/**
+ * Iterate the grapheme clusters of `str`.
+ *
+ * Uses `Intl.Segmenter` where it exists and falls back to code-point iteration
+ * otherwise — which keeps surrogate pairs intact (so a plain emoji survives) but
+ * cannot join a ZWJ sequence or a combining mark to its base.
+ *
+ * ```ts
+ * [...iterateGraphemes("a👍🏽b")] // ["a", "👍🏽", "b"]
+ * ```
+ */
+declare function iterateGraphemes(str: string): Generator<string, void, undefined>;
+/** The grapheme clusters of `str`, as an array. */
+declare function getGraphemes(str: string): string[];
+/** How many grapheme clusters `str` has — its length as a reader would count it. */
+declare function getGraphemeLength(str: string): number;
+
+export { type BaseRecord, type ChangeSource, type CollectionDiff, type ComputedCache, type ComputedCacheContext, type CreateComputedCacheOptions, type CreateComputedCacheOpts, type EphemeralKeys, type HistoryEntry, type IdOf, type IndexKey, type LegacyBaseMigrationsInfo, type LegacyMigration, type LegacyMigrations, type Migration, MigrationFailureReason, type MigrationId, type MigrationResult, type MigrationSequence, type ParseTldrFileResult, type QueryExpression, type QueryValueMatcher, type RSIndex, type RSIndexDiff, type RSIndexMap, type RecordCreateProps, type RecordDataKeys, type RecordFromId, type RecordFromTypeName, type RecordId, type RecordMigration, type RecordScope, RecordType, type RecordTypeConfig, type RecordTypeMap, type RecordsDiff, type SerializedSchema, type SerializedSchemaV1, type SerializedSchemaV2, type SerializedStore, type StandaloneDependsOn, Store, type StoreAfterChangeHandler, type StoreAfterCreateHandler, type StoreAfterDeleteHandler, type StoreBeforeChangeHandler, type StoreBeforeCreateHandler, type StoreBeforeDeleteHandler, type StoreError, type StoreListener, type StoreListenerFilters, type StoreMigration, type StoreObject, type StoreObjectRecordType, type StoreOperationCompleteHandler, type StoreOptions, StoreQueries, type StoreQueryFilter, type StoreRecord, StoreSchema, type StoreSchemaOptions, type StoreSideEffectHandlers, StoreSideEffects, type StoreSnapshot, type StoreValidationFailure, type StoreValidationPhase, type StoreValidator, type StoreValidators, type SynchronousRecordStorage, type SynchronousStorage, TLDR_FILE_FORMAT_VERSION, type TldrFile, type TldrFileParseError, UNIQUE_ID_LENGTH, type UnknownRecord, ZERO_INDEX_KEY, ZKEY_SIGNIFICANT_DIGITS, type ZKey, 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 };