@tldraw/store 4.1.0-canary.9f9255bd7a83 → 4.1.0-canary.a6e63b3bbde6

package/src/lib/StoreSchema.ts

@@ -19,7 +19,31 @@ import {
 	validateMigrations,
 } from './migrate'
 
-/** @public */
+/**
+ * Version 1 format for serialized store schema information.
+ *
+ * This is the legacy format used before schema version 2. Version 1 schemas
+ * separate store-level versioning from record-level versioning, and support
+ * subtypes for complex record types like shapes.
+ *
+ * @example
+ * ```ts
+ * const schemaV1: SerializedSchemaV1 = {
+ *   schemaVersion: 1,
+ *   storeVersion: 2,
+ *   recordVersions: {
+ *     book: { version: 3 },
+ *     shape: {
+ *       version: 2,
+ *       subTypeVersions: { rectangle: 1, circle: 2 },
+ *       subTypeKey: 'type'
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export interface SerializedSchemaV1 {
 	/** Schema version is the version for this type you're looking at right now */
 	schemaVersion: 1
@@ -43,7 +67,28 @@ export interface SerializedSchemaV1 {
 	>
 }
 
-/** @public */
+/**
+ * Version 2 format for serialized store schema information.
+ *
+ * This is the current format that uses a unified sequence-based approach
+ * for tracking versions across all migration sequences. Each sequence ID
+ * maps to the latest version number for that sequence.
+ *
+ * @example
+ * ```ts
+ * const schemaV2: SerializedSchemaV2 = {
+ *   schemaVersion: 2,
+ *   sequences: {
+ *     'com.tldraw.store': 3,
+ *     'com.tldraw.book': 2,
+ *     'com.tldraw.shape': 4,
+ *     'com.tldraw.shape.rectangle': 1
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export interface SerializedSchemaV2 {
 	schemaVersion: 2
 	sequences: {
@@ -51,9 +96,58 @@ export interface SerializedSchemaV2 {
 	}
 }
 
-/** @public */
+/**
+ * Union type representing all supported serialized schema formats.
+ *
+ * This type allows the store to handle both legacy (V1) and current (V2)
+ * schema formats during deserialization and migration.
+ *
+ * @example
+ * ```ts
+ * function handleSchema(schema: SerializedSchema) {
+ *   if (schema.schemaVersion === 1) {
+ *     // Handle V1 format
+ *     console.log('Store version:', schema.storeVersion)
+ *   } else {
+ *     // Handle V2 format
+ *     console.log('Sequences:', schema.sequences)
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export type SerializedSchema = SerializedSchemaV1 | SerializedSchemaV2
 
+/**
+ * Upgrades a serialized schema from version 1 to version 2 format.
+ *
+ * Version 1 schemas use separate `storeVersion` and `recordVersions` fields,
+ * while version 2 schemas use a unified `sequences` object with sequence IDs.
+ *
+ * @param schema - The serialized schema to upgrade
+ * @returns A Result containing the upgraded schema or an error message
+ *
+ * @example
+ * ```ts
+ * const v1Schema = {
+ *   schemaVersion: 1,
+ *   storeVersion: 1,
+ *   recordVersions: {
+ *     book: { version: 2 },
+ *     author: { version: 1, subTypeVersions: { fiction: 1 }, subTypeKey: 'genre' }
+ *   }
+ * }
+ *
+ * const result = upgradeSchema(v1Schema)
+ * if (result.ok) {
+ *   console.log(result.value.sequences)
+ *   // { 'com.tldraw.store': 1, 'com.tldraw.book': 2, 'com.tldraw.author': 1, 'com.tldraw.author.fiction': 1 }
+ * }
+ * ```
+ *
+ * @public
+ */
 export function upgradeSchema(schema: SerializedSchema): Result<SerializedSchemaV2, string> {
 	if (schema.schemaVersion > 2 || schema.schemaVersion < 1) return Result.err('Bad schema version')
 	if (schema.schemaVersion === 2) return Result.ok(schema as SerializedSchemaV2)
@@ -75,7 +169,32 @@ export function upgradeSchema(schema: SerializedSchema): Result<SerializedSchema
 	return Result.ok(result)
 }
 
