@mocanvas/store 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Symbio Digital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# @mocanvas/store
+
+The document model behind [mocanvas](https://github.com/SYMBIO/mocanvas): a
+reactive record store with a typed schema, migrations, record diffs and
+`.tldr` file IO. Built on `@mocanvas/state`; no React.
+
+## Install
+
+```bash
+npm install @mocanvas/store
+```
+
+## Use
+
+```ts
+import { createRecordType, Store, StoreSchema, type BaseRecord, type RecordId } from "@mocanvas/store"
+
+interface Book extends BaseRecord<"book", RecordId<Book>> {
+  title: string
+}
+
+const BookRecord = createRecordType<Book>("book", { scope: "document" })
+const store = new Store({ schema: StoreSchema.create({ book: BookRecord }), props: {} })
+
+store.listen(({ changes }) => console.log(changes))
+store.put([BookRecord.create({ title: "Dune" })])
+```
+
+Records are reactive: `store.query` exposes signals you can read from
+`@mocanvas/state` computeds and React components.
+
+ESM only. See the [repository](https://github.com/SYMBIO/mocanvas) for the
+rest of the packages.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,607 @@
+import { Computed, Atom } from '@mocanvas/state';
+
+/** Length of the unique part of a generated record id. */
+declare const UNIQUE_ID_LENGTH = 21;
+/** Generate a URL-safe unique id (21 chars by default). */
+declare function uniqueId(size?: number): string;
+/**
+ * A branded string id. The brand carries the record type so that ids of
+ * different record types cannot be mixed up at compile time.
+ */
+type RecordId<R extends UnknownRecord> = string & {
+    __type__: R;
+};
+/** Every record has an id and a type name. */
+interface BaseRecord<TypeName extends string, Id extends RecordId<UnknownRecord>> {
+    readonly id: Id;
+    readonly typeName: TypeName;
+}
+type UnknownRecord = BaseRecord<string, RecordId<UnknownRecord>>;
+type IdOf<R extends UnknownRecord> = R["id"];
+/** Extract the record type an id refers to. */
+type RecordFromId<K extends RecordId<UnknownRecord>> = K extends RecordId<infer R> ? R : never;
+/**
+ * Where a record lives:
+ * - `document`: persisted, shared between collaborators (shapes, pages, ...)
+ * - `session`: persisted locally only (camera, current page, ...)
+ * - `presence`: shared but never persisted (cursors, ...)
+ */
+type RecordScope = "document" | "session" | "presence";
+interface StoreValidator<R extends UnknownRecord> {
+    validate(record: unknown): R;
+    /**
+     * 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.
+     */
+    validateUsingKnownGoodVersion?(knownGoodVersion: R, newRecord: unknown): R;
+}
+/** Keys of `R` that hold data (everything except `id` and `typeName`). */
+type RecordDataKeys<R extends UnknownRecord> = Exclude<keyof R, "id" | "typeName">;
+type EphemeralKeys<R extends UnknownRecord> = {
+    readonly [K in RecordDataKeys<R>]: boolean;
+};
+interface RecordTypeConfig<R extends UnknownRecord> {
+    readonly scope: RecordScope;
+    readonly validator?: StoreValidator<R> | undefined;
+    /**
+     * Keys whose changes should not be considered "real" document changes,
+     * e.g. transient UI flags. Used by `Store.applyDiff({ ignoreEphemeralKeys })`.
+     */
+    readonly ephemeralKeys?: EphemeralKeys<R> | undefined;
+}
+/**
+ * Properties the caller must pass to `create()`: the record's data keys minus
+ * whatever `withDefaultProperties` provides. `id` is always optional.
+ */
+type RecordCreateProps<R extends UnknownRecord, RequiredProps extends keyof R> = Pick<R, RequiredProps> & Partial<Omit<R, RequiredProps | "typeName">>;
+/**
+ * Describes one kind of record in the store: how to make ids, defaults,
+ * validation, and where the record lives (its scope).
+ */
+declare class RecordType<R extends UnknownRecord, RequiredProps extends keyof R = RecordDataKeys<R>> {
+    private readonly config;
+    readonly typeName: R["typeName"];
+    readonly scope: RecordScope;
+    readonly validator: StoreValidator<R> | undefined;
+    readonly ephemeralKeys: EphemeralKeys<R> | undefined;
+    readonly ephemeralKeySet: ReadonlySet<string>;
+    constructor(typeName: R["typeName"], config: RecordTypeConfig<R> & {
+        readonly createDefaultProperties: () => Partial<Omit<R, "id" | "typeName">>;
+    });
+    /** Create a new record with defaults applied. A fresh id is generated when none is given. */
+    create(properties: RecordCreateProps<R, RequiredProps>): R;
+    /** Shallow-clone a record (props/meta are shared). */
+    clone(record: R): R;
+    /** Make an id of this type: `${typeName}:${uniquePart}`. */
+    createId(customUniquePart?: string): IdOf<R>;
+    /** Recover the unique part of an id of this type. */
+    parseId(id: IdOf<R>): string;
+    isId(id?: string): id is IdOf<R>;
+    isInstance(record?: unknown): record is R;
+    /**
+     * Return a new RecordType whose `create()` fills in the given defaults, so
+     * those properties become optional for callers.
+     */
+    withDefaultProperties<DefaultProps extends RecordDataKeys<R>>(createDefaultProperties: () => Pick<R, DefaultProps>): RecordType<R, Exclude<RequiredProps, DefaultProps>>;
+    /** Run the validator (if any). Throws on invalid input. */
+    validate(record: unknown, recordBefore?: R): R;
+}
+/**
+ * Define a record type.
+ *
+ * ```ts
+ * const Book = createRecordType<Book>('book', { scope: 'document' })
+ *   .withDefaultProperties(() => ({ inStock: true }))
+ * const b = Book.create({ title: 'Dune' })  // -> { id: 'book:...', typeName: 'book', title, inStock }
+ * ```
+ */
+declare function createRecordType<R extends UnknownRecord>(typeName: R["typeName"], config: RecordTypeConfig<R>): RecordType<R, RecordDataKeys<R>>;
+/** Split any `${typeName}:${unique}` id into its parts. */
+declare function parseRecordId(id: string): {
+    typeName: string;
+    uniquePart: string;
+};
+/** Assert that `value` looks like a record: an object with string `id` and `typeName`. */
+declare function isRecordLike(value: unknown): value is UnknownRecord;
+
+/**
+ * A fractional index: an order key that sorts lexicographically (plain string
+ * comparison) and between which new keys can always be generated.
+ */
+type IndexKey = string & {
+    __brand: "indexKey";
+};
+/** The conventional first key. */
+declare const ZERO_INDEX_KEY: IndexKey;
+/** Generate a key strictly between `below` and `above`; either may be omitted. Throws when `below >= above`. */
+declare function getIndexBetween(below?: IndexKey | undefined, above?: IndexKey | undefined): IndexKey;
+/** Generate a key strictly above `below` (or a first key when omitted). */
+declare function getIndexAbove(below?: IndexKey | undefined): IndexKey;
+/** Generate a key strictly below `above` (or a first key when omitted). */
+declare function getIndexBelow(above?: IndexKey | undefined): IndexKey;
+/** Generate `n` sorted keys strictly between `below` and `above`. */
+declare function getIndicesBetween(below: IndexKey | undefined, above: IndexKey | undefined, n: number): IndexKey[];
+/** Generate `n` sorted keys strictly above `below`. */
+declare function getIndicesAbove(below: IndexKey | undefined, n: number): IndexKey[];
+/** Generate `n` sorted keys strictly below `above`. */
+declare function getIndicesBelow(above: IndexKey | undefined, n: number): IndexKey[];
+/**
+ * Generate `n` sorted keys, the first of which is `start` (default `a0`).
+ * Useful when creating `n` items at once.
+ */
+declare function getIndices(n: number, start?: IndexKey): IndexKey[];
+/** Return a sorted copy of `items` ordered by their `index` (stable). */
+declare function sortByIndex<T extends {
+    index: IndexKey;
+}>(items: readonly T[]): T[];
+/** Compare two keys: negative, zero, or positive. */
+declare function compareIndexKeys(a: IndexKey, b: IndexKey): number;
+/**
+ * Throws if `key` is not a well-formed fractional index key: a head marker,
+ * enough base-62 integer digits for that head, then an optional fraction of
+ * base-62 digits that does not end in `0`.
+ * Narrows the type on success.
+ */
+declare function validateIndexKey(key: string): asserts key is IndexKey;
+/** Non-throwing variant of `validateIndexKey`. */
+declare function isIndexKey(key: unknown): key is IndexKey;
+
+/** Number of base-62 digits (after the head marker) that affect the zkey. */
+declare const ZKEY_SIGNIFICANT_DIGITS = 10;
+type ZKey = readonly [lo: number, hi: number];
+declare function indexKeyToZKey(key: IndexKey): [lo: number, hi: number];
+/** Recombine a zkey into a BigInt (mostly for tests and debugging). */
+declare function zKeyToBigInt([lo, hi]: ZKey): bigint;
+/** Compare two zkeys as unsigned 64-bit integers. */
+declare function compareZKeys(a: ZKey, b: ZKey): number;
+
+/** A set of changes to a store's records. */
+interface RecordsDiff<R extends UnknownRecord> {
+    added: Record<IdOf<R>, R>;
+    updated: Record<IdOf<R>, [from: R, to: R]>;
+    removed: Record<IdOf<R>, R>;
+}
+declare function createEmptyRecordsDiff<R extends UnknownRecord>(): RecordsDiff<R>;
+declare function isRecordsDiffEmpty<R extends UnknownRecord>(diff: RecordsDiff<R>): boolean;
+/** Produce the diff that undoes `diff`. */
+declare function reverseRecordsDiff<R extends UnknownRecord>(diff: RecordsDiff<R>): RecordsDiff<R>;
+/**
+ * Record that `id` went from `before` to `after` in `target`, collapsing with
+ * any change already recorded for the same id:
+ *
+ *   added   + updated -> added (latest)
+ *   added   + removed -> (nothing)
+ *   updated + updated -> updated [original from, latest to]
+ *   updated + removed -> removed (original from)
+ *   removed + added   -> updated [removed, added] (or nothing if identical)
+ */
+declare function applyChangeToDiff<R extends UnknownRecord>(target: RecordsDiff<R>, id: IdOf<R>, before: R | undefined, after: R | undefined): void;
+/** Merge `diff` into `target` in place (see `applyChangeToDiff` for the rules). */
+declare function squashRecordDiffsMutable<R extends UnknownRecord>(target: RecordsDiff<R>, diff: RecordsDiff<R>): void;
+/** Squash a sequence of diffs into one equivalent diff (does not mutate inputs). */
+declare function squashRecordDiffs<R extends UnknownRecord>(diffs: readonly RecordsDiff<R>[]): RecordsDiff<R>;
+/** Shallow-copy a diff (entries are shared). */
+declare function cloneRecordsDiff<R extends UnknownRecord>(diff: RecordsDiff<R>): RecordsDiff<R>;
+
+/** Serialized records keyed by id. */
+type SerializedStore<R extends UnknownRecord> = Record<IdOf<R>, R>;
+/**
+ * Persisted description of a schema: for each migration sequence, how many
+ * migrations had been applied when the data was saved.
+ */
+interface SerializedSchemaV2 {
+    schemaVersion: 2;
+    sequences: {
+        [sequenceId: string]: number;
+    };
+}
+type SerializedSchema = SerializedSchemaV2;
+type MigrationId = `${string}/${number}`;
+interface RecordMigration {
+    readonly id: MigrationId;
+    readonly scope: "record";
+    /** Only records for which this returns true are migrated. Defaults to all records. */
+    readonly filter?: ((record: UnknownRecord) => boolean) | undefined;
+    /** Mutate the record in place, or return a replacement. */
+    readonly up: (record: UnknownRecord) => void | UnknownRecord;
+    readonly down?: ((record: UnknownRecord) => void | UnknownRecord) | undefined;
+}
+interface StoreMigration {
+    readonly id: MigrationId;
+    readonly scope: "store";
+    /** Mutate the store in place, or return a replacement. */
+    readonly up: (store: SerializedStore<UnknownRecord>) => void | SerializedStore<UnknownRecord>;
+    readonly down?: ((store: SerializedStore<UnknownRecord>) => void | SerializedStore<UnknownRecord>) | undefined;
+}
+type Migration = RecordMigration | StoreMigration;
+interface MigrationSequence {
+    readonly sequenceId: string;
+    /**
+     * When data is loaded that has never seen this sequence, should every
+     * migration be applied (`true`, the default) or should the data be assumed
+     * already up to date (`false`)? Use `false` for sequences added to a type
+     * that already existed before the sequence did.
+     */
+    readonly retroactive: boolean;
+    readonly sequence: readonly Migration[];
+}
+type MigrationResult<T> = {
+    type: "success";
+    value: T;
+} | {
+    type: "error";
+    reason: string;
+};
+/**
+ * Build the ids of a sequence's migrations from friendly names:
+ *
+ * ```ts
+ * const Versions = createMigrationIds('com.example.shape.box', { AddColor: 1, AddSize: 2 })
+ * // Versions.AddColor === 'com.example.shape.box/1'
+ * ```
+ */
+declare function createMigrationIds<const ID extends string, const Versions extends Record<string, number>>(sequenceId: ID, versions: Versions): {
+    readonly [K in keyof Versions]: `${ID}/${Versions[K]}`;
+};
+declare function parseMigrationId(id: string): {
+    sequenceId: string;
+    version: number;
+};
+/**
+ * Create a validated migration sequence. Migration ids must be
+ * `${sequenceId}/1`, `${sequenceId}/2`, ... in order.
+ */
+declare function createMigrationSequence(options: {
+    sequenceId: string;
+    retroactive?: boolean | undefined;
+    sequence: readonly Migration[];
+}): MigrationSequence;
+/**
+ * Convenience for the common case: a sequence of record-scoped migrations
+ * that all apply to one record type (optionally narrowed further by `filter`).
+ */
+declare function createRecordMigrationSequence(options: {
+    sequenceId: string;
+    recordType: string;
+    retroactive?: boolean | undefined;
+    filter?: ((record: UnknownRecord) => boolean) | undefined;
+    sequence: readonly Omit<RecordMigration, "scope" | "filter">[];
+}): MigrationSequence;
+/** Apply one record migration to a single record, honoring its filter. */
+declare function applyRecordMigration(migration: RecordMigration, record: UnknownRecord, direction: "up" | "down"): UnknownRecord;
+/** 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>;
+
+type ChangeSource = "user" | "remote";
+interface HistoryEntry<R extends UnknownRecord> {
+    changes: RecordsDiff<R>;
+    source: ChangeSource;
+}
+type StoreListener<R extends UnknownRecord> = (entry: HistoryEntry<R>) => void;
+interface StoreListenerFilters {
+    source: ChangeSource | "all";
+    scope: RecordScope | "all";
+}
+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;
+interface StoreOptions<R extends UnknownRecord, Props> {
+    schema: StoreSchema<R, Props>;
+    initialData?: SerializedStore<R> | undefined;
+    props: Props;
+    id?: string | undefined;
+}
+type StoreBeforeCreateHandler<R extends UnknownRecord> = (record: R, source: ChangeSource) => R;
+type StoreAfterCreateHandler<R extends UnknownRecord> = (record: R, source: ChangeSource) => void;
+type StoreBeforeChangeHandler<R extends UnknownRecord> = (prev: R, next: R, source: ChangeSource) => R;
+type StoreAfterChangeHandler<R extends UnknownRecord> = (prev: R, next: R, source: ChangeSource) => void;
+/** Return `false` to veto the deletion. */
+type StoreBeforeDeleteHandler<R extends UnknownRecord> = (record: R, source: ChangeSource) => void | false;
+type StoreAfterDeleteHandler<R extends UnknownRecord> = (record: R, source: ChangeSource) => void;
+type StoreOperationCompleteHandler = (source: ChangeSource) => void;
+interface StoreSideEffectHandlers<R extends UnknownRecord> {
+    beforeCreate?: StoreBeforeCreateHandler<R> | undefined;
+    afterCreate?: StoreAfterCreateHandler<R> | undefined;
+    beforeChange?: StoreBeforeChangeHandler<R> | undefined;
+    afterChange?: StoreAfterChangeHandler<R> | undefined;
+    beforeDelete?: StoreBeforeDeleteHandler<R> | undefined;
+    afterDelete?: StoreAfterDeleteHandler<R> | undefined;
+}
+/**
+ * Hooks that run around record writes. `before*` handlers may replace the
+ * record being written (or veto a delete); `after*` handlers observe.
+ * `operationComplete` handlers run once when the outermost operation ends,
+ * before history listeners are notified.
+ */
+declare class StoreSideEffects<R extends UnknownRecord> {
+    private readonly byType;
+    private readonly operationComplete;
+    private enabled;
+    isEnabled(): boolean;
+    setIsEnabled(enabled: boolean): void;
+    private sets;
+    private add;
+    /** Register several handlers for several types at once. Returns a disposer for all of them. */
+    register(handlers: {
+        [T in R["typeName"]]?: StoreSideEffectHandlers<RecordFromTypeName<R, T>>;
+    }): () => void;
+    registerBeforeCreateHandler<T extends R["typeName"]>(typeName: T, handler: StoreBeforeCreateHandler<RecordFromTypeName<R, T>>): () => void;
+    registerAfterCreateHandler<T extends R["typeName"]>(typeName: T, handler: StoreAfterCreateHandler<RecordFromTypeName<R, T>>): () => void;
+    registerBeforeChangeHandler<T extends R["typeName"]>(typeName: T, handler: StoreBeforeChangeHandler<RecordFromTypeName<R, T>>): () => void;
+    registerAfterChangeHandler<T extends R["typeName"]>(typeName: T, handler: StoreAfterChangeHandler<RecordFromTypeName<R, T>>): () => void;
+    registerBeforeDeleteHandler<T extends R["typeName"]>(typeName: T, handler: StoreBeforeDeleteHandler<RecordFromTypeName<R, T>>): () => void;
+    registerAfterDeleteHandler<T extends R["typeName"]>(typeName: T, handler: StoreAfterDeleteHandler<RecordFromTypeName<R, T>>): () => void;
+    registerOperationCompleteHandler(handler: StoreOperationCompleteHandler): () => void;
+    /** @internal */
+    handleBeforeCreate(record: R, source: ChangeSource): R;
+    /** @internal */
+    handleAfterCreate(record: R, source: ChangeSource): void;
+    /** @internal */
+    handleBeforeChange(prev: R, next: R, source: ChangeSource): R;
+    /** @internal */
+    handleAfterChange(prev: R, next: R, source: ChangeSource): void;
+    /** @internal Returns false when a handler vetoed the delete. */
+    handleBeforeDelete(record: R, source: ChangeSource): boolean;
+    /** @internal */
+    handleAfterDelete(record: R, source: ChangeSource): void;
+    /** @internal */
+    handleOperationComplete(source: ChangeSource): void;
+}
+/**
+ * Records are considered unchanged when every top-level value is identical,
+ * with `props` and `meta` compared one level deeper. Cheap enough to run on
+ * every `put`, and avoids no-op history entries.
+ */
+declare function isRecordShallowEqual(a: UnknownRecord, b: UnknownRecord): boolean;
+/** Freeze a record and its `props` / `meta` bags (one level). */
+declare function freezeRecord<R extends UnknownRecord>(record: R): R;
+interface TypeIndex<R extends UnknownRecord> {
+    /** Mutated in place on every add/remove: O(1) per record. */
+    readonly live: Set<IdOf<R>>;
+    /** Bumped whenever `live` changes; the reactive handle on membership. */
+    readonly epoch: Atom<number>;
+}
+/** Reactive views over the store's records, cached per type name. */
+declare class StoreQueries<R extends UnknownRecord> {
+    private readonly store;
+    private readonly idsCache;
+    private readonly recordsCache;
+    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>;
+    /** Non-reactive filter over the records of `typeName`. */
+    exec<T extends R["typeName"]>(typeName: T, predicate: (record: RecordFromTypeName<R, T>) => boolean): RecordFromTypeName<R, T>[];
+}
+/**
+ * A reactive, transactional collection of records.
+ *
+ * - one atom per record, so consumers subscribe to exactly what they read
+ * - per-type id sets maintained incrementally
+ * - writes are batched; listeners receive one squashed diff per outermost operation
+ * - records are frozen on write
+ */
+declare class Store<R extends UnknownRecord = UnknownRecord, Props = unknown> {
+    readonly id: string;
+    readonly schema: StoreSchema<R, Props>;
+    readonly props: Props;
+    readonly scopedTypes: {
+        readonly [S in RecordScope]: ReadonlySet<string>;
+    };
+    readonly sideEffects: StoreSideEffects<R>;
+    readonly query: StoreQueries<R>;
+    /** Bumped once per completed operation that changed something. */
+    readonly history: Atom<number>;
+    private readonly records;
+    private readonly typeIndexes;
+    private readonly listeners;
+    private pendingEntries;
+    private readonly extractStack;
+    private depth;
+    private source;
+    private runCallbacks;
+    private inOperationComplete;
+    private disposed;
+    constructor(options: StoreOptions<R, Props>);
+    /** @internal */
+    getTypeIndex(typeName: string): TypeIndex<R>;
+    /** Get a record (reactive: subscribes to the record, or to its type's membership when absent). */
+    get<K extends IdOf<R>>(id: K): RecordFromId<K> | undefined;
+    /** Get a record without registering a reactive dependency. */
+    unsafeGetWithoutCapture<K extends IdOf<R>>(id: K): RecordFromId<K> | undefined;
+    has<K extends IdOf<R>>(id: K): boolean;
+    /** All records (reactive over every record and every type's membership). */
+    allRecords(): R[];
+    /** Scope of a record type; unknown types are `document`. */
+    getScope(typeName: string): RecordScope;
+    /**
+     * 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: readonly R[], phaseOverride?: StoreValidationPhase): void;
+    /** Remove records by id. Missing ids are ignored. `beforeDelete` handlers may veto. */
+    remove(ids: readonly IdOf<R>[]): void;
+    /** Remove every record. */
+    clear(): void;
+    /**
+     * Update one record with a function. No-op when the record does not exist.
+     */
+    update<K extends IdOf<R>>(id: K, updater: (record: RecordFromId<K>) => RecordFromId<K>): void;
+    /**
+     * Run `fn` as one operation: side effects' `operationComplete` handlers run
+     * once at the end, and listeners get a single squashed history entry.
+     */
+    atomic<T>(fn: () => T, options?: {
+        source?: ChangeSource | undefined;
+        runCallbacks?: boolean | undefined;
+    }): T;
+    /** Changes made inside `fn` are reported to listeners with source `remote`. */
+    mergeRemoteChanges(fn: () => void): void;
+    /** Run `fn` and return the squashed diff of everything it changed. Listeners are still notified. */
+    extractingChanges(fn: () => void): RecordsDiff<R>;
+    /**
+     * 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: RecordsDiff<R>, options?: {
+        runCallbacks?: boolean | undefined;
+        ignoreEphemeralKeys?: boolean | undefined;
+    }): void;
+    /**
+     * Subscribe to history entries. Called after each outermost operation with
+     * the squashed changes, filtered by source and record scope.
+     */
+    listen(onHistory: StoreListener<R>, filters?: Partial<StoreListenerFilters>): () => void;
+    /** Plain-object snapshot of the records in `scope` (default `document`). */
+    serialize(scope?: RecordScope | "all"): SerializedStore<R>;
+    getStoreSnapshot(scope?: RecordScope | "all"): 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
+     * snapshot are removed unless the snapshot contains them; other scopes are
+     * left alone. Side effects do not run; listeners are notified.
+     */
+    loadStoreSnapshot(snapshot: StoreSnapshot<R>): void;
+    /**
+     * A per-record derived value, recomputed only when that record changes.
+     * Entries are dropped automatically when records are removed.
+     */
+    createComputedCache<T, K extends IdOf<R> = IdOf<R>>(name: string, derive: (record: RecordFromId<K>) => T, options?: {
+        isEqual?: ((a: T, b: T) => boolean) | undefined;
+    }): {
+        get(id: K): T | undefined;
+    };
+    isDisposed(): boolean;
+    dispose(): void;
+    private addToIndex;
+    private removeFromIndex;
+    private recordChange;
+    private completeOperation;
+    private flushHistory;
+    private filterDiffByScope;
+}
+
+type StoreValidationPhase = "initialize" | "createRecord" | "updateRecord" | "tests";
+type RecordTypeMap<R extends UnknownRecord> = {
+    readonly [TypeName in R["typeName"]]: RecordType<Extract<R, {
+        typeName: TypeName;
+    }>, any>;
+};
+interface StoreValidationFailure<R extends UnknownRecord> {
+    error: unknown;
+    store: Store<R, any>;
+    record: R;
+    phase: StoreValidationPhase;
+    recordBefore: R | null;
+}
+interface StoreSchemaOptions<R extends UnknownRecord, Props> {
+    readonly migrations?: readonly MigrationSequence[] | undefined;
+    /**
+     * Called when a record fails validation. Return a repaired record to keep
+     * going, or throw to abort the operation. When omitted the error is thrown.
+     */
+    readonly onValidationFailure?: ((data: StoreValidationFailure<R>) => R) | undefined;
+    /** Reserved for store-level integrity checks; unused by the schema itself. */
+    readonly createIntegrityChecker?: ((store: Store<R, Props>) => void) | undefined;
+}
+interface StoreSnapshot<R extends UnknownRecord> {
+    store: SerializedStore<R>;
+    schema: SerializedSchema;
+}
+/**
+ * The set of record types a store holds plus the migrations that bring
+ * persisted data up to date.
+ */
+declare class StoreSchema<R extends UnknownRecord, Props = unknown> {
+    readonly types: RecordTypeMap<R>;
+    private readonly options;
+    static create<R extends UnknownRecord, Props = unknown>(types: RecordTypeMap<R>, options?: StoreSchemaOptions<R, Props>): StoreSchema<R, Props>;
+    readonly migrations: Readonly<Record<string, MigrationSequence>>;
+    /** All migrations in application order (sequence registration order, then version). */
+    readonly sortedMigrations: readonly Migration[];
+    private readonly typeByName;
+    private constructor();
+    getType(typeName: string): RecordType<R, any> | undefined;
+    /** Scope of a record type; unknown types are treated as `document`. */
+    getScope(typeName: string): RecordScope;
+    /**
+     * 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: Store<R, any>, record: R, phase: StoreValidationPhase, recordBefore: R | undefined): R;
+    /** The current version of every sequence. */
+    serialize(): SerializedSchema;
+    /** A schema at version 0 of every sequence (all migrations still pending). */
+    serializeEarliestVersion(): SerializedSchema;
+    /**
+     * 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[]>;
+    /**
+     * 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: UnknownRecord, persistedSchema: SerializedSchema, direction?: "up" | "down"): MigrationResult<UnknownRecord>;
+    /**
+     * 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: StoreSnapshot<R>): MigrationResult<SerializedStore<R>>;
+}
+
+/**
+ * `.tldr` file envelope. Schema-agnostic: this module does not know or care
+ * what record types the file holds.
+ */
+declare const TLDR_FILE_FORMAT_VERSION = 1;
+interface TldrFile {
+    tldrawFileFormatVersion: number;
+    schema: SerializedSchema;
+    records: UnknownRecord[];
+}
+type TldrFileParseError = "notATldrFile" | "v1File" | "invalidRecords" | "futureVersion";
+type ParseTldrFileResult = {
+    ok: true;
+    schema: SerializedSchema;
+    records: UnknownRecord[];
+} | {
+    ok: false;
+    error: TldrFileParseError;
+    cause?: unknown;
+};
+/**
+ * Parse a `.tldr` file. Accepts either the JSON text or the already-parsed
+ * value. Never throws.
+ */
+declare function parseTldrFile(json: unknown): ParseTldrFileResult;
+/**
+ * Serialize records and their schema into the `.tldr` envelope
+ * (pretty-printed, stable key order). Records are written in the given order.
+ */
+declare function serializeTldrFile(schema: SerializedSchema, records: readonly UnknownRecord[]): string;
+/** Convert a parsed file into a `{ store, schema }` snapshot. */
+declare function tldrFileToStoreSnapshot(file: {
+    schema: SerializedSchema;
+    records: readonly UnknownRecord[];
+}): {
+    store: SerializedStore<UnknownRecord>;
+    schema: SerializedSchema;
+};
+/** Convert a `{ store, schema }` snapshot into `.tldr` text. Records are ordered by id. */
+declare function storeSnapshotToTldrFile(snapshot: {
+    store: SerializedStore<UnknownRecord>;
+    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 };