@react-text-game/core 0.2.1 → 0.3.0

package/dist/saves/migrations/index.js

@@ -0,0 +1,40 @@
+/**
+ * Save Migration System
+ *
+ * This module provides a complete solution for versioning and migrating game saves.
+ * It allows developers to register migration functions that transform save data
+ * from older versions to newer versions.
+ *
+ * ## Key Concepts
+ *
+ * - **Migration**: A function that transforms save data from version A to version B
+ * - **Migration Path**: A sequence of migrations needed to go from an old version to the current version
+ * - **Migration Chain**: Migrations are applied sequentially (1.0.0 → 1.1.0 → 1.2.0 → 2.0.0)
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { registerMigration } from '@react-text-game/core/saves';
+ *
+ * // Register a migration when you make a breaking change
+ * registerMigration({
+ *   from: "1.0.0",
+ *   to: "1.1.0",
+ *   description: "Added player inventory system",
+ *   migrate: (data) => ({
+ *     ...data,
+ *     player: {
+ *       ...data.player,
+ *       inventory: [] // Add default value
+ *     }
+ *   })
+ * });
+ * ```
+ *
+ * Migrations are automatically applied when loading saves via `useLoadGame()`.
+ *
+ * @module saves/migrations
+ */
+export { clearMigrations, findMigrationPath, getAllMigrations, registerMigration, validateMigrations, } from "./registry";
+export { migrateToCurrentVersion, runMigrations } from "./runner";
+//# sourceMappingURL=index.js.map

package/dist/saves/migrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/saves/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EACH,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,uBAAuB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC"}

package/dist/saves/migrations/registry.d.ts

@@ -0,0 +1,72 @@
+import { SaveMigration } from "./types";
+/**
+ * Registers a migration function for moving from one version to another.
+ *
+ * Migrations should be registered during game initialization, typically in
+ * your game's entry point after calling `Game.init()`.
+ *
+ * @param migration - The migration definition
+ * @throws Error if a migration with the same from->to path already exists
+ *
+ * @example
+ * ```typescript
+ * registerMigration({
+ *   from: "1.0.0",
+ *   to: "1.1.0",
+ *   description: "Added player inventory",
+ *   migrate: (data) => ({
+ *     ...data,
+ *     player: { ...data.player, inventory: [] }
+ *   })
+ * });
+ * ```
+ */
+export declare function registerMigration(migration: SaveMigration): void;
+/**
+ * Clears all registered migrations.
+ * Primarily used for testing.
+ *
+ * @internal
+ */
+export declare function clearMigrations(): void;
+/**
+ * Gets all registered migrations.
+ *
+ * @returns Array of all registered migration definitions
+ */
+export declare function getAllMigrations(): SaveMigration[];
+/**
+ * Finds the shortest migration path from one version to another using BFS.
+ *
+ * This function builds a graph of all registered migrations and uses
+ * breadth-first search to find the shortest sequence of migrations
+ * needed to go from the source version to the target version.
+ *
+ * @param fromVersion - The starting version (e.g., "1.0.0")
+ * @param toVersion - The target version (e.g., "2.0.0")
+ * @returns Array of migrations to apply in order, or null if no path exists
+ *
+ * @example
+ * ```typescript
+ * // Registered migrations: 1.0.0→1.1.0, 1.1.0→1.2.0, 1.2.0→2.0.0
+ * const path = findMigrationPath("1.0.0", "2.0.0");
+ * // Returns: [migration_1_0_to_1_1, migration_1_1_to_1_2, migration_1_2_to_2_0]
+ * ```
+ */
+export declare function findMigrationPath(fromVersion: string, toVersion: string): SaveMigration[] | null;
+/**
+ * Validates that the migration registry forms a valid chain.
+ *
+ * Checks for:
+ * - Orphaned migrations (from versions with no incoming migrations)
+ * - Dead ends (to versions with no outgoing migrations, except latest)
+ * - Duplicate migrations
+ *
+ * @param latestVersion - The current/latest version of the game
+ * @returns Validation result with any issues found
+ */
+export declare function validateMigrations(latestVersion: string): {
+    valid: boolean;
+    issues: string[];
+};
+//# sourceMappingURL=registry.d.ts.map

