@tldraw/store 4.1.0-canary.ccd6179e1cb2 → 4.1.0-canary.e23ee15a46bc

package/dist-esm/lib/RecordsDiff.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/RecordsDiff.ts"],
-  "sourcesContent": ["import { objectMapEntries } from '@tldraw/utils'\nimport { IdOf, UnknownRecord } from './BaseRecord'\n\n/**\n * A diff describing the changes to a record.\n *\n * @public\n */\nexport interface RecordsDiff<R extends UnknownRecord> {\n\tadded: Record<IdOf<R>, R>\n\tupdated: Record<IdOf<R>, [from: R, to: R]>\n\tremoved: Record<IdOf<R>, R>\n}\n\n/** @internal */\nexport function createEmptyRecordsDiff<R extends UnknownRecord>(): RecordsDiff<R> {\n\treturn { added: {}, updated: {}, removed: {} } as RecordsDiff<R>\n}\n\n/** @public */\nexport function reverseRecordsDiff(diff: RecordsDiff<any>) {\n\tconst result: RecordsDiff<any> = { added: diff.removed, removed: diff.added, updated: {} }\n\tfor (const [from, to] of Object.values(diff.updated)) {\n\t\tresult.updated[from.id] = [to, from]\n\t}\n\treturn result\n}\n\n/**\n * Is a records diff empty?\n * @internal\n */\nexport function isRecordsDiffEmpty<T extends UnknownRecord>(diff: RecordsDiff<T>) {\n\treturn (\n\t\tObject.keys(diff.added).length === 0 &&\n\t\tObject.keys(diff.updated).length === 0 &&\n\t\tObject.keys(diff.removed).length === 0\n\t)\n}\n\n/**\n * Squash a collection of diffs into a single diff.\n *\n * @param diffs - An array of diffs to squash.\n * @param options - An optional object with a `mutateFirstDiff` property. If `mutateFirstDiff` is true, the first diff in the array will be mutated in-place.\n * @returns A single diff that represents the squashed diffs.\n * @public\n */\nexport function squashRecordDiffs<T extends UnknownRecord>(\n\tdiffs: RecordsDiff<T>[],\n\toptions?: {\n\t\tmutateFirstDiff?: boolean\n\t}\n): RecordsDiff<T> {\n\tconst result = options?.mutateFirstDiff\n\t\t? diffs[0]\n\t\t: ({ added: {}, removed: {}, updated: {} } as RecordsDiff<T>)\n\n\tsquashRecordDiffsMutable(result, options?.mutateFirstDiff ? diffs.slice(1) : diffs)\n\treturn result\n}\n\n/**\n * Apply the array `diffs` to the `target` diff, mutating it in-place.\n * @internal\n */\nexport function squashRecordDiffsMutable<T extends UnknownRecord>(\n\ttarget: RecordsDiff<T>,\n\tdiffs: RecordsDiff<T>[]\n): void {\n\tfor (const diff of diffs) {\n\t\tfor (const [id, value] of objectMapEntries(diff.added)) {\n\t\t\tif (target.removed[id]) {\n\t\t\t\tconst original = target.removed[id]\n\t\t\t\tdelete target.removed[id]\n\t\t\t\tif (original !== value) {\n\t\t\t\t\ttarget.updated[id] = [original, value]\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\ttarget.added[id] = value\n\t\t\t}\n\t\t}\n\n\t\tfor (const [id, [_from, to]] of objectMapEntries(diff.updated)) {\n\t\t\tif (target.added[id]) {\n\t\t\t\ttarget.added[id] = to\n\t\t\t\tdelete target.updated[id]\n\t\t\t\tdelete target.removed[id]\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tif (target.updated[id]) {\n\t\t\t\ttarget.updated[id] = [target.updated[id][0], to]\n\t\t\t\tdelete target.removed[id]\n\t\t\t\tcontinue\n\t\t\t}\n\n\t\t\ttarget.updated[id] = diff.updated[id]\n\t\t\tdelete target.removed[id]\n\t\t}\n\n\t\tfor (const [id, value] of objectMapEntries(diff.removed)) {\n\t\t\t// the same record was added in this diff sequence, just drop it\n\t\t\tif (target.added[id]) {\n\t\t\t\tdelete target.added[id]\n\t\t\t} else if (target.updated[id]) {\n\t\t\t\ttarget.removed[id] = target.updated[id][0]\n\t\t\t\tdelete target.updated[id]\n\t\t\t} else {\n\t\t\t\ttarget.removed[id] = value\n\t\t\t}\n\t\t}\n\t}\n}\n"],
-  "mappings": "AAAA,SAAS,wBAAwB;AAe1B,SAAS,yBAAkE;AACjF,SAAO,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC,EAAE;AAC9C;AAGO,SAAS,mBAAmB,MAAwB;AAC1D,QAAM,SAA2B,EAAE,OAAO,KAAK,SAAS,SAAS,KAAK,OAAO,SAAS,CAAC,EAAE;AACzF,aAAW,CAAC,MAAM,EAAE,KAAK,OAAO,OAAO,KAAK,OAAO,GAAG;AACrD,WAAO,QAAQ,KAAK,EAAE,IAAI,CAAC,IAAI,IAAI;AAAA,EACpC;AACA,SAAO;AACR;AAMO,SAAS,mBAA4C,MAAsB;AACjF,SACC,OAAO,KAAK,KAAK,KAAK,EAAE,WAAW,KACnC,OAAO,KAAK,KAAK,OAAO,EAAE,WAAW,KACrC,OAAO,KAAK,KAAK,OAAO,EAAE,WAAW;AAEvC;AAUO,SAAS,kBACf,OACA,SAGiB;AACjB,QAAM,SAAS,SAAS,kBACrB,MAAM,CAAC,IACN,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC,EAAE;AAE1C,2BAAyB,QAAQ,SAAS,kBAAkB,MAAM,MAAM,CAAC,IAAI,KAAK;AAClF,SAAO;AACR;AAMO,SAAS,yBACf,QACA,OACO;AACP,aAAW,QAAQ,OAAO;AACzB,eAAW,CAAC,IAAI,KAAK,KAAK,iBAAiB,KAAK,KAAK,GAAG;AACvD,UAAI,OAAO,QAAQ,EAAE,GAAG;AACvB,cAAM,WAAW,OAAO,QAAQ,EAAE;AAClC,eAAO,OAAO,QAAQ,EAAE;AACxB,YAAI,aAAa,OAAO;AACvB,iBAAO,QAAQ,EAAE,IAAI,CAAC,UAAU,KAAK;AAAA,QACtC;AAAA,MACD,OAAO;AACN,eAAO,MAAM,EAAE,IAAI;AAAA,MACpB;AAAA,IACD;AAEA,eAAW,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,iBAAiB,KAAK,OAAO,GAAG;AAC/D,UAAI,OAAO,MAAM,EAAE,GAAG;AACrB,eAAO,MAAM,EAAE,IAAI;AACnB,eAAO,OAAO,QAAQ,EAAE;AACxB,eAAO,OAAO,QAAQ,EAAE;AACxB;AAAA,MACD;AACA,UAAI,OAAO,QAAQ,EAAE,GAAG;AACvB,eAAO,QAAQ,EAAE,IAAI,CAAC,OAAO,QAAQ,EAAE,EAAE,CAAC,GAAG,EAAE;AAC/C,eAAO,OAAO,QAAQ,EAAE;AACxB;AAAA,MACD;AAEA,aAAO,QAAQ,EAAE,IAAI,KAAK,QAAQ,EAAE;AACpC,aAAO,OAAO,QAAQ,EAAE;AAAA,IACzB;AAEA,eAAW,CAAC,IAAI,KAAK,KAAK,iBAAiB,KAAK,OAAO,GAAG;AAEzD,UAAI,OAAO,MAAM,EAAE,GAAG;AACrB,eAAO,OAAO,MAAM,EAAE;AAAA,MACvB,WAAW,OAAO,QAAQ,EAAE,GAAG;AAC9B,eAAO,QAAQ,EAAE,IAAI,OAAO,QAAQ,EAAE,EAAE,CAAC;AACzC,eAAO,OAAO,QAAQ,EAAE;AAAA,MACzB,OAAO;AACN,eAAO,QAAQ,EAAE,IAAI;AAAA,MACtB;AAAA,IACD;AAAA,EACD;AACD;",
+  "sourcesContent": ["import { objectMapEntries } from '@tldraw/utils'\nimport { IdOf, UnknownRecord } from './BaseRecord'\n\n/**\n * A diff describing the changes to records, containing collections of records that were added,\n * updated, or removed. This is the fundamental data structure used throughout the store system\n * to track and communicate changes.\n *\n * @example\n * ```ts\n * const diff: RecordsDiff<Book> = {\n *   added: {\n *     'book:1': { id: 'book:1', typeName: 'book', title: 'New Book' }\n *   },\n *   updated: {\n *     'book:2': [\n *       { id: 'book:2', typeName: 'book', title: 'Old Title' }, // from\n *       { id: 'book:2', typeName: 'book', title: 'New Title' }  // to\n *     ]\n *   },\n *   removed: {\n *     'book:3': { id: 'book:3', typeName: 'book', title: 'Deleted Book' }\n *   }\n * }\n * ```\n *\n * @public\n */\nexport interface RecordsDiff<R extends UnknownRecord> {\n\t/** Records that were created, keyed by their ID */\n\tadded: Record<IdOf<R>, R>\n\t/** Records that were modified, keyed by their ID. Each entry contains [from, to] tuple */\n\tupdated: Record<IdOf<R>, [from: R, to: R]>\n\t/** Records that were deleted, keyed by their ID */\n\tremoved: Record<IdOf<R>, R>\n}\n\n/**\n * Creates an empty RecordsDiff with no added, updated, or removed records.\n * This is useful as a starting point when building diffs programmatically.\n *\n * @returns An empty RecordsDiff with all collections initialized to empty objects\n * @example\n * ```ts\n * const emptyDiff = createEmptyRecordsDiff<Book>()\n * // Result: { added: {}, updated: {}, removed: {} }\n * ```\n *\n * @internal\n */\nexport function createEmptyRecordsDiff<R extends UnknownRecord>(): RecordsDiff<R> {\n\treturn { added: {}, updated: {}, removed: {} } as RecordsDiff<R>\n}\n\n/**\n * Creates the inverse of a RecordsDiff, effectively reversing all changes.\n * Added records become removed, removed records become added, and updated records\n * have their from/to values swapped. This is useful for implementing undo operations.\n *\n * @param diff - The diff to reverse\n * @returns A new RecordsDiff that represents the inverse of the input diff\n * @example\n * ```ts\n * const originalDiff: RecordsDiff<Book> = {\n *   added: { 'book:1': newBook },\n *   updated: { 'book:2': [oldBook, updatedBook] },\n *   removed: { 'book:3': deletedBook }\n * }\n *\n * const reversedDiff = reverseRecordsDiff(originalDiff)\n * // Result: {\n * //   added: { 'book:3': deletedBook },\n * //   updated: { 'book:2': [updatedBook, oldBook] },\n * //   removed: { 'book:1': newBook }\n * // }\n * ```\n *\n * @public\n */\nexport function reverseRecordsDiff(diff: RecordsDiff<any>) {\n\tconst result: RecordsDiff<any> = { added: diff.removed, removed: diff.added, updated: {} }\n\tfor (const [from, to] of Object.values(diff.updated)) {\n\t\tresult.updated[from.id] = [to, from]\n\t}\n\treturn result\n}\n\n/**\n * Checks whether a RecordsDiff contains any changes. A diff is considered empty\n * if it has no added, updated, or removed records.\n *\n * @param diff - The diff to check\n * @returns True if the diff contains no changes, false otherwise\n * @example\n * ```ts\n * const emptyDiff = createEmptyRecordsDiff<Book>()\n * console.log(isRecordsDiffEmpty(emptyDiff)) // true\n *\n * const nonEmptyDiff: RecordsDiff<Book> = {\n *   added: { 'book:1': someBook },\n *   updated: {},\n *   removed: {}\n * }\n * console.log(isRecordsDiffEmpty(nonEmptyDiff)) // false\n * ```\n *\n * @public\n */\nexport function isRecordsDiffEmpty<T extends UnknownRecord>(diff: RecordsDiff<T>) {\n\treturn (\n\t\tObject.keys(diff.added).length === 0 &&\n\t\tObject.keys(diff.updated).length === 0 &&\n\t\tObject.keys(diff.removed).length === 0\n\t)\n}\n\n/**\n * Combines multiple RecordsDiff objects into a single consolidated diff.\n * This function intelligently merges changes, handling cases where the same record\n * is modified multiple times across different diffs. For example, if a record is\n * added in one diff and then updated in another, the result will show it as added\n * with the final state.\n *\n * @param diffs - An array of diffs to combine into a single diff\n * @param options - Configuration options for the squashing operation\n *   - mutateFirstDiff - If true, modifies the first diff in place instead of creating a new one\n * @returns A single diff that represents the cumulative effect of all input diffs\n * @example\n * ```ts\n * const diff1: RecordsDiff<Book> = {\n *   added: { 'book:1': { id: 'book:1', title: 'New Book' } },\n *   updated: {},\n *   removed: {}\n * }\n *\n * const diff2: RecordsDiff<Book> = {\n *   added: {},\n *   updated: { 'book:1': [{ id: 'book:1', title: 'New Book' }, { id: 'book:1', title: 'Updated Title' }] },\n *   removed: {}\n * }\n *\n * const squashed = squashRecordDiffs([diff1, diff2])\n * // Result: {\n * //   added: { 'book:1': { id: 'book:1', title: 'Updated Title' } },\n * //   updated: {},\n * //   removed: {}\n * // }\n * ```\n *\n * @public\n */\nexport function squashRecordDiffs<T extends UnknownRecord>(\n\tdiffs: RecordsDiff<T>[],\n\toptions?: {\n\t\tmutateFirstDiff?: boolean\n\t}\n): RecordsDiff<T> {\n\tconst result = options?.mutateFirstDiff\n\t\t? diffs[0]\n\t\t: ({ added: {}, removed: {}, updated: {} } as RecordsDiff<T>)\n\n\tsquashRecordDiffsMutable(result, options?.mutateFirstDiff ? diffs.slice(1) : diffs)\n\treturn result\n}\n\n/**\n * Applies an array of diffs to a target diff by mutating the target in-place.\n * This is the core implementation used by squashRecordDiffs. It handles complex\n * scenarios where records move between added/updated/removed states across multiple diffs.\n *\n * The function processes each diff sequentially, applying the following logic:\n * - Added records: If the record was previously removed, convert to an update; otherwise add it\n * - Updated records: Chain updates together, preserving the original 'from' state\n * - Removed records: If the record was added in this sequence, cancel both operations\n *\n * @param target - The diff to modify in-place (will be mutated)\n * @param diffs - Array of diffs to apply to the target\n * @example\n * ```ts\n * const targetDiff: RecordsDiff<Book> = {\n *   added: {},\n *   updated: {},\n *   removed: { 'book:1': oldBook }\n * }\n *\n * const newDiffs = [{\n *   added: { 'book:1': newBook },\n *   updated: {},\n *   removed: {}\n * }]\n *\n * squashRecordDiffsMutable(targetDiff, newDiffs)\n * // targetDiff is now: {\n * //   added: {},\n * //   updated: { 'book:1': [oldBook, newBook] },\n * //   removed: {}\n * // }\n * ```\n *\n * @internal\n */\nexport function squashRecordDiffsMutable<T extends UnknownRecord>(\n\ttarget: RecordsDiff<T>,\n\tdiffs: RecordsDiff<T>[]\n): void {\n\tfor (const diff of diffs) {\n\t\tfor (const [id, value] of objectMapEntries(diff.added)) {\n\t\t\tif (target.removed[id]) {\n\t\t\t\tconst original = target.removed[id]\n\t\t\t\tdelete target.removed[id]\n\t\t\t\tif (original !== value) {\n\t\t\t\t\ttarget.updated[id] = [original, value]\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\ttarget.added[id] = value\n\t\t\t}\n\t\t}\n\n\t\tfor (const [id, [_from, to]] of objectMapEntries(diff.updated)) {\n\t\t\tif (target.added[id]) {\n\t\t\t\ttarget.added[id] = to\n\t\t\t\tdelete target.updated[id]\n\t\t\t\tdelete target.removed[id]\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tif (target.updated[id]) {\n\t\t\t\ttarget.updated[id] = [target.updated[id][0], to]\n\t\t\t\tdelete target.removed[id]\n\t\t\t\tcontinue\n\t\t\t}\n\n\t\t\ttarget.updated[id] = diff.updated[id]\n\t\t\tdelete target.removed[id]\n\t\t}\n\n\t\tfor (const [id, value] of objectMapEntries(diff.removed)) {\n\t\t\t// the same record was added in this diff sequence, just drop it\n\t\t\tif (target.added[id]) {\n\t\t\t\tdelete target.added[id]\n\t\t\t} else if (target.updated[id]) {\n\t\t\t\ttarget.removed[id] = target.updated[id][0]\n\t\t\t\tdelete target.updated[id]\n\t\t\t} else {\n\t\t\t\ttarget.removed[id] = value\n\t\t\t}\n\t\t}\n\t}\n}\n"],
+  "mappings": "AAAA,SAAS,wBAAwB;AAkD1B,SAAS,yBAAkE;AACjF,SAAO,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC,EAAE;AAC9C;AA2BO,SAAS,mBAAmB,MAAwB;AAC1D,QAAM,SAA2B,EAAE,OAAO,KAAK,SAAS,SAAS,KAAK,OAAO,SAAS,CAAC,EAAE;AACzF,aAAW,CAAC,MAAM,EAAE,KAAK,OAAO,OAAO,KAAK,OAAO,GAAG;AACrD,WAAO,QAAQ,KAAK,EAAE,IAAI,CAAC,IAAI,IAAI;AAAA,EACpC;AACA,SAAO;AACR;AAuBO,SAAS,mBAA4C,MAAsB;AACjF,SACC,OAAO,KAAK,KAAK,KAAK,EAAE,WAAW,KACnC,OAAO,KAAK,KAAK,OAAO,EAAE,WAAW,KACrC,OAAO,KAAK,KAAK,OAAO,EAAE,WAAW;AAEvC;AAqCO,SAAS,kBACf,OACA,SAGiB;AACjB,QAAM,SAAS,SAAS,kBACrB,MAAM,CAAC,IACN,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC,EAAE;AAE1C,2BAAyB,QAAQ,SAAS,kBAAkB,MAAM,MAAM,CAAC,IAAI,KAAK;AAClF,SAAO;AACR;AAsCO,SAAS,yBACf,QACA,OACO;AACP,aAAW,QAAQ,OAAO;AACzB,eAAW,CAAC,IAAI,KAAK,KAAK,iBAAiB,KAAK,KAAK,GAAG;AACvD,UAAI,OAAO,QAAQ,EAAE,GAAG;AACvB,cAAM,WAAW,OAAO,QAAQ,EAAE;AAClC,eAAO,OAAO,QAAQ,EAAE;AACxB,YAAI,aAAa,OAAO;AACvB,iBAAO,QAAQ,EAAE,IAAI,CAAC,UAAU,KAAK;AAAA,QACtC;AAAA,MACD,OAAO;AACN,eAAO,MAAM,EAAE,IAAI;AAAA,MACpB;AAAA,IACD;AAEA,eAAW,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,iBAAiB,KAAK,OAAO,GAAG;AAC/D,UAAI,OAAO,MAAM,EAAE,GAAG;AACrB,eAAO,MAAM,EAAE,IAAI;AACnB,eAAO,OAAO,QAAQ,EAAE;AACxB,eAAO,OAAO,QAAQ,EAAE;AACxB;AAAA,MACD;AACA,UAAI,OAAO,QAAQ,EAAE,GAAG;AACvB,eAAO,QAAQ,EAAE,IAAI,CAAC,OAAO,QAAQ,EAAE,EAAE,CAAC,GAAG,EAAE;AAC/C,eAAO,OAAO,QAAQ,EAAE;AACxB;AAAA,MACD;AAEA,aAAO,QAAQ,EAAE,IAAI,KAAK,QAAQ,EAAE;AACpC,aAAO,OAAO,QAAQ,EAAE;AAAA,IACzB;AAEA,eAAW,CAAC,IAAI,KAAK,KAAK,iBAAiB,KAAK,OAAO,GAAG;AAEzD,UAAI,OAAO,MAAM,EAAE,GAAG;AACrB,eAAO,OAAO,MAAM,EAAE;AAAA,MACvB,WAAW,OAAO,QAAQ,EAAE,GAAG;AAC9B,eAAO,QAAQ,EAAE,IAAI,OAAO,QAAQ,EAAE,EAAE,CAAC;AACzC,eAAO,OAAO,QAAQ,EAAE;AAAA,MACzB,OAAO;AACN,eAAO,QAAQ,EAAE,IAAI;AAAA,MACtB;AAAA,IACD;AAAA,EACD;AACD;",
   "names": []
 }

