@tldraw/store 4.1.0-canary.5b2a01989756 → 4.1.0-canary.5d5610599458

package/src/lib/migrate.ts

@@ -23,8 +23,32 @@ function squashDependsOn(sequence: Array<Migration | StandaloneDependsOn>): Migr
 }
 
 /**
- * Creates a migration sequence.
+ * Creates a migration sequence that defines how to transform data as your schema evolves.
+ *
+ * A migration sequence contains a series of migrations that are applied in order to transform
+ * data from older versions to newer versions. Each migration is identified by a unique ID
+ * and can operate at either the record level (transforming individual records) or store level
+ * (transforming the entire store structure).
+ *
  * See the [migration guide](https://tldraw.dev/docs/persistence#Migrations) for more info on how to use this API.
+ * @param options - Configuration for the migration sequence
+ *   - sequenceId - Unique identifier for this migration sequence (e.g., 'com.myapp.book')
+ *   - sequence - Array of migrations or dependency declarations to include in the sequence
+ *   - retroactive - Whether migrations should apply to snapshots created before this sequence was added (defaults to true)
+ * @returns A validated migration sequence that can be included in a store schema
+ * @example
+ * ```ts
+ * const bookMigrations = createMigrationSequence({
+ *   sequenceId: 'com.myapp.book',
+ *   sequence: [
+ *     {
+ *       id: 'com.myapp.book/1',
+ *       scope: 'record',
+ *       up: (record) => ({ ...record, newField: 'default' })
+ *     }
+ *   ]
+ * })
+ * ```
  * @public
  */
 export function createMigrationSequence({
@@ -46,10 +70,29 @@ export function createMigrationSequence({
 }
 
 /**
- * Creates a named set of migration ids given a named set of version numbers and a sequence id.
+ * Creates a named set of migration IDs from version numbers and a sequence ID.
+ *
+ * This utility function helps generate properly formatted migration IDs that follow
+ * the required `sequenceId/version` pattern. It takes a sequence ID and a record
+ * of named versions, returning migration IDs that can be used in migration definitions.
  *
  * See the [migration guide](https://tldraw.dev/docs/persistence#Migrations) for more info on how to use this API.
- * @public
+ * @param sequenceId - The sequence identifier (e.g., 'com.myapp.book')
+ * @param versions - Record mapping version names to numbers
+ * @returns Record mapping version names to properly formatted migration IDs
+ * @example
+ * ```ts
+ * const migrationIds = createMigrationIds('com.myapp.book', {
+ *   addGenre: 1,
+ *   addPublisher: 2,
+ *   removeOldField: 3
+ * })
+ * // Result: {
+ * //   addGenre: 'com.myapp.book/1',
+ * //   addPublisher: 'com.myapp.book/2',
+ * //   removeOldField: 'com.myapp.book/3'
+ * // }
+ * ```
  * @public
  */
 export function createMigrationIds<
@@ -61,7 +104,22 @@ export function createMigrationIds<
 	) as any
 }
 
-/** @internal */
+/**
+ * Creates a migration sequence specifically for record-level migrations.
+ *
+ * This is a convenience function that creates a migration sequence where all migrations
+ * operate at the record scope and are automatically filtered to apply only to records
+ * of a specific type. Each migration in the sequence will be enhanced with the record
+ * scope and appropriate filtering logic.
+ * @param opts - Configuration for the record migration sequence
+ *   - recordType - The record type name these migrations should apply to
+ *   - filter - Optional additional filter function to determine which records to migrate
+ *   - retroactive - Whether migrations should apply to snapshots created before this sequence was added
+ *   - sequenceId - Unique identifier for this migration sequence
+ *   - sequence - Array of record migration definitions (scope will be added automatically)
+ * @returns A migration sequence configured for record-level operations
+ * @internal
+ */
 export function createRecordMigrationSequence(opts: {
 	recordType: string
 	filter?(record: UnknownRecord): boolean
@@ -88,7 +146,14 @@ export function createRecordMigrationSequence(opts: {
 	})
 }
 
-/** @public */
+/**
+ * Legacy migration interface for backward compatibility.
+ *
+ * This interface represents the old migration format that included both `up` and `down`
+ * transformation functions. While still supported, new code should use the `Migration`
+ * type which provides more flexibility and better integration with the current system.
+ * @public
+ */
 export interface LegacyMigration<Before = any, After = any> {
 	// eslint-disable-next-line @typescript-eslint/method-signature-style
 	up: (oldState: Before) => After
@@ -96,15 +161,40 @@ export interface LegacyMigration<Before = any, After = any> {
 	down: (newState: After) => Before
 }
 
-/** @public */
+/**
+ * Unique identifier for a migration in the format `sequenceId/version`.
+ *
+ * Migration IDs follow a specific pattern where the sequence ID identifies the migration
+ * sequence and the version number indicates the order within that sequence. For example:
+ * 'com.myapp.book/1', 'com.myapp.book/2', etc.
+ * @public
+ */
 export type MigrationId = `${string}/${number}`
 
-/** @public */
+/**
+ * Declares dependencies for migrations without being a migration itself.
+ *
+ * This interface allows you to specify that future migrations in a sequence depend on
+ * migrations from other sequences, without defining an actual migration transformation.
+ * It's used to establish cross-sequence dependencies in the migration graph.
+ * @public
+ */
 export interface StandaloneDependsOn {
 	readonly dependsOn: readonly MigrationId[]
 }
 
-/** @public */
+/**
+ * Defines a single migration that transforms data from one schema version to another.
+ *
+ * A migration can operate at two different scopes:
+ * - `record`: Transforms individual records, with optional filtering to target specific records
+ * - `store`: Transforms the entire serialized store structure
+ *
+ * Each migration has a unique ID and can declare dependencies on other migrations that must
+ * be applied first. The `up` function performs the forward transformation, while the optional
+ * `down` function can reverse the migration if needed.
+ * @public
+ */
 export type Migration = {
 	readonly id: MigrationId
 	readonly dependsOn?: readonly MigrationId[] | undefined
@@ -131,20 +221,43 @@ export type Migration = {
 	  }
 )
 
-/** @public */
+/**
+ * Base interface for legacy migration information.
+ *
+ * Contains the basic structure used by the legacy migration system, including version
+ * range information and the migration functions indexed by version number. This is
+ * maintained for backward compatibility with older migration definitions.
+ * @public
+ */
 export interface LegacyBaseMigrationsInfo {
 	firstVersion: number
 	currentVersion: number
 	migrators: { [version: number]: LegacyMigration }
 }
 
-/** @public */
+/**
+ * Legacy migration configuration with support for sub-type migrations.
+ *
+ * This interface extends the base legacy migration info to support migrations that
+ * vary based on a sub-type key within records. This allows different migration paths
+ * for different variants of the same record type, which was useful in older migration
+ * systems but is now handled more elegantly by the current Migration system.
+ * @public
+ */
 export interface LegacyMigrations extends LegacyBaseMigrationsInfo {
 	subTypeKey?: string
 	subTypeMigrations?: Record<string, LegacyBaseMigrationsInfo>
 }
 
-/** @public */
+/**
+ * A complete sequence of migrations that can be applied to transform data.
+ *
+ * A migration sequence represents a series of ordered migrations that belong together,
+ * typically for a specific part of your schema. The sequence includes metadata about
+ * whether it should be applied retroactively to existing data and contains the actual
+ * migration definitions in execution order.
+ * @public
+ */
 export interface MigrationSequence {
 	sequenceId: string
 	/**
@@ -180,6 +293,17 @@ export interface MigrationSequence {
  *
  * @param migrations - Array of migrations to sort
  * @returns Sorted array of migrations in execution order
+ * @throws Assertion error if circular dependencies are detected
+ * @example
+ * ```ts
+ * const sorted = sortMigrations([
+ *   { id: 'app/2', scope: 'record', up: (r) => r },
+ *   { id: 'app/1', scope: 'record', up: (r) => r },
+ *   { id: 'lib/1', scope: 'record', up: (r) => r, dependsOn: ['app/1'] }
+ * ])
+ * // Result: [app/1, app/2, lib/1] (respects both sequence and explicit deps)
+ * ```
+ * @public
  */
 export function sortMigrations(migrations: Migration[]): Migration[] {
 	if (migrations.length === 0) return []
@@ -285,7 +409,21 @@ export function sortMigrations(migrations: Migration[]): Migration[] {
 	return result
 }
 
-/** @internal */
+/**
+ * Parses a migration ID to extract the sequence ID and version number.
+ *
+ * Migration IDs follow the format `sequenceId/version`, and this function splits
+ * them into their component parts. This is used internally for sorting migrations
+ * and understanding their relationships.
+ * @param id - The migration ID to parse
+ * @returns Object containing the sequence ID and numeric version
+ * @example
+ * ```ts
+ * const { sequenceId, version } = parseMigrationId('com.myapp.book/5')
+ * // sequenceId: 'com.myapp.book', version: 5
+ * ```
+ * @internal
+ */
 export function parseMigrationId(id: MigrationId): { sequenceId: string; version: number } {
 	const [sequenceId, version] = id.split('/')
 	return { sequenceId, version: parseInt(version) }
@@ -302,6 +440,26 @@ function validateMigrationId(id: string, expectedSequenceId?: string) {
 	assert(id.match(/^(.*?)\/(0|[1-9]\d*)$/), `Invalid migration id: '${id}'`)
 }
 
+/**
+ * Validates that a migration sequence is correctly structured.
+ *
+ * Performs several validation checks to ensure the migration sequence is valid:
+ * - Sequence ID doesn't contain invalid characters
+ * - All migration IDs belong to the expected sequence
+ * - Migration versions start at 1 and increment by 1
+ * - Migration IDs follow the correct format
+ * @param migrations - The migration sequence to validate
+ * @throws Assertion error if any validation checks fail
+ * @example
+ * ```ts
+ * const sequence = createMigrationSequence({
+ *   sequenceId: 'com.myapp.book',
+ *   sequence: [{ id: 'com.myapp.book/1', scope: 'record', up: (r) => r }]
+ * })
+ * validateMigrations(sequence) // Passes validation
+ * ```
+ * @public
+ */
 export function validateMigrations(migrations: MigrationSequence) {
 	assert(
 		!migrations.sequenceId.includes('/'),
@@ -331,12 +489,27 @@ export function validateMigrations(migrations: MigrationSequence) {
 	}
 }
 
-/** @public */
+/**
+ * Result type returned by migration operations.
+ *
+ * Migration operations can either succeed and return the transformed value,
+ * or fail with a specific reason. This discriminated union type allows for
+ * safe handling of both success and error cases when applying migrations.
+ * @public
+ */
 export type MigrationResult<T> =
 	| { type: 'success'; value: T }
 	| { type: 'error'; reason: MigrationFailureReason }
 
-/** @public */
+/**
+ * Enumeration of possible reasons why a migration might fail.
+ *
+ * These reasons help identify what went wrong during migration processing,
+ * allowing applications to handle different failure scenarios appropriately.
+ * Common failures include incompatible data formats, unknown record types,
+ * and version mismatches between the data and available migrations.
+ * @public
+ */
 export enum MigrationFailureReason {
 	IncompatibleSubtype = 'incompatible-subtype',
 	UnknownType = 'unknown-type',

package/src/lib/setUtils.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest'
+import { diffSets, intersectSets } from './setUtils'
+
+describe('intersectSets', () => {
+	it('should return intersection of multiple sets', () => {
+		const set1 = new Set([1, 2, 3, 4])
+		const set2 = new Set([2, 3, 4, 5])
+		const set3 = new Set([3, 4, 5, 6])
+
+		const result = intersectSets([set1, set2, set3])
+
+		expect(Array.from(result).sort()).toEqual([3, 4])
+	})
+
+	it('should return empty set when no sets provided', () => {
+		const result = intersectSets([])
+		expect(result.size).toBe(0)
+	})
+
+	it('should return empty set when no common elements exist', () => {
+		const set1 = new Set([1, 2, 3])
+		const set2 = new Set([4, 5, 6])
+
+		const result = intersectSets([set1, set2])
+
+		expect(result.size).toBe(0)
+	})
+
+	it('should return empty set when any set is empty', () => {
+		const set1 = new Set([1, 2, 3])
+		const set2 = new Set<number>()
+		const set3 = new Set([2, 3, 4])
+
+		const result = intersectSets([set1, set2, set3])
+
+		expect(result.size).toBe(0)
+	})
+
+	it('should return copy of single set', () => {
+		const set1 = new Set([1, 2, 3])
+		const result = intersectSets([set1])
+
+		expect(result).not.toBe(set1)
+		expect(Array.from(result).sort()).toEqual([1, 2, 3])
+	})
+})
+
+describe('diffSets', () => {
+	it('should detect added elements', () => {
+		const prev = new Set(['a', 'b'])
+		const next = new Set(['a', 'b', 'c'])
+
+		const result = diffSets(prev, next)
+
+		expect(result?.added).toBeDefined()
+		expect(result?.removed).toBeUndefined()
+		expect(Array.from(result!.added!)).toEqual(['c'])
+	})
+
+	it('should detect removed elements', () => {
+		const prev = new Set(['a', 'b', 'c'])
+		const next = new Set(['a', 'b'])
+
+		const result = diffSets(prev, next)
+
+		expect(result?.removed).toBeDefined()
+		expect(result?.added).toBeUndefined()
+		expect(Array.from(result!.removed!)).toEqual(['c'])
+	})
+
+	it('should detect both added and removed elements', () => {
+		const prev = new Set(['a', 'b'])
+		const next = new Set(['b', 'c'])
+
+		const result = diffSets(prev, next)
+
+		expect(result?.added).toBeDefined()
+		expect(result?.removed).toBeDefined()
+		expect(Array.from(result!.added!)).toEqual(['c'])
+		expect(Array.from(result!.removed!)).toEqual(['a'])
+	})
+
+	it('should return undefined when sets are identical', () => {
+		const prev = new Set(['a', 'b', 'c'])
+		const next = new Set(['a', 'b', 'c'])
+
+		const result = diffSets(prev, next)
+
+		expect(result).toBeUndefined()
+	})
+
+	it('should handle object references correctly', () => {
+		const obj1 = { id: 1 }
+		const obj2 = { id: 2 }
+		const obj3 = { id: 3 }
+
+		const prev = new Set([obj1, obj2])
+		const next = new Set([obj2, obj3])
+
+		const result = diffSets(prev, next)
+
+		expect(result?.added?.has(obj3)).toBe(true)
+		expect(result?.removed?.has(obj1)).toBe(true)
+	})
+})

package/src/lib/setUtils.ts

@@ -2,8 +2,27 @@ import { CollectionDiff } from './Store'
 
 /**
  * Combine multiple sets into a single set containing only the common elements of all sets.
+ * Returns the intersection of all provided sets - elements that exist in every set.
+ * If no sets are provided, returns an empty set.
  *
- * @param sets - The sets to combine.
+ * @param sets - The sets to intersect. Can be an empty array.
+ * @returns A new set containing only elements that exist in all input sets
+ *
+ * @example
+ * ```ts
+ * const set1 = new Set([1, 2, 3])
+ * const set2 = new Set([2, 3, 4])
+ * const set3 = new Set([3, 4, 5])
+ *
+ * const intersection = intersectSets([set1, set2, set3])
+ * console.log(intersection) // Set {3}
+ *
+ * // Empty array returns empty set
+ * const empty = intersectSets([])
+ * console.log(empty) // Set {}
+ * ```
+ *
+ * @public
  */
 export function intersectSets<T>(sets: Set<T>[]) {
 	if (sets.length === 0) return new Set<T>()
@@ -21,10 +40,31 @@ export function intersectSets<T>(sets: Set<T>[]) {
 }
 
 /**
- * Calculates a diff between two sets.
+ * Calculates a diff between two sets, identifying which elements were added or removed.
+ * Returns undefined if the sets are identical (no changes detected).
+ *
+ * @param prev - The previous set to compare from
+ * @param next - The next set to compare to
+ * @returns A CollectionDiff object with `added` and/or `removed` sets, or undefined if no changes
+ *
+ * @example
+ * ```ts
+ * const prev = new Set(['a', 'b', 'c'])
+ * const next = new Set(['b', 'c', 'd'])
+ *
+ * const diff = diffSets(prev, next)
+ * console.log(diff)
+ * // {
+ * //   added: Set {'d'},
+ * //   removed: Set {'a'}
+ * // }
+ *
+ * // No changes returns undefined
+ * const same = diffSets(prev, prev)
+ * console.log(same) // undefined
+ * ```
  *
- * @param prev - The previous set
- * @param next - The next set
+ * @public
  */
 export function diffSets<T>(prev: Set<T>, next: Set<T>): CollectionDiff<T> | undefined {
 	const result: CollectionDiff<T> = {}