package/dist/saves/migrations/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/saves/migrations/registry.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAaxC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,aAAa,GAAG,IAAI,CAahE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,EAAE,CAElD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC7B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAClB,aAAa,EAAE,GAAG,IAAI,CA+DxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG;IACvD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CACpB,CA6CA"}

package/dist/saves/migrations/registry.js

@@ -0,0 +1,174 @@
+import { logger } from "../../logger";
+/**
+ * In-memory registry of all registered migrations.
+ * Maps "from -> to" version pairs to migration objects.
+ */
+const migrations = new Map();
+/**
+ * Helper to create a unique key for a migration edge
+ */
+const getMigrationKey = (from, to) => `${from}→${to}`;
+/**
+ * Registers a migration function for moving from one version to another.
+ *
+ * Migrations should be registered during game initialization, typically in
+ * your game's entry point after calling `Game.init()`.
+ *
+ * @param migration - The migration definition
+ * @throws Error if a migration with the same from->to path already exists
+ *
+ * @example
+ * ```typescript
+ * registerMigration({
+ *   from: "1.0.0",
+ *   to: "1.1.0",
+ *   description: "Added player inventory",
+ *   migrate: (data) => ({
+ *     ...data,
+ *     player: { ...data.player, inventory: [] }
+ *   })
+ * });
+ * ```
+ */
+export function registerMigration(migration) {
+    const key = getMigrationKey(migration.from, migration.to);
+    if (migrations.has(key)) {
+        throw new Error(`Migration from ${migration.from} to ${migration.to} is already registered`);
+    }
+    migrations.set(key, migration);
+    logger.log(`Registered save migration: ${migration.from} → ${migration.to} (${migration.description})`);
+}
+/**
+ * Clears all registered migrations.
+ * Primarily used for testing.
+ *
+ * @internal
+ */
+export function clearMigrations() {
+    migrations.clear();
+}
+/**
+ * Gets all registered migrations.
+ *
+ * @returns Array of all registered migration definitions
+ */
+export function getAllMigrations() {
+    return Array.from(migrations.values());
+}
+/**
+ * Finds the shortest migration path from one version to another using BFS.
+ *
+ * This function builds a graph of all registered migrations and uses
+ * breadth-first search to find the shortest sequence of migrations
+ * needed to go from the source version to the target version.
+ *
+ * @param fromVersion - The starting version (e.g., "1.0.0")
+ * @param toVersion - The target version (e.g., "2.0.0")
+ * @returns Array of migrations to apply in order, or null if no path exists
+ *
+ * @example
+ * ```typescript
+ * // Registered migrations: 1.0.0→1.1.0, 1.1.0→1.2.0, 1.2.0→2.0.0
+ * const path = findMigrationPath("1.0.0", "2.0.0");
+ * // Returns: [migration_1_0_to_1_1, migration_1_1_to_1_2, migration_1_2_to_2_0]
+ * ```
+ */
+export function findMigrationPath(fromVersion, toVersion) {
+    // If versions are the same, no migration needed
+    if (fromVersion === toVersion) {
+        return [];
+    }
+    // Build adjacency list of version graph
+    const graph = new Map();
+    const migrationMap = new Map();
+    for (const migration of migrations.values()) {
+        if (!graph.has(migration.from)) {
+            graph.set(migration.from, []);
+        }
+        graph.get(migration.from).push(migration.to);
+        migrationMap.set(getMigrationKey(migration.from, migration.to), migration);
+    }
+    // BFS to find shortest path
+    const queue = [
+        { version: fromVersion, path: [] },
+    ];
+    const visited = new Set([fromVersion]);
+    while (queue.length > 0) {
+        const current = queue.shift();
+        // Check if we reached the target
+        if (current.version === toVersion) {
+            // Reconstruct the migration path
+            const migrationPath = [];
+            for (let i = 0; i < current.path.length; i++) {
+                const from = i === 0 ? fromVersion : current.path[i - 1];
+                const to = current.path[i];
+                if (!from || !to) {
+                    continue; // Skip if either is undefined
+                }
+                const migration = migrationMap.get(getMigrationKey(from, to));
+                if (migration) {
+                    migrationPath.push(migration);
+                }
+            }
+            return migrationPath;
+        }
+        // Explore neighbors
+        const neighbors = graph.get(current.version) || [];
+        for (const neighbor of neighbors) {
+            if (!visited.has(neighbor)) {
+                visited.add(neighbor);
+                queue.push({
+                    version: neighbor,
+                    path: [...current.path, neighbor],
+                });
+            }
+        }
+    }
+    // No path found
+    return null;
+}
+/**
+ * Validates that the migration registry forms a valid chain.
+ *
+ * Checks for:
+ * - Orphaned migrations (from versions with no incoming migrations)
+ * - Dead ends (to versions with no outgoing migrations, except latest)
+ * - Duplicate migrations
+ *
+ * @param latestVersion - The current/latest version of the game
+ * @returns Validation result with any issues found
+ */
+export function validateMigrations(latestVersion) {
+    const issues = [];
+    const allMigrations = getAllMigrations();
+    if (allMigrations.length === 0) {
+        return { valid: true, issues: [] };
+    }
+    // Collect all version nodes
+    const fromVersions = new Set();
+    const toVersions = new Set();
+    for (const migration of allMigrations) {
+        fromVersions.add(migration.from);
+        toVersions.add(migration.to);
+    }
+    // Find orphaned versions (versions that are targets but have no path from any base version)
+    const baseVersions = new Set(Array.from(fromVersions).filter((v) => !toVersions.has(v)));
+    // Check if all versions can reach the latest version
+    for (const baseVersion of baseVersions) {
+        const path = findMigrationPath(baseVersion, latestVersion);
+        if (path === null) {
+            issues.push(`No migration path from base version ${baseVersion} to latest version ${latestVersion}`);
+        }
+    }
+    // Check for dead ends (versions that have no outgoing migrations, except latest)
+    for (const toVersion of toVersions) {
+        if (toVersion !== latestVersion && !fromVersions.has(toVersion)) {
+            issues.push(`Dead end detected: Version ${toVersion} has no outgoing migrations`);
+        }
+    }
+    return {
+        valid: issues.length === 0,
+        issues,
+    };
+}
+//# sourceMappingURL=registry.js.map

