@tldraw/store 3.16.0-next.fe14f1b4181f → 4.0.1

package/src/lib/Store.ts

@@ -501,21 +501,11 @@ export class Store<R extends UnknownRecord = UnknownRecord, Props = unknown> {
 		}
 	}
 
-	/**
-	 * @deprecated use `getSnapshot` from the 'tldraw' package instead.
-	 */
-	getSnapshot(scope: RecordScope | 'all' = 'document') {
-		console.warn(
-			'[tldraw] `Store.getSnapshot` is deprecated and will be removed in a future release. Use `getSnapshot` from the `tldraw` package instead.'
-		)
-		return this.getStoreSnapshot(scope)
-	}
-
 	/**
 	 * Migrate a serialized snapshot of the store and its schema.
 	 *
 	 * ```ts
-	 * const snapshot = store.getSnapshot()
+	 * const snapshot = store.getStoreSnapshot()
 	 * store.migrateSnapshot(snapshot)
 	 * ```
 	 *
@@ -566,17 +556,6 @@ export class Store<R extends UnknownRecord = UnknownRecord, Props = unknown> {
 		}
 	}
 
-	/**
-	 * @public
-	 * @deprecated use `loadSnapshot` from the 'tldraw' package instead.
-	 */
-	loadSnapshot(snapshot: StoreSnapshot<R>) {
-		console.warn(
-			"[tldraw] `Store.loadSnapshot` is deprecated and will be removed in a future release. Use `loadSnapshot` from the 'tldraw' package instead."
-		)
-		this.loadStoreSnapshot(snapshot)
-	}
-
 	/**
 	 * Get an array of all values in the store.
 	 *

package/src/lib/StoreSchema.ts

@@ -349,6 +349,7 @@ export class StoreSchema<R extends UnknownRecord, P = unknown> {
 
 	/**
 	 * @deprecated This is only here for legacy reasons, don't use it unless you have david's blessing!
+	 * @internal
 	 */
 	serializeEarliestVersion(): SerializedSchema {
 		return {

package/src/lib/migrate.ts

@@ -2,45 +2,6 @@ import { assert, objectMapEntries } from '@tldraw/utils'
 import { UnknownRecord } from './BaseRecord'
 import { SerializedStore } from './Store'
 
-let didWarn = false
-
-/**
- * @public
- * @deprecated use `createShapePropsMigrationSequence` instead. See [the docs](https://tldraw.dev/docs/persistence#Updating-legacy-shape-migrations-defineMigrations) for how to migrate.
- */
-export function defineMigrations(opts: {
-	firstVersion?: number
-	currentVersion?: number
-	migrators?: Record<number, LegacyMigration>
-	subTypeKey?: string
-	subTypeMigrations?: Record<string, LegacyBaseMigrationsInfo>
-}): LegacyMigrations {
-	const { currentVersion, firstVersion, migrators = {}, subTypeKey, subTypeMigrations } = opts
-	if (!didWarn) {
-		console.warn(
-			`The 'defineMigrations' function is deprecated and will be removed in a future release. Use the new migrations API instead. See the migration guide for more info: https://tldraw.dev/docs/persistence#Updating-legacy-shape-migrations-defineMigrations`
-		)
-		didWarn = true
-	}
-
-	// Some basic guards against impossible version combinations, some of which will be caught by TypeScript
-	if (typeof currentVersion === 'number' && typeof firstVersion === 'number') {
-		if ((currentVersion as number) === (firstVersion as number)) {
-			throw Error(`Current version is equal to initial version.`)
-		} else if (currentVersion < firstVersion) {
-			throw Error(`Current version is lower than initial version.`)
-		}
-	}
-
-	return {
-		firstVersion: (firstVersion as number) ?? 0, // defaults
-		currentVersion: (currentVersion as number) ?? 0, // defaults
-		migrators,
-		subTypeKey,
-		subTypeMigrations,
-	}
-}
-
 function squashDependsOn(sequence: Array<Migration | StandaloneDependsOn>): Migration[] {
 	const result: Migration[] = []
 	for (let i = sequence.length - 1; i >= 0; i--) {
@@ -199,38 +160,126 @@ export interface MigrationSequence {
 	sequence: Migration[]
 }
 
+/**
+ * Sorts migrations using a distance-minimizing topological sort.
+ *
+ * This function respects two types of dependencies:
+ * 1. Implicit sequence dependencies (foo/1 must come before foo/2)
+ * 2. Explicit dependencies via `dependsOn` property
+ *
+ * The algorithm minimizes the total distance between migrations and their explicit
+ * dependencies in the final ordering, while maintaining topological correctness.
+ * This means when migration A depends on migration B, A will be scheduled as close
+ * as possible to B (while respecting all constraints).
+ *
+ * Implementation uses Kahn's algorithm with priority scoring:
+ * - Builds dependency graph and calculates in-degrees
+ * - Uses priority queue that prioritizes migrations which unblock explicit dependencies
+ * - Processes migrations in urgency order while maintaining topological constraints
+ * - Detects cycles by ensuring all migrations are processed
+ *
+ * @param migrations - Array of migrations to sort
+ * @returns Sorted array of migrations in execution order
+ */
 export function sortMigrations(migrations: Migration[]): Migration[] {
-	// we do a topological sort using dependsOn and implicit dependencies between migrations in the same sequence
-	const byId = new Map(migrations.map((m) => [m.id, m]))
-	const isProcessing = new Set<MigrationId>()
+	if (migrations.length === 0) return []
 
-	const result: Migration[] = []
+	// Build dependency graph and calculate in-degrees
+	const byId = new Map(migrations.map((m) => [m.id, m]))
+	const dependents = new Map<MigrationId, Set<MigrationId>>() // who depends on this
+	const inDegree = new Map<MigrationId, number>()
+	const explicitDeps = new Map<MigrationId, Set<MigrationId>>() // explicit dependsOn relationships
 
-	function process(m: Migration) {
-		assert(!isProcessing.has(m.id), `Circular dependency in migrations: ${m.id}`)
-		isProcessing.add(m.id)
+	// Initialize
+	for (const m of migrations) {
+		inDegree.set(m.id, 0)
+		dependents.set(m.id, new Set())
+		explicitDeps.set(m.id, new Set())
+	}
 
+	// Add implicit sequence dependencies and explicit dependencies
+	for (const m of migrations) {
 		const { version, sequenceId } = parseMigrationId(m.id)
-		const parent = byId.get(`${sequenceId}/${version - 1}`)
-		if (parent) {
-			process(parent)
+
+		// Implicit dependency on previous in sequence
+		const prevId = `${sequenceId}/${version - 1}` as MigrationId
+		if (byId.has(prevId)) {
+			dependents.get(prevId)!.add(m.id)
+			inDegree.set(m.id, inDegree.get(m.id)! + 1)
 		}
 
+		// Explicit dependencies
 		if (m.dependsOn) {
-			for (const dep of m.dependsOn) {
-				const depMigration = byId.get(dep)
-				if (depMigration) {
-					process(depMigration)
+			for (const depId of m.dependsOn) {
+				if (byId.has(depId)) {
+					dependents.get(depId)!.add(m.id)
+					explicitDeps.get(m.id)!.add(depId)
+					inDegree.set(m.id, inDegree.get(m.id)! + 1)
+				}
+			}
+		}
+	}
+
+	// Priority queue: migrations ready to process (in-degree 0)
+	const ready = migrations.filter((m) => inDegree.get(m.id) === 0)
+	const result: Migration[] = []
+	const processed = new Set<MigrationId>()
+
+	while (ready.length > 0) {
+		// Calculate urgency scores for ready migrations and pick the best one
+		let bestCandidate: Migration | undefined
+		let bestCandidateScore = -Infinity
+
+		for (const m of ready) {
+			let urgencyScore = 0
+
+			for (const depId of dependents.get(m.id) || []) {
+				if (!processed.has(depId)) {
+					// Priority 1: Count all unprocessed dependents (to break ties)
+					urgencyScore += 1
+
+					// Priority 2: If this migration is explicitly depended on by others, boost priority
+					if (explicitDeps.get(depId)!.has(m.id)) {
+						urgencyScore += 100
+					}
 				}
 			}
+
+			if (
+				urgencyScore > bestCandidateScore ||
+				// Tiebreaker: prefer lower sequence/version
+				(urgencyScore === bestCandidateScore && m.id.localeCompare(bestCandidate?.id ?? '') < 0)
+			) {
+				bestCandidate = m
+				bestCandidateScore = urgencyScore
+			}
 		}
 
-		byId.delete(m.id)
-		result.push(m)
+		const nextMigration = bestCandidate!
+		ready.splice(ready.indexOf(nextMigration), 1)
+
+		// Cycle detection - if we have processed everything and still have items left, there's a cycle
+		// This is handled by Kahn's algorithm naturally - if we finish with items unprocessed, there's a cycle
+
+		// Process this migration
+		result.push(nextMigration)
+		processed.add(nextMigration.id)
+
+		// Update in-degrees and add newly ready migrations
+		for (const depId of dependents.get(nextMigration.id) || []) {
+			if (!processed.has(depId)) {
+				inDegree.set(depId, inDegree.get(depId)! - 1)
+				if (inDegree.get(depId) === 0) {
+					ready.push(byId.get(depId)!)
+				}
+			}
+		}
 	}
 
-	for (const m of byId.values()) {
-		process(m)
+	// Check for cycles - if we didn't process all migrations, there's a cycle
+	if (result.length !== migrations.length) {
+		const unprocessed = migrations.filter((m) => !processed.has(m.id))
+		assert(false, `Circular dependency in migrations: ${unprocessed[0].id}`)
 	}
 
 	return result

package/src/lib/test/sortMigrations.test.ts

@@ -31,6 +31,38 @@ describe(sortMigrations, () => {
 		).toEqual(['bar/1', 'bar/2', 'foo/1', 'foo/2'])
 	})
 
+	it('should minimize distance between dependencies and dependents', () => {
+		// bar/3 depends on foo/1 - should process bar sequence immediately after foo/1
+		expect(
+			sort([m('foo/2'), m('bar/3', { dependsOn: ['foo/1'] }), m('foo/1'), m('bar/1'), m('bar/2')])
+		).toEqual(['foo/1', 'bar/1', 'bar/2', 'bar/3', 'foo/2'])
+	})
+
+	it('should minimize total distance for multiple explicit dependencies', () => {
+		// Both bar/2 and baz/1 depend on foo/1 - minimize total distance
+		expect(
+			sort([
+				m('foo/2'),
+				m('bar/2', { dependsOn: ['foo/1'] }),
+				m('foo/1'),
+				m('bar/1'),
+				m('baz/1', { dependsOn: ['foo/1'] }),
+			])
+		).toEqual(['foo/1', 'bar/1', 'bar/2', 'baz/1', 'foo/2'])
+	})
+
+	it('should handle chain of explicit dependencies optimally', () => {
+		// foo/1 -> bar/1 -> baz/1 chain should be consecutive
+		expect(
+			sort([
+				m('foo/2'),
+				m('bar/1', { dependsOn: ['foo/1'] }),
+				m('foo/1'),
+				m('baz/1', { dependsOn: ['bar/1'] }),
+			])
+		).toEqual(['foo/1', 'bar/1', 'baz/1', 'foo/2'])
+	})
+
 	it('should fail if a cycle is created', () => {
 		expect(() => {
 			sort([m('foo/1', { dependsOn: ['foo/1'] })])

package/src/lib/test/defineMigrations.test.ts

@@ -1,232 +0,0 @@
-import { defineMigrations } from '../migrate'
-
-const Versions = {
-	Initial: 0,
-	January: 1,
-	February: 2,
-	March: 3,
-} as const
-
-describe('define migrations tests', () => {
-	it('defines migrations', () => {
-		expect(() => {
-			// no versions
-			// eslint-disable-next-line @typescript-eslint/no-deprecated
-			defineMigrations({
-				firstVersion: Versions.Initial,
-			})
-		}).not.toThrow()
-
-		expect(() => {
-			// no versions
-			// eslint-disable-next-line @typescript-eslint/no-deprecated
-			defineMigrations({
-				firstVersion: Versions.February,
-			})
-		}).not.toThrow()
-
-		expect(() => {
-			// empty migrators
-			// eslint-disable-next-line @typescript-eslint/no-deprecated
-			defineMigrations({
-				migrators: {},
-			})
-		}).not.toThrow()
-
-		expect(() => {
-			// no versions!
-			// eslint-disable-next-line @typescript-eslint/no-deprecated
-			defineMigrations({
-				migrators: {
-					[Versions.February]: {
-						up: (rec: any) => rec,
-						down: (rec: any) => rec,
-					},
-				},
-			})
-		}).not.toThrow()
-
-		expect(() => {
-			// wrong current version!
-			// eslint-disable-next-line @typescript-eslint/no-deprecated
-			defineMigrations({
-				currentVersion: Versions.January,
-				migrators: {
-					[Versions.February]: {
-						up: (rec: any) => rec,
-						down: (rec: any) => rec,
-					},
-				},
-			})
-		}).not.toThrow()
-
-		expect(() => {
-			// eslint-disable-next-line @typescript-eslint/no-deprecated
-			defineMigrations({
-				currentVersion: Versions.February,
-				migrators: {
-					// has a default zero version
-					[Versions.January]: {
-						up: (rec: any) => rec,
-						down: (rec: any) => rec,
-					},
-					// has a current version
-					[Versions.February]: {
-						up: (rec: any) => rec,
-						down: (rec: any) => rec,
-					},
-				},
-			})
-		}).not.toThrow()
-
-		expect(() => {
-			// can't provide only first version
-			// eslint-disable-next-line @typescript-eslint/no-deprecated
-			defineMigrations({
-				firstVersion: Versions.January,
-				migrators: {},
-			})
-		}).not.toThrow()
-
-		expect(() => {
-			// same version
-			// eslint-disable-next-line @typescript-eslint/no-deprecated
-			defineMigrations({
-				firstVersion: Versions.Initial,
-				currentVersion: Versions.Initial,
-				migrators: {},
-			})
-		}).toThrow()
-
-		expect(() => {
-			// only first version
-			// eslint-disable-next-line @typescript-eslint/no-deprecated
-			defineMigrations({
-				firstVersion: Versions.January,
-				migrators: {},
-			})
-		}).not.toThrow()
-
-		expect(() => {
-			// missing only version
-			// eslint-disable-next-line @typescript-eslint/no-deprecated
-			defineMigrations({
-				firstVersion: Versions.January,
-				currentVersion: Versions.January,
-				migrators: {},
-			})
-		}).toThrow()
-
-		expect(() => {
-			// only version, explicit start and current
-			// eslint-disable-next-line @typescript-eslint/no-deprecated
-			defineMigrations({
-				firstVersion: Versions.January,
-				currentVersion: Versions.January,
-				migrators: {
-					[Versions.January]: {
-						up: (rec: any) => rec,
-						down: (rec: any) => rec,
-					},
-				},
-			})
-		}).toThrow()
-
-		expect(() => {
-			// missing later versions
-			// eslint-disable-next-line @typescript-eslint/no-deprecated
-			defineMigrations({
-				firstVersion: Versions.January,
-				currentVersion: Versions.February,
-				migrators: {},
-			})
-		}).not.toThrow()
-
-		expect(() => {
-			// missing later versions
-			// eslint-disable-next-line @typescript-eslint/no-deprecated
-			defineMigrations({
-				firstVersion: Versions.Initial,
-				currentVersion: Versions.February,
-				migrators: {
-					[Versions.January]: {
-						up: (rec: any) => rec,
-						down: (rec: any) => rec,
-					},
-				},
-			})
-		}).not.toThrow()
-
-		expect(() => {
-			// missing earlier versions
-			// eslint-disable-next-line @typescript-eslint/no-deprecated
-			defineMigrations({
-				firstVersion: Versions.Initial,
-				currentVersion: Versions.February,
-				migrators: {
-					[Versions.February]: {
-						up: (rec: any) => rec,
-						down: (rec: any) => rec,
-					},
-				},
-			})
-		}).not.toThrow()
-
-		expect(() => {
-			// got em all
-			// eslint-disable-next-line @typescript-eslint/no-deprecated
-			defineMigrations({
-				firstVersion: Versions.Initial,
-				currentVersion: Versions.February,
-				migrators: {
-					[Versions.January]: {
-						up: (rec: any) => rec,
-						down: (rec: any) => rec,
-					},
-					[Versions.February]: {
-						up: (rec: any) => rec,
-						down: (rec: any) => rec,
-					},
-				},
-			})
-		}).not.toThrow()
-
-		expect(() => {
-			// got em all starting later
-			// eslint-disable-next-line @typescript-eslint/no-deprecated
-			defineMigrations({
-				firstVersion: Versions.January,
-				currentVersion: Versions.March,
-				migrators: {
-					[Versions.February]: {
-						up: (rec: any) => rec,
-						down: (rec: any) => rec,
-					},
-					[Versions.March]: {
-						up: (rec: any) => rec,
-						down: (rec: any) => rec,
-					},
-				},
-			})
-		}).not.toThrow()
-
-		expect(() => {
-			// first migration should be first version + 1
-			// eslint-disable-next-line @typescript-eslint/no-deprecated
-			defineMigrations({
-				firstVersion: Versions.February,
-				currentVersion: Versions.March,
-				migrators: {
-					[Versions.February]: {
-						up: (rec: any) => rec,
-						down: (rec: any) => rec,
-					},
-					[Versions.March]: {
-						up: (rec: any) => rec,
-						down: (rec: any) => rec,
-					},
-				},
-			})
-		}).not.toThrow()
-	})
-})