-/** @public */
+/**
+ * Information about a record validation failure that occurred in the store.
+ *
+ * This interface provides context about validation errors, including the failed
+ * record, the store state, and the operation phase where the failure occurred.
+ * It's used by validation failure handlers to implement recovery strategies.
+ *
+ * @example
+ * ```ts
+ * const schema = StoreSchema.create(
+ *   { book: Book },
+ *   {
+ *     onValidationFailure: (failure: StoreValidationFailure<Book>) => {
+ *       console.error(`Validation failed during ${failure.phase}:`, failure.error)
+ *       console.log('Failed record:', failure.record)
+ *       console.log('Previous record:', failure.recordBefore)
+ *
+ *       // Return a corrected version of the record
+ *       return { ...failure.record, title: failure.record.title || 'Untitled' }
+ *     }
+ *   }
+ * )
+ * ```
+ *
+ * @public
+ */
 export interface StoreValidationFailure<R extends UnknownRecord> {
 	error: unknown
 	store: Store<R>
@@ -84,7 +203,30 @@ export interface StoreValidationFailure<R extends UnknownRecord> {
 	recordBefore: R | null
 }
 
-/** @public */
+/**
+ * Configuration options for creating a StoreSchema.
+ *
+ * These options control migration behavior, validation error handling,
+ * and integrity checking for the store schema.
+ *
+ * @example
+ * ```ts
+ * const options: StoreSchemaOptions<MyRecord, MyProps> = {
+ *   migrations: [bookMigrations, authorMigrations],
+ *   onValidationFailure: (failure) => {
+ *     // Log the error and return a corrected record
+ *     console.error('Validation failed:', failure.error)
+ *     return sanitizeRecord(failure.record)
+ *   },
+ *   createIntegrityChecker: (store) => {
+ *     // Set up integrity checking logic
+ *     return setupIntegrityChecks(store)
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export interface StoreSchemaOptions<R extends UnknownRecord, P> {
 	migrations?: MigrationSequence[]
 	/** @public */
@@ -93,8 +235,68 @@ export interface StoreSchemaOptions<R extends UnknownRecord, P> {
 	createIntegrityChecker?(store: Store<R, P>): void
 }
 
-/** @public */
+/**
+ * Manages the schema definition, validation, and migration system for a Store.
+ *
+ * StoreSchema coordinates record types, handles data migrations between schema
+ * versions, validates records, and provides the foundational structure for
+ * reactive stores. It acts as the central authority for data consistency
+ * and evolution within the store system.
+ *
+ * @example
+ * ```ts
+ * // Define record types
+ * const Book = createRecordType<Book>('book', { scope: 'document' })
+ * const Author = createRecordType<Author>('author', { scope: 'document' })
+ *
+ * // Create schema with migrations
+ * const schema = StoreSchema.create(
+ *   { book: Book, author: Author },
+ *   {
+ *     migrations: [bookMigrations, authorMigrations],
+ *     onValidationFailure: (failure) => {
+ *       console.warn('Validation failed, using default:', failure.error)
+ *       return failure.record // or return a corrected version
+ *     }
+ *   }
+ * )
+ *
+ * // Use with store
+ * const store = new Store({ schema })
+ * ```
+ *
+ * @public
+ */
 export class StoreSchema<R extends UnknownRecord, P = unknown> {
+	/**
+	 * Creates a new StoreSchema with the given record types and options.
+	 *
+	 * This static factory method is the recommended way to create a StoreSchema.
+	 * It ensures type safety while providing a clean API for schema definition.
+	 *
+	 * @param types - Object mapping type names to their RecordType definitions
+	 * @param options - Optional configuration for migrations, validation, and integrity checking
+	 * @returns A new StoreSchema instance
+	 *
+	 * @example
+	 * ```ts
+	 * const Book = createRecordType<Book>('book', { scope: 'document' })
+	 * const Author = createRecordType<Author>('author', { scope: 'document' })
+	 *
+	 * const schema = StoreSchema.create(
+	 *   {
+	 *     book: Book,
+	 *     author: Author
+	 *   },
+	 *   {
+	 *     migrations: [bookMigrations],
+	 *     onValidationFailure: (failure) => failure.record
+	 *   }
+	 * )
+	 * ```
+	 *
+	 * @public
+	 */
 	static create<R extends UnknownRecord, P = unknown>(
 		// HACK: making this param work with RecordType is an enormous pain
 		// let's just settle for making sure each typeName has a corresponding RecordType
@@ -132,6 +334,35 @@ export class StoreSchema<R extends UnknownRecord, P = unknown> {
 		}
 	}
 
+	/**
+	 * Validates a record using its corresponding RecordType validator.
+	 *
+	 * This method ensures that records conform to their type definitions before
+	 * being stored. If validation fails and an onValidationFailure handler is
+	 * provided, it will be called to potentially recover from the error.
+	 *
+	 * @param store - The store instance where validation is occurring
+	 * @param record - The record to validate
+	 * @param phase - The lifecycle phase where validation is happening
+	 * @param recordBefore - The previous version of the record (for updates)
+	 * @returns The validated record, potentially modified by validation failure handler
+	 *
+	 * @example
+	 * ```ts
+	 * try {
+	 *   const validatedBook = schema.validateRecord(
+	 *     store,
+	 *     { id: 'book:1', typeName: 'book', title: '', author: 'Jane Doe' },
+	 *     'createRecord',
+	 *     null
+	 *   )
+	 * } catch (error) {
+	 *   console.error('Record validation failed:', error)
+	 * }
+	 * ```
+	 *
+	 * @public
+	 */
 	validateRecord(
 		store: Store<R>,
 		record: R,
@@ -159,6 +390,34 @@ export class StoreSchema<R extends UnknownRecord, P = unknown> {
 		}
 	}
 
+	/**
+	 * Gets all migrations that need to be applied to upgrade from a persisted schema
+	 * to the current schema version.
+	 *
+	 * This method compares the persisted schema with the current schema and determines
+	 * which migrations need to be applied to bring the data up to date. It handles
+	 * both regular migrations and retroactive migrations, and caches results for
+	 * performance.
+	 *
+	 * @param persistedSchema - The schema version that was previously persisted
+	 * @returns A Result containing the list of migrations to apply, or an error message
+	 *
+	 * @example
+	 * ```ts
+	 * const persistedSchema = {
+	 *   schemaVersion: 2,
+	 *   sequences: { 'com.tldraw.book': 1, 'com.tldraw.author': 0 }
+	 * }
+	 *
+	 * const migrationsResult = schema.getMigrationsSince(persistedSchema)
+	 * if (migrationsResult.ok) {
+	 *   console.log('Migrations to apply:', migrationsResult.value.length)
+	 *   // Apply each migration to bring data up to date
+	 * }
+	 * ```
+	 *
+	 * @public
+	 */
 	public getMigrationsSince(persistedSchema: SerializedSchema): Result<Migration[], string> {
 		// Check cache first
 		const cached = this.migrationCache.get(persistedSchema)
@@ -227,6 +486,34 @@ export class StoreSchema<R extends UnknownRecord, P = unknown> {
 		return result
 	}
 
+	/**
+	 * Migrates a single persisted record to match the current schema version.
+	 *
+	 * This method applies the necessary migrations to transform a record from an
+	 * older (or newer) schema version to the current version. It supports both
+	 * forward ('up') and backward ('down') migrations.
+	 *
+	 * @param record - The record to migrate
+	 * @param persistedSchema - The schema version the record was persisted with
+	 * @param direction - Direction to migrate ('up' for newer, 'down' for older)
+	 * @returns A MigrationResult containing the migrated record or an error
+	 *
+	 * @example
+	 * ```ts
+	 * const oldRecord = { id: 'book:1', typeName: 'book', title: 'Old Title', publishDate: '2020-01-01' }
+	 * const oldSchema = { schemaVersion: 2, sequences: { 'com.tldraw.book': 1 } }
+	 *
+	 * const result = schema.migratePersistedRecord(oldRecord, oldSchema, 'up')
+	 * if (result.type === 'success') {
+	 *   console.log('Migrated record:', result.value)
+	 *   // Record now has publishedYear instead of publishDate
+	 * } else {
+	 *   console.error('Migration failed:', result.reason)
+	 * }
+	 * ```
+	 *
+	 * @public
+	 */
 	migratePersistedRecord(
 		record: R,
 		persistedSchema: SerializedSchema,
@@ -282,6 +569,37 @@ export class StoreSchema<R extends UnknownRecord, P = unknown> {
 		return { type: 'success', value: record }
 	}
 
+	/**
+	 * Migrates an entire store snapshot to match the current schema version.
+	 *
+	 * This method applies all necessary migrations to bring a persisted store
+	 * snapshot up to the current schema version. It handles both record-level
+	 * and store-level migrations, and can optionally mutate the input store
+	 * for performance.
+	 *
+	 * @param snapshot - The store snapshot containing data and schema information
+	 * @param opts - Options controlling migration behavior
+	 *   - mutateInputStore - Whether to modify the input store directly (default: false)
+	 * @returns A MigrationResult containing the migrated store or an error
+	 *
+	 * @example
+	 * ```ts
+	 * const snapshot = {
+	 *   schema: { schemaVersion: 2, sequences: { 'com.tldraw.book': 1 } },
+	 *   store: {
+	 *     'book:1': { id: 'book:1', typeName: 'book', title: 'Old Book', publishDate: '2020-01-01' }
+	 *   }
+	 * }
+	 *
+	 * const result = schema.migrateStoreSnapshot(snapshot)
+	 * if (result.type === 'success') {
+	 *   console.log('Migrated store:', result.value)
+	 *   // All records are now at current schema version
+	 * }
+	 * ```
+	 *
+	 * @public
+	 */
 	migrateStoreSnapshot(
 		snapshot: StoreSnapshot<R>,
 		opts?: { mutateInputStore?: boolean }
@@ -330,11 +648,50 @@ export class StoreSchema<R extends UnknownRecord, P = unknown> {
 		return { type: 'success', value: store }
 	}
 
-	/** @internal */
+	/**
+	 * Creates an integrity checker function for the given store.
+	 *
+	 * This method calls the createIntegrityChecker option if provided, allowing
+	 * custom integrity checking logic to be set up for the store. The integrity
+	 * checker is used to validate store consistency and catch data corruption.
+	 *
+	 * @param store - The store instance to create an integrity checker for
+	 * @returns An integrity checker function, or undefined if none is configured
+	 *
+	 * @internal
+	 */
 	createIntegrityChecker(store: Store<R, P>): (() => void) | undefined {
 		return this.options.createIntegrityChecker?.(store) ?? undefined
 	}
 
+	/**
+	 * Serializes the current schema to a SerializedSchemaV2 format.
+	 *
+	 * This method creates a serialized representation of the current schema,
+	 * capturing the latest version number for each migration sequence.
+	 * The result can be persisted and later used to determine what migrations
+	 * need to be applied when loading data.
+	 *
+	 * @returns A SerializedSchemaV2 object representing the current schema state
+	 *
+	 * @example
+	 * ```ts
+	 * const serialized = schema.serialize()
+	 * console.log(serialized)
+	 * // {
+	 * //   schemaVersion: 2,
+	 * //   sequences: {
+	 * //     'com.tldraw.book': 3,
+	 * //     'com.tldraw.author': 2
+	 * //   }
+	 * // }
+	 *
+	 * // Store this with your data for future migrations
+	 * localStorage.setItem('schema', JSON.stringify(serialized))
+	 * ```
+	 *
+	 * @public
+	 */
 	serialize(): SerializedSchemaV2 {
 		return {
 			schemaVersion: 2,
@@ -348,6 +705,14 @@ export class StoreSchema<R extends UnknownRecord, P = unknown> {
 	}
 
 	/**
+	 * Serializes a schema representing the earliest possible version.
+	 *
+	 * This method creates a serialized schema where all migration sequences
+	 * are set to version 0, representing the state before any migrations
+	 * have been applied. This is used in specific legacy scenarios.
+	 *
+	 * @returns A SerializedSchema with all sequences set to version 0
+	 *
 	 * @deprecated This is only here for legacy reasons, don't use it unless you have david's blessing!
 	 * @internal
 	 */
@@ -360,7 +725,20 @@ export class StoreSchema<R extends UnknownRecord, P = unknown> {
 		}
 	}
 
-	/** @internal */
+	/**
+	 * Gets the RecordType definition for a given type name.
+	 *
+	 * This method retrieves the RecordType associated with the specified
+	 * type name, which contains the record's validation, creation, and
+	 * other behavioral logic.
+	 *
+	 * @param typeName - The name of the record type to retrieve
+	 * @returns The RecordType definition for the specified type
+	 *
+	 * @throws Will throw an error if the record type does not exist
+	 *
+	 * @internal
+	 */
 	getType(typeName: string) {
 		const type = getOwnProperty(this.types, typeName)
 		assert(type, 'record type does not exists')