package/dist/saves/migrations/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/saves/migrations/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAIjC;;;GAGG;AACH,MAAM,UAAU,GAAG,IAAI,GAAG,EAAyB,CAAC;AAEpD;;GAEG;AACH,MAAM,eAAe,GAAG,CAAC,IAAY,EAAE,EAAU,EAAU,EAAE,CAAC,GAAG,IAAI,IAAI,EAAE,EAAE,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAwB;IACtD,MAAM,GAAG,GAAG,eAAe,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,CAAC,CAAC;IAE1D,IAAI,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACX,kBAAkB,SAAS,CAAC,IAAI,OAAO,SAAS,CAAC,EAAE,wBAAwB,CAC9E,CAAC;IACN,CAAC;IAED,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IAC/B,MAAM,CAAC,GAAG,CACN,8BAA8B,SAAS,CAAC,IAAI,MAAM,SAAS,CAAC,EAAE,KAAK,SAAS,CAAC,WAAW,GAAG,CAC9F,CAAC;AACN,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe;IAC3B,UAAU,CAAC,KAAK,EAAE,CAAC;AACvB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB;IAC5B,OAAO,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,iBAAiB,CAC7B,WAAmB,EACnB,SAAiB;IAEjB,gDAAgD;IAChD,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,EAAE,CAAC;IACd,CAAC;IAED,wCAAwC;IACxC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC1C,MAAM,YAAY,GAAG,IAAI,GAAG,EAAyB,CAAC;IAEtD,KAAK,MAAM,SAAS,IAAI,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC;QAC1C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7B,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAClC,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAE,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QAC9C,YAAY,CAAC,GAAG,CACZ,eAAe,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,CAAC,EAC7C,SAAS,CACZ,CAAC;IACN,CAAC;IAED,4BAA4B;IAC5B,MAAM,KAAK,GAA+C;QACtD,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,EAAE,EAAE;KACrC,CAAC;IACF,MAAM,OAAO,GAAG,IAAI,GAAG,CAAS,CAAC,WAAW,CAAC,CAAC,CAAC;IAE/C,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,EAAG,CAAC;QAE/B,iCAAiC;QACjC,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAChC,iCAAiC;YACjC,MAAM,aAAa,GAAoB,EAAE,CAAC;YAC1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC3C,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;gBACzD,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBAC3B,IAAI,CAAC,IAAI,IAAI,CAAC,EAAE,EAAE,CAAC;oBACf,SAAS,CAAC,8BAA8B;gBAC5C,CAAC;gBACD,MAAM,SAAS,GAAG,YAAY,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;gBAC9D,IAAI,SAAS,EAAE,CAAC;oBACZ,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;gBAClC,CAAC;YACL,CAAC;YACD,OAAO,aAAa,CAAC;QACzB,CAAC;QAED,oBAAoB;QACpB,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QACnD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YAC/B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACzB,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;gBACtB,KAAK,CAAC,IAAI,CAAC;oBACP,OAAO,EAAE,QAAQ;oBACjB,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC;iBACpC,CAAC,CAAC;YACP,CAAC;QACL,CAAC;IACL,CAAC;IAED,gBAAgB;IAChB,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAAC,aAAqB;IAIpD,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,aAAa,GAAG,gBAAgB,EAAE,CAAC;IAEzC,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IACvC,CAAC;IAED,4BAA4B;IAC5B,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACvC,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IAErC,KAAK,MAAM,SAAS,IAAI,aAAa,EAAE,CAAC;QACpC,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACjC,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACjC,CAAC;IAED,4FAA4F;IAC5F,MAAM,YAAY,GAAG,IAAI,GAAG,CACxB,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAC7D,CAAC;IAEF,qDAAqD;IACrD,KAAK,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,iBAAiB,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;QAC3D,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAChB,MAAM,CAAC,IAAI,CACP,uCAAuC,WAAW,sBAAsB,aAAa,EAAE,CAC1F,CAAC;QACN,CAAC;IACL,CAAC;IAED,iFAAiF;IACjF,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACjC,IAAI,SAAS,KAAK,aAAa,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9D,MAAM,CAAC,IAAI,CACP,8BAA8B,SAAS,6BAA6B,CACvE,CAAC;QACN,CAAC;IACL,CAAC;IAED,OAAO;QACH,KAAK,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC;QAC1B,MAAM;KACT,CAAC;AACN,CAAC"}