package/dist-esm/lib/Store.mjs

@@ -18,7 +18,9 @@ import { StoreSideEffects } from "./StoreSideEffects.mjs";
 import { devFreeze } from "./devFreeze.mjs";
 class Store {
   /**
-   * The random id of the store.
+   * The unique identifier of the store instance.
+   *
+   * @public
    */
   id;
   /**
@@ -38,7 +40,19 @@ class Store {
     historyLength: 1e3
   });
   /**
-   * A StoreQueries instance for this store.
+   * Reactive queries and indexes for efficiently accessing store data.
+   * Provides methods for filtering, indexing, and subscribing to subsets of records.
+   *
+   * @example
+   * ```ts
+   * // Create an index by a property
+   * const booksByAuthor = store.query.index('book', 'author')
+   *
+   * // Get records matching criteria
+   * const inStockBooks = store.query.records('book', () => ({
+   *   inStock: { eq: true }
+   * }))
+   * ```
    *
    * @public
    * @readonly
@@ -70,10 +84,53 @@ class Store {
    */
   cancelHistoryReactor() {
   }
+  /**
+   * The schema that defines the structure and validation rules for records in this store.
+   *
+   * @public
+   */
   schema;
+  /**
+   * Custom properties associated with this store instance.
+   *
+   * @public
+   */
   props;
+  /**
+   * A mapping of record scopes to the set of record type names that belong to each scope.
+   * Used to filter records by their persistence and synchronization behavior.
+   *
+   * @public
+   */
   scopedTypes;
+  /**
+   * Side effects manager that handles lifecycle events for record operations.
+   * Allows registration of callbacks for create, update, delete, and validation events.
+   *
+   * @example
+   * ```ts
+   * store.sideEffects.registerAfterCreateHandler('book', (book) => {
+   *   console.log('Book created:', book.title)
+   * })
+   * ```
+   *
+   * @public
+   */
   sideEffects = new StoreSideEffects(this);
+  /**
+   * Creates a new Store instance.
+   *
+   * @example
+   * ```ts
+   * const store = new Store({
+   *   schema: StoreSchema.create({ book: Book }),
+   *   props: { appName: 'MyLibrary' },
+   *   initialData: savedData
+   * })
+   * ```
+   *
+   * @param config - Configuration object for the store
+   */
   constructor(config) {
     const { initialData, schema, id } = config;
     this.id = id ?? uniqueId();
@@ -182,10 +239,21 @@ class Store {
     this.allRecords().forEach((record) => this.schema.validateRecord(this, record, phase, null));
   }
   /**
-   * Add some records to the store. It's an error if they already exist.
+   * Add or update records in the store. If a record with the same ID already exists, it will be updated.
+   * Otherwise, a new record will be created.
+   *
+   * @example
+   * ```ts
+   * // Add new records
+   * const book = Book.create({ title: 'Lathe Of Heaven', author: 'Le Guin' })
+   * store.put([book])
    *
-   * @param records - The records to add.
-   * @param phaseOverride - The phase override.
+   * // Update existing record
+   * store.put([{ ...book, title: 'The Lathe of Heaven' }])
+   * ```
+   *
+   * @param records - The records to add or update
+   * @param phaseOverride - Override the validation phase (used internally)
    * @public
    */
   put(records, phaseOverride) {
@@ -236,9 +304,18 @@ class Store {
     });
   }
   /**
-   * Remove some records from the store via their ids.
+   * Remove records from the store by their IDs.
+   *
+   * @example
+   * ```ts
+   * // Remove a single record
+   * store.remove([book.id])
+   *
+   * // Remove multiple records
+   * store.remove([book1.id, book2.id, book3.id])
+   * ```
    *
-   * @param ids - The ids of the records to remove.
+   * @param ids - The IDs of the records to remove
    * @public
    */
   remove(ids) {
@@ -265,28 +342,56 @@ class Store {
     });
   }
   /**
-   * Get the value of a store record by its id.
+   * Get a record by its ID. This creates a reactive subscription to the record.
    *
-   * @param id - The id of the record to get.
+   * @example
+   * ```ts
+   * const book = store.get(bookId)
+   * if (book) {
+   *   console.log(book.title)
+   * }
+   * ```
+   *
+   * @param id - The ID of the record to get
+   * @returns The record if it exists, undefined otherwise
    * @public
    */
   get(id) {
     return this.records.get(id);
   }
   /**
-   * Get the value of a store record by its id without updating its epoch.
+   * Get a record by its ID without creating a reactive subscription.
+   * Use this when you need to access a record but don't want reactive updates.
    *
-   * @param id - The id of the record to get.
+   * @example
+   * ```ts
+   * // Won't trigger reactive updates when this record changes
+   * const book = store.unsafeGetWithoutCapture(bookId)
+   * ```
+   *
+   * @param id - The ID of the record to get
+   * @returns The record if it exists, undefined otherwise
    * @public
    */
   unsafeGetWithoutCapture(id) {
     return this.records.__unsafe__getWithoutCapture(id);
   }
   /**
-   * Creates a JSON payload from the record store.
+   * Serialize the store's records to a plain JavaScript object.
+   * Only includes records matching the specified scope.
+   *
+   * @example
+   * ```ts
+   * // Serialize only document records (default)
+   * const documentData = store.serialize('document')
    *
-   * @param scope - The scope of records to serialize. Defaults to 'document'.
-   * @returns The record store snapshot as a JSON payload.
+   * // Serialize all records
+   * const allData = store.serialize('all')
+   * ```
+   *
+   * @param scope - The scope of records to serialize. Defaults to 'document'
+   * @returns The serialized store data
+   * @public
    */
   serialize(scope = "document") {
     const result = {};
@@ -299,14 +404,20 @@ class Store {
   }
   /**
    * Get a serialized snapshot of the store and its schema.
+   * This includes both the data and schema information needed for proper migration.
    *
+   * @example
    * ```ts
    * const snapshot = store.getStoreSnapshot()
-   * store.loadStoreSnapshot(snapshot)
-   * ```
+   * localStorage.setItem('myApp', JSON.stringify(snapshot))
    *
-   * @param scope - The scope of records to serialize. Defaults to 'document'.
+   * // Later...
+   * const saved = JSON.parse(localStorage.getItem('myApp'))
+   * store.loadStoreSnapshot(saved)
+   * ```
    *
+   * @param scope - The scope of records to serialize. Defaults to 'document'
+   * @returns A snapshot containing both store data and schema information
    * @public
    */
   getStoreSnapshot(scope = "document") {
@@ -316,14 +427,18 @@ class Store {
     };
   }
   /**
-   * Migrate a serialized snapshot of the store and its schema.
+   * Migrate a serialized snapshot to the current schema version.
+   * This applies any necessary migrations to bring old data up to date.
    *
+   * @example
    * ```ts
-   * const snapshot = store.getStoreSnapshot()
-   * store.migrateSnapshot(snapshot)
+   * const oldSnapshot = JSON.parse(localStorage.getItem('myApp'))
+   * const migratedSnapshot = store.migrateSnapshot(oldSnapshot)
    * ```
    *
-   * @param snapshot - The snapshot to load.
+   * @param snapshot - The snapshot to migrate
+   * @returns The migrated snapshot with current schema version
+   * @throws Error if migration fails
    * @public
    */
   migrateSnapshot(snapshot) {
@@ -337,14 +452,17 @@ class Store {
     };
   }
   /**
-   * Load a serialized snapshot.
+   * Load a serialized snapshot into the store, replacing all current data.
+   * The snapshot will be automatically migrated to the current schema version if needed.
    *
+   * @example
    * ```ts
-   * const snapshot = store.getStoreSnapshot()
+   * const snapshot = JSON.parse(localStorage.getItem('myApp'))
    * store.loadStoreSnapshot(snapshot)
    * ```
    *
-   * @param snapshot - The snapshot to load.
+   * @param snapshot - The snapshot to load
+   * @throws Error if migration fails or snapshot is invalid
    * @public
    */
   loadStoreSnapshot(snapshot) {
@@ -365,16 +483,28 @@ class Store {
     }
   }
   /**
-   * Get an array of all values in the store.
+   * Get an array of all records in the store.
    *
-   * @returns An array of all values in the store.
+   * @example
+   * ```ts
+   * const allRecords = store.allRecords()
+   * const books = allRecords.filter(r => r.typeName === 'book')
+   * ```
+   *
+   * @returns An array containing all records in the store
    * @public
    */
   allRecords() {
     return Array.from(this.records.values());
   }
   /**
-   * Removes all records from the store.
+   * Remove all records from the store.
+   *
+   * @example
+   * ```ts
+   * store.clear()
+   * console.log(store.allRecords().length) // 0
+   * ```
    *
    * @public
    */
@@ -382,11 +512,20 @@ class Store {
     this.remove(Array.from(this.records.keys()));
   }
   /**
-   * Update a record. To update multiple records at once, use the `update` method of the
-   * `TypedStore` class.
+   * Update a single record using an updater function. To update multiple records at once,
+   * use the `update` method of the `TypedStore` class.
    *
-   * @param id - The id of the record to update.
-   * @param updater - A function that updates the record.
+   * @example
+   * ```ts
+   * store.update(book.id, (book) => ({
+   *   ...book,
+   *   title: 'Updated Title'
+   * }))
+   * ```
+   *
+   * @param id - The ID of the record to update
+   * @param updater - A function that receives the current record and returns the updated record
+   * @public
    */
   update(id, updater) {
     const existing = this.unsafeGetWithoutCapture(id);
@@ -397,20 +536,47 @@ class Store {
     this.put([updater(existing)]);
   }
   /**
-   * Get whether the record store has a id.
+   * Check whether a record with the given ID exists in the store.
    *
-   * @param id - The id of the record to check.
+   * @example
+   * ```ts
+   * if (store.has(bookId)) {
+   *   console.log('Book exists!')
+   * }
+   * ```
+   *
+   * @param id - The ID of the record to check
+   * @returns True if the record exists, false otherwise
    * @public
    */
   has(id) {
     return this.records.has(id);
   }
   /**
-   * Add a new listener to the store.
+   * Add a listener that will be called when the store changes.
+   * Returns a function to remove the listener.
+   *
+   * @example
+   * ```ts
+   * const removeListener = store.listen((entry) => {
+   *   console.log('Changes:', entry.changes)
+   *   console.log('Source:', entry.source)
+   * })
+   *
+   * // Listen only to user changes to document records
+   * const removeDocumentListener = store.listen(
+   *   (entry) => console.log('Document changed:', entry),
+   *   { source: 'user', scope: 'document' }
+   * )
    *
-   * @param onHistory - The listener to call when the store updates.
-   * @param filters - Filters to apply to the listener.
-   * @returns A function to remove the listener.
+   * // Later, remove the listener
+   * removeListener()
+   * ```
+   *
+   * @param onHistory - The listener function to call when changes occur
+   * @param filters - Optional filters to control when the listener is called
+   * @returns A function that removes the listener when called
+   * @public
    */
   listen(onHistory, filters) {
     this._flushHistory();
@@ -435,9 +601,19 @@ class Store {
   }
   isMergingRemoteChanges = false;
   /**
-   * Merge changes from a remote source
+   * Merge changes from a remote source. Changes made within the provided function
+   * will be marked with source 'remote' instead of 'user'.
+   *
+   * @example
+   * ```ts
+   * // Changes from sync/collaboration
+   * store.mergeRemoteChanges(() => {
+   *   store.put(remoteRecords)
+   *   store.remove(deletedIds)
+   * })
+   * ```
    *
-   * @param fn - A function that merges the external changes.
+   * @param fn - A function that applies the remote changes
    * @public
    */
   mergeRemoteChanges(fn) {
@@ -666,26 +842,44 @@ function squashHistoryEntries(entries) {
 class HistoryAccumulator {
   _history = [];
   _interceptors = /* @__PURE__ */ new Set();
+  /**
+   * Add an interceptor that will be called for each history entry.
+   * Returns a function to remove the interceptor.
+   */
   addInterceptor(fn) {
     this._interceptors.add(fn);
     return () => {
       this._interceptors.delete(fn);
     };
   }
+  /**
+   * Add a history entry to the accumulator.
+   * Calls all registered interceptors with the entry.
+   */
   add(entry) {
     this._history.push(entry);
     for (const interceptor of this._interceptors) {
       interceptor(entry);
     }
   }
+  /**
+   * Flush all accumulated history entries, squashing adjacent entries from the same source.
+   * Clears the internal history buffer.
+   */
   flush() {
     const history = squashHistoryEntries(this._history);
     this._history = [];
     return history;
   }
+  /**
+   * Clear all accumulated history entries without flushing.
+   */
   clear() {
     this._history = [];
   }
+  /**
+   * Check if there are any accumulated history entries.
+   */
   hasChanges() {
     return this._history.length > 0;
   }