@tldraw/store 4.1.0-canary.e2133d922c9e → 4.1.0-canary.e259b517a450

package/src/lib/RecordType.ts

@@ -2,6 +2,17 @@ import { Expand, objectMapEntries, structuredClone, uniqueId } from '@tldraw/uti
 import { IdOf, UnknownRecord } from './BaseRecord'
 import { StoreValidator } from './Store'
 
+/**
+ * Utility type that extracts the record type from a RecordType instance.
+ *
+ * @example
+ * ```ts
+ * const Book = createRecordType<BookRecord>('book', { scope: 'document' })
+ * type BookFromType = RecordTypeRecord<typeof Book> // BookRecord
+ * ```
+ *
+ * @public
+ */
 export type RecordTypeRecord<R extends RecordType<any, any>> = ReturnType<R['create']>
 
 /**
@@ -25,12 +36,48 @@ export class RecordType<
 	R extends UnknownRecord,
 	RequiredProperties extends keyof Omit<R, 'id' | 'typeName'>,
 > {
+	/**
+	 * Factory function that creates default properties for new records.
+	 * @public
+	 */
 	readonly createDefaultProperties: () => Exclude<Omit<R, 'id' | 'typeName'>, RequiredProperties>
+
+	/**
+	 * Validator function used to validate records of this type.
+	 * @public
+	 */
 	readonly validator: StoreValidator<R>
+
+	/**
+	 * Optional configuration specifying which record properties are ephemeral.
+	 * Ephemeral properties are not included in snapshots or synchronization.
+	 * @public
+	 */
 	readonly ephemeralKeys?: { readonly [K in Exclude<keyof R, 'id' | 'typeName'>]: boolean }
+
+	/**
+	 * Set of property names that are marked as ephemeral for efficient lookup.
+	 * @public
+	 */
 	readonly ephemeralKeySet: ReadonlySet<string>
+
+	/**
+	 * The scope that determines how records of this type are persisted and synchronized.
+	 * @public
+	 */
 	readonly scope: RecordScope
 