package/dist/saves/migrations/runner.d.ts

@@ -0,0 +1,45 @@
+import { GameSaveState } from "../../types";
+import { MigrationOptions, MigrationResult } from "./types";
+/**
+ * Runs the migration chain to migrate save data from one version to another.
+ *
+ * This function:
+ * 1. Finds the shortest migration path using BFS
+ * 2. Applies each migration in sequence
+ * 3. Returns the migrated data or error information
+ *
+ * @param data - The save data to migrate
+ * @param fromVersion - The version the save was created with
+ * @param toVersion - The target version to migrate to (usually current game version)
+ * @param options - Migration behavior options
+ * @returns Migration result with success status and migrated data
+ *
+ * @example
+ * ```typescript
+ * const result = runMigrations(oldSaveData, "1.0.0", "2.0.0");
+ * if (result.success) {
+ *   console.log("Migrated data:", result.data);
+ * } else {
+ *   console.error("Migration failed:", result.error);
+ * }
+ * ```
+ */
+export declare function runMigrations(data: GameSaveState, fromVersion: string, toVersion: string, options?: MigrationOptions): MigrationResult;
+/**
+ * Convenience function to migrate save data to the current game version.
+ *
+ * @param data - The save data to migrate
+ * @param fromVersion - The version the save was created with
+ * @param options - Migration behavior options
+ * @returns Migration result
+ *
+ * @example
+ * ```typescript
+ * const result = migrateToCurrentVersion(saveData, "1.0.0");
+ * if (result.success) {
+ *   Game.setState(result.data);
+ * }
+ * ```
+ */
+export declare function migrateToCurrentVersion(data: GameSaveState, fromVersion: string, options?: MigrationOptions): MigrationResult;
+//# sourceMappingURL=runner.d.ts.map

package/dist/saves/migrations/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/saves/migrations/runner.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAGvC,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CACzB,IAAI,EAAE,aAAa,EACnB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,gBAAqB,GAC/B,eAAe,CAqIjB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CACnC,IAAI,EAAE,aAAa,EACnB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,gBAAgB,GAC3B,eAAe,CAGjB"}

package/dist/saves/migrations/runner.js

@@ -0,0 +1,139 @@
+import { logger } from "../../logger";
+import { _getOptions } from "../../options";
+import { findMigrationPath } from "./registry";
+/**
+ * Runs the migration chain to migrate save data from one version to another.
+ *
+ * This function:
+ * 1. Finds the shortest migration path using BFS
+ * 2. Applies each migration in sequence
+ * 3. Returns the migrated data or error information
+ *
+ * @param data - The save data to migrate
+ * @param fromVersion - The version the save was created with
+ * @param toVersion - The target version to migrate to (usually current game version)
+ * @param options - Migration behavior options
+ * @returns Migration result with success status and migrated data
+ *
+ * @example
+ * ```typescript
+ * const result = runMigrations(oldSaveData, "1.0.0", "2.0.0");
+ * if (result.success) {
+ *   console.log("Migrated data:", result.data);
+ * } else {
+ *   console.error("Migration failed:", result.error);
+ * }
+ * ```
+ */
+export function runMigrations(data, fromVersion, toVersion, options = {}) {
+    const { strict = false, verbose } = options;
+    // Determine verbosity (default to dev mode setting)
+    const shouldLog = verbose !== undefined ? verbose : _getOptions().isDevMode;
+    // If versions match, no migration needed
+    if (fromVersion === toVersion) {
+        if (shouldLog) {
+            logger.log(`No migration needed: save version ${fromVersion} matches current version`);
+        }
+        return {
+            success: true,
+            data,
+            migrationsApplied: [],
+        };
+    }
+    // Find migration path
+    if (shouldLog) {
+        logger.log(`Finding migration path from ${fromVersion} to ${toVersion}...`);
+    }
+    const migrationPath = findMigrationPath(fromVersion, toVersion);
+    if (migrationPath === null) {
+        const errorMsg = `No migration path found from version ${fromVersion} to ${toVersion}`;
+        if (strict) {
+            throw new Error(errorMsg);
+        }
+        logger.warn(`${errorMsg}. Returning original data. This may cause compatibility issues.`);
+        return {
+            success: false,
+            error: errorMsg,
+            migrationsApplied: [],
+        };
+    }
+    if (migrationPath.length === 0) {
+        return {
+            success: true,
+            data,
+            migrationsApplied: [],
+        };
+    }
+    // Log migration plan
+    if (shouldLog) {
+        logger.log(`Found migration path with ${migrationPath.length} step(s):`);
+        migrationPath.forEach((m, i) => {
+            logger.log(`  ${i + 1}. ${m.from} → ${m.to}: ${m.description}`);
+        });
+    }
+    // Apply migrations sequentially
+    let currentData = data;
+    const appliedMigrations = [];
+    try {
+        for (const migration of migrationPath) {
+            if (shouldLog) {
+                logger.log(`Applying migration: ${migration.from} → ${migration.to}`);
+            }
+            // Run migration
+            const migratedData = migration.migrate(currentData);
+            // Validate migration output
+            if (!migratedData ||
+                typeof migratedData !== "object" ||
+                Array.isArray(migratedData)) {
+                throw new Error(`Migration ${migration.from} → ${migration.to} returned invalid data type. Expected object, got ${typeof migratedData}`);
+            }
+            currentData = migratedData;
+            appliedMigrations.push({
+                from: migration.from,
+                to: migration.to,
+                description: migration.description,
+            });
+            if (shouldLog) {
+                logger.log(`Successfully applied migration: ${migration.from} → ${migration.to}`);
+            }
+        }
+        if (shouldLog) {
+            logger.log(`Migration complete: ${fromVersion} → ${toVersion} (${appliedMigrations.length} steps)`);
+        }
+        return {
+            success: true,
+            data: currentData,
+            migrationsApplied: appliedMigrations,
+        };
+    }
+    catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        logger.error(`Migration failed at step ${appliedMigrations.length + 1}: ${errorMsg}`);
+        return {
+            success: false,
+            error: errorMsg,
+            migrationsApplied: appliedMigrations,
+        };
+    }
+}
+/**
+ * Convenience function to migrate save data to the current game version.
+ *
+ * @param data - The save data to migrate
+ * @param fromVersion - The version the save was created with
+ * @param options - Migration behavior options
+ * @returns Migration result
+ *
+ * @example
+ * ```typescript
+ * const result = migrateToCurrentVersion(saveData, "1.0.0");
+ * if (result.success) {
+ *   Game.setState(result.data);
+ * }
+ * ```
+ */
+export function migrateToCurrentVersion(data, fromVersion, options) {
+    const currentVersion = _getOptions().gameVersion;
+    return runMigrations(data, fromVersion, currentVersion, options);
+}
+//# sourceMappingURL=runner.js.map