+	/**
+	 * Creates a new RecordType instance.
+	 *
+	 * typeName - The unique type name for records created by this RecordType
+	 * config - Configuration object for the RecordType
+	 *   - createDefaultProperties - Function that returns default properties for new records
+	 *   - validator - Optional validator function for record validation
+	 *   - scope - Optional scope determining persistence behavior (defaults to 'document')
+	 *   - ephemeralKeys - Optional mapping of property names to ephemeral status
+	 * @public
+	 */
 	constructor(
 		/**
 		 * The unique type associated with this record.
@@ -65,10 +112,23 @@ export class RecordType<
 	}
 
 	/**
-	 * Create a new record of this type.
+	 * Creates a new record of this type with the given properties.
+	 *
+	 * Properties are merged with default properties from the RecordType configuration.
+	 * If no id is provided, a unique id will be generated automatically.
 	 *
-	 * @param properties - The properties of the record.
-	 * @returns The new record.
+	 * @example
+	 * ```ts
+	 * const book = Book.create({
+	 *   title: 'The Great Gatsby',
+	 *   author: 'F. Scott Fitzgerald'
+	 * })
+	 * // Result: { id: 'book:abc123', typeName: 'book', title: 'The Great Gatsby', author: 'F. Scott Fitzgerald', inStock: true }
+	 * ```
+	 *
+	 * @param properties - The properties for the new record, including both required and optional fields
+	 * @returns The newly created record with generated id and typeName
+	 * @public
 	 */
 	create(
 		properties: Expand<Pick<R, RequiredProperties> & Omit<Partial<R>, RequiredProperties>>
@@ -90,10 +150,20 @@ export class RecordType<
 	}
 
 	/**
-	 * Clone a record of this type.
+	 * Creates a deep copy of an existing record with a new unique id.
+	 *
+	 * This method performs a deep clone of all properties while generating a fresh id,
+	 * making it useful for duplicating records without id conflicts.
+	 *
+	 * @example
+	 * ```ts
+	 * const originalBook = Book.create({ title: '1984', author: 'George Orwell' })
+	 * const duplicatedBook = Book.clone(originalBook)
+	 * // duplicatedBook has same properties but different id
+	 * ```
 	 *
-	 * @param record - The record to clone.
-	 * @returns The cloned record.
+	 * @param record - The record to clone
+	 * @returns A new record with the same properties but a different id
 	 * @public
 	 */
 	clone(record: R): R {
@@ -117,10 +187,20 @@ export class RecordType<
 	}
 
 	/**
-	 * Takes an id like `user:123` and returns the part after the colon `123`
+	 * Extracts the unique identifier part from a full record id.
+	 *
+	 * Record ids have the format `typeName:uniquePart`. This method returns just the unique part.
+	 *
+	 * @example
+	 * ```ts
+	 * const bookId = Book.createId() // 'book:abc123'
+	 * const uniquePart = Book.parseId(bookId) // 'abc123'
+	 * ```
 	 *
-	 * @param id - The id
-	 * @returns
+	 * @param id - The full record id to parse
+	 * @returns The unique identifier portion after the colon
+	 * @throws Error if the id is not valid for this record type
+	 * @public
 	 */
 	parseId(id: IdOf<R>): string {
 		if (!this.isId(id)) {
@@ -131,32 +211,44 @@ export class RecordType<
 	}
 
 	/**
-	 * Check whether a record is an instance of this record type.
+	 * Type guard that checks whether a record belongs to this RecordType.
 	 *
-	 * @example
+	 * This method performs a runtime check by comparing the record's typeName
+	 * against this RecordType's typeName.
 	 *
+	 * @example
 	 * ```ts
-	 * const result = recordType.isInstance(someRecord)
+	 * if (Book.isInstance(someRecord)) {
+	 *   // someRecord is now typed as a book record
+	 *   console.log(someRecord.title)
+	 * }
 	 * ```
 	 *
-	 * @param record - The record to check.
-	 * @returns Whether the record is an instance of this record type.
+	 * @param record - The record to check, may be undefined
+	 * @returns True if the record is an instance of this record type
+	 * @public
 	 */
 	isInstance(record?: UnknownRecord): record is R {
 		return record?.typeName === this.typeName
 	}
 
 	/**
-	 * Check whether an id is an id of this type.
+	 * Type guard that checks whether an id string belongs to this RecordType.
 	 *
-	 * @example
+	 * Validates that the id starts with this RecordType's typeName followed by a colon.
+	 * This is more efficient than parsing the full id when you only need to verify the type.
 	 *
+	 * @example
 	 * ```ts
-	 * const result = recordType.isIn('someId')
+	 * if (Book.isId(someId)) {
+	 *   // someId is now typed as IdOf<BookRecord>
+	 *   const book = store.get(someId)
+	 * }
 	 * ```
 	 *
-	 * @param id - The id to check.
-	 * @returns Whether the id is an id of this type.
+	 * @param id - The id string to check, may be undefined
+	 * @returns True if the id belongs to this record type
+	 * @public
 	 */
 	isId(id?: string): id is IdOf<R> {
 		if (!id) return false
@@ -193,8 +285,26 @@ export class RecordType<
 	}
 
 	/**
-	 * Check that the passed in record passes the validations for this type. Returns its input
-	 * correctly typed if it does, but throws an error otherwise.
+	 * Validates a record against this RecordType's validator and returns it with proper typing.
+	 *
+	 * This method runs the configured validator function and throws an error if validation fails.
+	 * If a previous version of the record is provided, it may use optimized validation.
+	 *
+	 * @example
+	 * ```ts
+	 * try {
+	 *   const validBook = Book.validate(untrustedData)
+	 *   // validBook is now properly typed and validated
+	 * } catch (error) {
+	 *   console.log('Validation failed:', error.message)
+	 * }
+	 * ```
+	 *
+	 * @param record - The unknown record data to validate
+	 * @param recordBefore - Optional previous version for optimized validation
+	 * @returns The validated and properly typed record
+	 * @throws Error if validation fails
+	 * @public
 	 */
 	validate(record: unknown, recordBefore?: R): R {
 		if (recordBefore && this.validator.validateUsingKnownGoodVersion) {
@@ -205,15 +315,29 @@ export class RecordType<
 }
 
 /**
- * Create a record type.
+ * Creates a new RecordType with the specified configuration.
  *
- * @example
+ * This factory function creates a RecordType that can be used to create, validate, and manage
+ * records of a specific type within a store. The resulting RecordType can be extended with
+ * default properties using the withDefaultProperties method.
  *
+ * @example
  * ```ts
- * const Book = createRecordType<Book>('book')
+ * interface BookRecord extends BaseRecord<'book', RecordId<BookRecord>> {
+ *   title: string
+ *   author: string
+ *   inStock: boolean
+ * }
+ *
+ * const Book = createRecordType<BookRecord>('book', {
+ *   scope: 'document',
+ *   validator: bookValidator
+ * })
  * ```
  *
- * @param typeName - The name of the type to create.
+ * @param typeName - The unique type name for this record type
+ * @param config - Configuration object containing validator, scope, and ephemeral keys
+ * @returns A new RecordType instance for creating and managing records
  * @public
  */
 export function createRecordType<R extends UnknownRecord>(

package/src/lib/RecordsDiff.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from 'vitest'
+import { BaseRecord, RecordId } from './BaseRecord'
+import {
+	RecordsDiff,
+	createEmptyRecordsDiff,
+	isRecordsDiffEmpty,
+	reverseRecordsDiff,
+	squashRecordDiffs,
+	squashRecordDiffsMutable,
+} from './RecordsDiff'
+
+// Test interface for testing
+interface TestBook extends BaseRecord<'book', RecordId<TestBook>> {
+	title: string
+	author: string
+	pages: number
+}
+
+// Helper functions to create test records
+function createBook(id: string, title: string, author: string, pages: number = 100): TestBook {
+	return {
+		id: id as RecordId<TestBook>,
+		typeName: 'book',
+		title,
+		author,
+		pages,
+	}
+}
+
+// Helper to create a diff
+function createDiff<R extends TestBook>(
+	added: Record<string, R> = {},
+	updated: Record<string, [R, R]> = {},
+	removed: Record<string, R> = {}
+): RecordsDiff<R> {
+	return {
+		added: added as any,
+		updated: updated as any,
+		removed: removed as any,
+	}
+}
+
+describe('isRecordsDiffEmpty', () => {
+	it('should return true for empty diffs and false for non-empty diffs', () => {
+		const emptyDiff = createEmptyRecordsDiff<TestBook>()
+		expect(isRecordsDiffEmpty(emptyDiff)).toBe(true)
+
+		const addedDiff = createDiff<TestBook>({ 'book:1': createBook('book:1', 'Test', 'Author') })
+		expect(isRecordsDiffEmpty(addedDiff)).toBe(false)
+
+		const oldBook = createBook('book:1', 'Old Title', 'Author')
+		const newBook = createBook('book:1', 'New Title', 'Author')
+		const updatedDiff = createDiff<TestBook>({}, { 'book:1': [oldBook, newBook] })
+		expect(isRecordsDiffEmpty(updatedDiff)).toBe(false)
+
+		const removedDiff = createDiff<TestBook>(
+			{},
+			{},
+			{ 'book:1': createBook('book:1', 'Deleted', 'Author') }
+		)
+		expect(isRecordsDiffEmpty(removedDiff)).toBe(false)
+	})
+})
+
+describe('reverseRecordsDiff', () => {
+	it('should reverse all operation types correctly', () => {
+		const addedBook = createBook('book:1', 'Added Book', 'Author')
+		const oldUpdatedBook = createBook('book:2', 'Old Title', 'Author')
+		const newUpdatedBook = createBook('book:2', 'New Title', 'Author')
+		const removedBook = createBook('book:3', 'Removed Book', 'Author')
+
+		const originalDiff = createDiff<TestBook>(
+			{ 'book:1': addedBook },
+			{ 'book:2': [oldUpdatedBook, newUpdatedBook] },
+			{ 'book:3': removedBook }
+		)
+
+		const reversedDiff = reverseRecordsDiff(originalDiff)
+
+		// Added becomes removed
+		expect(reversedDiff.removed['book:1']).toEqual(addedBook)
+		// Removed becomes added
+		expect(reversedDiff.added['book:3']).toEqual(removedBook)
+		// Updated swaps from/to
+		expect(reversedDiff.updated['book:2']).toEqual([newUpdatedBook, oldUpdatedBook])
+	})
+})
+
+describe('squashRecordDiffs', () => {
+	it('should handle core diff squashing operations', () => {
+		// Add then update becomes single add with final state
+		const initialBook = createBook('book:1', 'Initial Title', 'Author')
+		const updatedBook = createBook('book:1', 'Updated Title', 'Author')
+
+		const diff1 = createDiff<TestBook>({ 'book:1': initialBook })
+		const diff2 = createDiff<TestBook>({}, { 'book:1': [initialBook, updatedBook] })
+		const result1 = squashRecordDiffs([diff1, diff2])
+		expect(result1).toEqual(createDiff<TestBook>({ 'book:1': updatedBook }))
+
+		// Add then remove cancels out
+		const book = createBook('book:1', 'Test Book', 'Author')
+		const diff3 = createDiff<TestBook>({ 'book:1': book })
+		const diff4 = createDiff<TestBook>({}, {}, { 'book:1': book })
+		const result2 = squashRecordDiffs([diff3, diff4])
+		expect(result2).toEqual(createEmptyRecordsDiff<TestBook>())
+
+		// Remove then add becomes update
+		const originalBook = createBook('book:1', 'Original', 'Author')
+		const newBook = createBook('book:1', 'New', 'Author')
+		const diff5 = createDiff<TestBook>({}, {}, { 'book:1': originalBook })
+		const diff6 = createDiff<TestBook>({ 'book:1': newBook })
+		const result3 = squashRecordDiffs([diff5, diff6])
+		expect(result3).toEqual(createDiff<TestBook>({}, { 'book:1': [originalBook, newBook] }))
+
+		// Chain updates together
+		const v1 = createBook('book:1', 'Version 1', 'Author')
+		const v2 = createBook('book:1', 'Version 2', 'Author')
+		const v3 = createBook('book:1', 'Version 3', 'Author')
+		const diff7 = createDiff<TestBook>({}, { 'book:1': [v1, v2] })
+		const diff8 = createDiff<TestBook>({}, { 'book:1': [v2, v3] })
+		const result4 = squashRecordDiffs([diff7, diff8])
+		expect(result4).toEqual(createDiff<TestBook>({}, { 'book:1': [v1, v3] }))
+	})
+})
+
+describe('squashRecordDiffsMutable', () => {
+	it('should maintain consistency with squashRecordDiffs', () => {
+		const book1 = createBook('book:1', 'Book 1', 'Author')
+		const book2Old = createBook('book:2', 'Book 2 Old', 'Author')
+		const book2New = createBook('book:2', 'Book 2 New', 'Author')
+
+		const diff1 = createDiff<TestBook>({ 'book:1': book1 })
+		const diff2 = createDiff<TestBook>({}, { 'book:2': [book2Old, book2New] })
+
+		// Test immutable version
+		const immutableResult = squashRecordDiffs([diff1, diff2])
+
+		// Test mutable version
+		const mutableTarget = createEmptyRecordsDiff<TestBook>()
+		squashRecordDiffsMutable(mutableTarget, [diff1, diff2])
+
+		expect(immutableResult).toEqual(mutableTarget)
+	})
+})

package/src/lib/RecordsDiff.ts

@@ -2,22 +2,81 @@ import { objectMapEntries } from '@tldraw/utils'
 import { IdOf, UnknownRecord } from './BaseRecord'
 
 /**
- * A diff describing the changes to a record.
+ * A diff describing the changes to records, containing collections of records that were added,
+ * updated, or removed. This is the fundamental data structure used throughout the store system
+ * to track and communicate changes.
+ *
+ * @example
+ * ```ts
+ * const diff: RecordsDiff<Book> = {
+ *   added: {
+ *     'book:1': { id: 'book:1', typeName: 'book', title: 'New Book' }
+ *   },
+ *   updated: {
+ *     'book:2': [
+ *       { id: 'book:2', typeName: 'book', title: 'Old Title' }, // from
+ *       { id: 'book:2', typeName: 'book', title: 'New Title' }  // to
+ *     ]
+ *   },
+ *   removed: {
+ *     'book:3': { id: 'book:3', typeName: 'book', title: 'Deleted Book' }
+ *   }
+ * }
+ * ```
  *
  * @public
  */
 export interface RecordsDiff<R extends UnknownRecord> {
+	/** Records that were created, keyed by their ID */
 	added: Record<IdOf<R>, R>
+	/** Records that were modified, keyed by their ID. Each entry contains [from, to] tuple */
 	updated: Record<IdOf<R>, [from: R, to: R]>
+	/** Records that were deleted, keyed by their ID */
 	removed: Record<IdOf<R>, R>
 }
 
-/** @internal */
+/**
+ * Creates an empty RecordsDiff with no added, updated, or removed records.
+ * This is useful as a starting point when building diffs programmatically.
+ *
+ * @returns An empty RecordsDiff with all collections initialized to empty objects
+ * @example
+ * ```ts
+ * const emptyDiff = createEmptyRecordsDiff<Book>()
+ * // Result: { added: {}, updated: {}, removed: {} }
+ * ```
+ *
+ * @internal
+ */
 export function createEmptyRecordsDiff<R extends UnknownRecord>(): RecordsDiff<R> {
 	return { added: {}, updated: {}, removed: {} } as RecordsDiff<R>
 }
 
-/** @public */
+/**
+ * Creates the inverse of a RecordsDiff, effectively reversing all changes.
+ * Added records become removed, removed records become added, and updated records
+ * have their from/to values swapped. This is useful for implementing undo operations.
+ *
+ * @param diff - The diff to reverse
+ * @returns A new RecordsDiff that represents the inverse of the input diff
+ * @example
+ * ```ts
+ * const originalDiff: RecordsDiff<Book> = {
+ *   added: { 'book:1': newBook },
+ *   updated: { 'book:2': [oldBook, updatedBook] },
+ *   removed: { 'book:3': deletedBook }
+ * }
+ *
+ * const reversedDiff = reverseRecordsDiff(originalDiff)
+ * // Result: {
+ * //   added: { 'book:3': deletedBook },
+ * //   updated: { 'book:2': [updatedBook, oldBook] },
+ * //   removed: { 'book:1': newBook }
+ * // }
+ * ```
+ *
+ * @public
+ */
 export function reverseRecordsDiff(diff: RecordsDiff<any>) {
 	const result: RecordsDiff<any> = { added: diff.removed, removed: diff.added, updated: {} }
 	for (const [from, to] of Object.values(diff.updated)) {
@@ -27,8 +86,25 @@ export function reverseRecordsDiff(diff: RecordsDiff<any>) {
 }
 
 /**
- * Is a records diff empty?
- * @internal
+ * Checks whether a RecordsDiff contains any changes. A diff is considered empty
+ * if it has no added, updated, or removed records.
+ *
+ * @param diff - The diff to check
+ * @returns True if the diff contains no changes, false otherwise
+ * @example
+ * ```ts
+ * const emptyDiff = createEmptyRecordsDiff<Book>()
+ * console.log(isRecordsDiffEmpty(emptyDiff)) // true
+ *
+ * const nonEmptyDiff: RecordsDiff<Book> = {
+ *   added: { 'book:1': someBook },
+ *   updated: {},
+ *   removed: {}
+ * }
+ * console.log(isRecordsDiffEmpty(nonEmptyDiff)) // false
+ * ```
+ *
+ * @public
  */
 export function isRecordsDiffEmpty<T extends UnknownRecord>(diff: RecordsDiff<T>) {
 	return (
@@ -39,11 +115,38 @@ export function isRecordsDiffEmpty<T extends UnknownRecord>(diff: RecordsDiff<T>
 }
 
 /**
- * Squash a collection of diffs into a single diff.
+ * Combines multiple RecordsDiff objects into a single consolidated diff.
+ * This function intelligently merges changes, handling cases where the same record
+ * is modified multiple times across different diffs. For example, if a record is
+ * added in one diff and then updated in another, the result will show it as added
+ * with the final state.
+ *
+ * @param diffs - An array of diffs to combine into a single diff
+ * @param options - Configuration options for the squashing operation
+ *   - mutateFirstDiff - If true, modifies the first diff in place instead of creating a new one
+ * @returns A single diff that represents the cumulative effect of all input diffs
+ * @example
+ * ```ts
+ * const diff1: RecordsDiff<Book> = {
+ *   added: { 'book:1': { id: 'book:1', title: 'New Book' } },
+ *   updated: {},
+ *   removed: {}
+ * }
+ *
+ * const diff2: RecordsDiff<Book> = {
+ *   added: {},
+ *   updated: { 'book:1': [{ id: 'book:1', title: 'New Book' }, { id: 'book:1', title: 'Updated Title' }] },
+ *   removed: {}
+ * }
+ *
+ * const squashed = squashRecordDiffs([diff1, diff2])
+ * // Result: {
+ * //   added: { 'book:1': { id: 'book:1', title: 'Updated Title' } },
+ * //   updated: {},
+ * //   removed: {}
+ * // }
+ * ```
  *
- * @param diffs - An array of diffs to squash.
- * @param options - An optional object with a `mutateFirstDiff` property. If `mutateFirstDiff` is true, the first diff in the array will be mutated in-place.
- * @returns A single diff that represents the squashed diffs.
  * @public
  */
 export function squashRecordDiffs<T extends UnknownRecord>(
@@ -61,7 +164,39 @@ export function squashRecordDiffs<T extends UnknownRecord>(
 }
 
 /**
- * Apply the array `diffs` to the `target` diff, mutating it in-place.
+ * Applies an array of diffs to a target diff by mutating the target in-place.
+ * This is the core implementation used by squashRecordDiffs. It handles complex
+ * scenarios where records move between added/updated/removed states across multiple diffs.
+ *
+ * The function processes each diff sequentially, applying the following logic:
+ * - Added records: If the record was previously removed, convert to an update; otherwise add it
+ * - Updated records: Chain updates together, preserving the original 'from' state
+ * - Removed records: If the record was added in this sequence, cancel both operations
+ *
+ * @param target - The diff to modify in-place (will be mutated)
+ * @param diffs - Array of diffs to apply to the target
+ * @example
+ * ```ts
+ * const targetDiff: RecordsDiff<Book> = {
+ *   added: {},
+ *   updated: {},
+ *   removed: { 'book:1': oldBook }
+ * }
+ *
+ * const newDiffs = [{
+ *   added: { 'book:1': newBook },
+ *   updated: {},
+ *   removed: {}
+ * }]
+ *
+ * squashRecordDiffsMutable(targetDiff, newDiffs)
+ * // targetDiff is now: {
+ * //   added: {},
+ * //   updated: { 'book:1': [oldBook, newBook] },
+ * //   removed: {}
+ * // }
+ * ```
+ *
  * @internal
  */
 export function squashRecordDiffsMutable<T extends UnknownRecord>(