package/dist/saves/migrations/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../../src/saves/migrations/runner.ts"],"names":[],"mappings":"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"}

package/dist/saves/migrations/types.d.ts

@@ -0,0 +1,182 @@
+import { GameSaveState } from "../../types";
+export type MigrationGameSaveState = Partial<GameSaveState> & Record<string, unknown>;
+/**
+ * A function that migrates game save data from one version to another.
+ *
+ * Migration functions should be pure (no side effects) and should always
+ * return a new object rather than mutating the input.
+ *
+ * @template T - The shape of the game save state for this migration. Can be a partial
+ *               type if the migration only touches specific fields. Defaults to GameSaveState.
+ *
+ * @param data - The game save state at the source version
+ * @returns The migrated game save state at the target version
+ *
+ * @example
+ * Basic migration without specific types:
+ * ```typescript
+ * const migrateFn: SaveMigrationFn = (data) => {
+ *   return {
+ *     ...data,
+ *     player: {
+ *       ...data.player,
+ *       health: data.player.hp ?? 100, // Rename hp to health
+ *     }
+ *   };
+ * };
+ * ```
+ *
+ * @example
+ * Type-safe migration with specific field types:
+ * ```typescript
+ * const migrateFn: SaveMigrationFn<{ player?: { inventory: string[] } }> = (data) => {
+ *   const player = data.player || {};
+ *   return {
+ *     ...data,
+ *     player: {
+ *       ...player,
+ *       inventory: [], // TypeScript knows this should be string[]
+ *     }
+ *   };
+ * };
+ * ```
+ */
+export type SaveMigrationFn<T extends MigrationGameSaveState = GameSaveState> = (data: T) => T;
+/**
+ * Defines a migration from one game version to another.
+ *
+ * Migrations are registered by developers when they make breaking changes
+ * to the game save structure. The migration system will automatically
+ * chain migrations together to migrate saves from any old version to the
+ * current version.
+ *
+ * @template T - The shape of the game save state for this migration. Can be a partial
+ *               type if the migration only touches specific fields. Defaults to GameSaveState.
+ *               Using specific types provides better type safety and IDE autocomplete.
+ *
+ * @example
+ * Basic migration without specific types:
+ * ```typescript
+ * const migration: SaveMigration = {
+ *   from: "1.0.0",
+ *   to: "1.1.0",
+ *   description: "Added inventory system",
+ *   migrate: (save) => ({ ...save, inventory: [] })
+ * };
+ * ```
+ *
+ * @example
+ * Type-safe migration with specific field types:
+ * ```typescript
+ * const migration: SaveMigration<{ player?: { inventory: string[] } }> = {
+ *   from: "1.0.0",
+ *   to: "1.1.0",
+ *   description: "Added inventory system",
+ *   migrate: (save) => {
+ *     const player = save.player || {};
+ *     return {
+ *       ...save,
+ *       player: {
+ *         ...player,
+ *         inventory: [], // TypeScript validates the type
+ *       }
+ *     };
+ *   }
+ * };
+ * ```
+ */
+export interface SaveMigration<T extends MigrationGameSaveState = GameSaveState> {
+    /**
+     * The source version this migration starts from.
+     * Should be a valid semver string (e.g., "1.0.0", "1.2.3")
+     */
+    from: string;
+    /**
+     * The target version this migration migrates to.
+     * Should be a valid semver string (e.g., "1.1.0", "2.0.0")
+     */
+    to: string;
+    /**
+     * Human-readable description of what this migration does.
+     * Used for logging and debugging.
+     *
+     * @example "Added player inventory system"
+     * @example "Renamed 'hp' field to 'health'"
+     */
+    description: string;
+    /**
+     * The migration function that transforms the data.
+     * Should be pure and not mutate the input.
+     */
+    migrate: SaveMigrationFn<T>;
+}
+/**
+ * Result of running a migration chain.
+ *
+ * @template T - The type of the migrated data. Should match the target version's
+ *               save state structure. Defaults to GameSaveState.
+ *
+ * @example
+ * ```typescript
+ * const result: MigrationResult = runMigrations(oldSave, "1.0.0", "2.0.0");
+ * if (result.success) {
+ *   console.log("Migrated data:", result.data);
+ *   console.log("Applied migrations:", result.migrationsApplied);
+ * } else {
+ *   console.error("Migration failed:", result.error);
+ * }
+ * ```
+ *
+ * @example
+ * Type-safe migration result:
+ * ```typescript
+ * type NewSaveFormat = {
+ *   player: { stats: { health: number; mana: number } }
+ * } & Record<string, unknown>;
+ *
+ * const result: MigrationResult<NewSaveFormat> = runMigrations(oldSave, "1.0.0", "2.0.0");
+ * if (result.success && result.data) {
+ *   // TypeScript knows about the new structure
+ *   console.log(result.data.player.stats.health);
+ * }
+ * ```
+ */
+export interface MigrationResult<T extends GameSaveState = GameSaveState> {
+    /**
+     * Whether the migration was successful
+     */
+    success: boolean;
+    /**
+     * The migrated data (if successful)
+     */
+    data?: T;
+    /**
+     * Error message (if failed)
+     */
+    error?: string;
+    /**
+     * List of migrations that were applied, in order
+     */
+    migrationsApplied: Array<{
+        from: string;
+        to: string;
+        description: string;
+    }>;
+}
+/**
+ * Options for migration behavior
+ */
+export interface MigrationOptions {
+    /**
+     * Whether to throw an error if no migration path is found.
+     * If false, returns the original data unchanged.
+     * @default false
+     */
+    strict?: boolean;
+    /**
+     * Whether to log migration steps for debugging.
+     * @default true in dev mode, false in production
+     */
+    verbose?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map