@react-text-game/core 0.2.2 → 0.4.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"EXAMPLE.d.ts","sourceRoot":"","sources":["../../../src/saves/migrations/EXAMPLE.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA+KH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,SAYpC;AAMD;;;GAGG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6CrB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,kBAgCvC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG"}

package/dist/saves/migrations/EXAMPLE.js

@@ -0,0 +1,304 @@
+/**
+ * EXAMPLE: Save Migration System Usage
+ *
+ * This file demonstrates how to use the save migration system in a real game.
+ * It shows a complete migration history from version 1.0.0 to 3.0.0.
+ */
+import { registerMigration } from "./index";
+// ============================================================================
+// MIGRATION HISTORY
+// ============================================================================
+/**
+ * Version 1.0.0 → 1.1.0
+ * Added: Inventory system
+ *
+ * In version 1.1.0, we added an inventory system to the game.
+ * Players who saved in 1.0.0 don't have an inventory field,
+ * so we add an empty array as the default.
+ *
+ * NOTE: This migration uses the generic type parameter to specify
+ * the exact shape of the data it operates on. This provides:
+ * - Better type safety when accessing save.player.inventory
+ * - IDE autocomplete for the specific fields
+ * - Compile-time validation of the migration logic
+ */
+const migration_1_0_to_1_1 = {
+    from: "1.0.0",
+    to: "1.1.0",
+    description: "Added player inventory system",
+    migrate: (save) => {
+        const player = save.player || {};
+        return {
+            ...save,
+            player: {
+                ...player,
+                inventory: [],
+            },
+        };
+    },
+};
+/**
+ * Version 1.1.0 → 1.2.0
+ * Added: Quest tracking system
+ *
+ * We added a quest system with active and completed quests.
+ *
+ * NOTE: This migration does NOT use the generic type parameter,
+ * relying on the default GameSaveState type. This is fine for simple
+ * migrations where type safety is less critical. Use generics when:
+ * - You need type safety for complex nested structures
+ * - You want IDE autocomplete for specific fields
+ * - The migration logic is non-trivial and could benefit from type checking
+ */
+const migration_1_1_to_1_2 = {
+    from: "1.1.0",
+    to: "1.2.0",
+    description: "Added quest tracking system",
+    migrate: (save) => ({
+        ...save,
+        quests: {
+            active: [],
+            completed: [],
+        },
+    }),
+};
+/**
+ * Version 1.2.0 → 2.0.0 (MAJOR VERSION)
+ * Changed: Renamed 'hp' to 'health', 'mp' to 'mana'
+ * Changed: Moved stats into a separate 'stats' object
+ *
+ * This is a breaking change that restructures how player stats are stored.
+ */
+const migration_1_2_to_2_0 = {
+    from: "1.2.0",
+    to: "2.0.0",
+    description: "Restructured player stats: renamed hp→health, mp→mana, moved to stats object",
+    migrate: (save) => {
+        const player = save.player;
+        return {
+            ...save,
+            player: {
+                name: player.name,
+                level: player.level ?? 1,
+                experience: player.experience ?? 0,
+                inventory: player.inventory ?? [],
+                stats: {
+                    health: player.hp ?? 100,
+                    mana: player.mp ?? 50,
+                    maxHealth: player.maxHp ?? 100,
+                    maxMana: player.maxMp ?? 50,
+                    strength: player.strength ?? 10,
+                    intelligence: player.intelligence ?? 10,
+                    agility: player.agility ?? 10,
+                },
+            },
+        };
+    },
+};
+/**
+ * Version 2.0.0 → 2.1.0
+ * Added: Skills system
+ * Added: Player location tracking
+ */
+const migration_2_0_to_2_1 = {
+    from: "2.0.0",
+    to: "2.1.0",
+    description: "Added skills system and location tracking",
+    migrate: (save) => {
+        const player = (save.player || {});
+        return {
+            ...save,
+            player: {
+                ...player,
+                skills: {
+                    combat: 1,
+                    magic: 1,
+                    crafting: 1,
+                },
+                location: {
+                    passageId: "start",
+                    zone: "village",
+                },
+            },
+        };
+    },
+};
+/**
+ * Version 2.1.0 → 3.0.0 (MAJOR VERSION)
+ * Changed: Completely redesigned inventory system
+ * - Old: Array of item names
+ * - New: Array of item objects with id, quantity, metadata
+ *
+ * This migration converts the old simple inventory to the new detailed format.
+ */
+const migration_2_1_to_3_0 = {
+    from: "2.1.0",
+    to: "3.0.0",
+    description: "Redesigned inventory to use item objects instead of strings",
+    migrate: (save) => {
+        const player = save.player;
+        const oldInventory = (player.inventory || []);
+        // Count duplicate items
+        const itemCounts = new Map();
+        for (const itemName of oldInventory) {
+            itemCounts.set(itemName, (itemCounts.get(itemName) || 0) + 1);
+        }
+        // Convert to new format
+        const newInventory = Array.from(itemCounts.entries()).map(([name, quantity], index) => ({
+            id: `item_${index}`,
+            name,
+            quantity,
+            metadata: {},
+        }));
+        return {
+            ...save,
+            player: {
+                ...player,
+                inventory: newInventory,
+            },
+        };
+    },
+};
+// ============================================================================
+// MIGRATION REGISTRATION
+// ============================================================================
+/**
+ * Call this function during game initialization to register all migrations.
+ *
+ * @example
+ * ```typescript
+ * import { Game } from '@react-text-game/core';
+ * import { registerAllMigrations } from './migrations';
+ *
+ * async function initGame() {
+ *   await Game.init({ gameVersion: "3.0.0", ... });
+ *   registerAllMigrations();
+ * }
+ * ```
+ */
+export function registerAllMigrations() {
+    // Register in chronological order for clarity
+    // The order doesn't actually matter - the system uses BFS to find the path
+    registerMigration(migration_1_0_to_1_1);
+    registerMigration(migration_1_1_to_1_2);
+    registerMigration(migration_1_2_to_2_0);
+    registerMigration(migration_2_0_to_2_1);
+    registerMigration(migration_2_1_to_3_0);
+    console.log("✓ Registered 5 save migrations covering versions 1.0.0 → 3.0.0");
+}
+// ============================================================================
+// TESTING MIGRATIONS
+// ============================================================================
+/**
+ * Example test data for each version.
+ * Use these to test your migrations.
+ */
+export const testSaves = {
+    "1.0.0": {
+        player: {
+            name: "Hero",
+            hp: 80,
+            mp: 30,
+            maxHp: 100,
+            maxMp: 50,
+            level: 5,
+            experience: 1200,
+        },
+    },
+    "1.1.0": {
+        player: {
+            name: "Hero",
+            hp: 80,
+            mp: 30,
+            maxHp: 100,
+            maxMp: 50,
+            level: 5,
+            experience: 1200,
+            inventory: ["sword", "potion", "potion"],
+        },
+    },
+    "2.0.0": {
+        player: {
+            name: "Hero",
+            level: 5,
+            experience: 1200,
+            inventory: ["sword", "potion", "potion"],
+            stats: {
+                health: 80,
+                mana: 30,
+                maxHealth: 100,
+                maxMana: 50,
+                strength: 12,
+                intelligence: 8,
+                agility: 10,
+            },
+        },
+        quests: {
+            active: ["main_quest_1"],
+            completed: ["tutorial"],
+        },
+    },
+};
+/**
+ * Example test function to verify migrations work correctly.
+ *
+ * @example
+ * ```typescript
+ * import { testMigrationChain } from './migrations/example';
+ *
+ * // In your test file or dev console
+ * testMigrationChain();
+ * ```
+ */
+export async function testMigrationChain() {
+    const { runMigrations } = await import("./runner");
+    console.group("Testing Save Migration Chain");
+    // Test 1.0.0 → 3.0.0 (full chain)
+    console.log("\nTest 1: Migrating from 1.0.0 to 3.0.0");
+    const result1 = runMigrations(testSaves["1.0.0"], "1.0.0", "3.0.0", {
+        verbose: true,
+    });
+    console.log(result1.success ? "✓ Success" : "✗ Failed:", result1.error || result1.data);
+    // Test 1.1.0 → 3.0.0 (partial chain)
+    console.log("\nTest 2: Migrating from 1.1.0 to 3.0.0");
+    const result2 = runMigrations(testSaves["1.1.0"], "1.1.0", "3.0.0");
+    console.log(result2.success ? "✓ Success" : "✗ Failed:", result2.error || result2.data);
+    // Test 2.0.0 → 3.0.0 (single migration)
+    console.log("\nTest 3: Migrating from 2.0.0 to 3.0.0");
+    const result3 = runMigrations(testSaves["2.0.0"], "2.0.0", "3.0.0");
+    console.log(result3.success ? "✓ Success" : "✗ Failed:", result3.error || result3.data);
+    console.groupEnd();
+}
+// ============================================================================
+// USAGE IN YOUR GAME
+// ============================================================================
+/**
+ * How to integrate this into your game:
+ *
+ * 1. Create a migrations file (like this one) in your game
+ * 2. Define migration functions for each version change
+ * 3. Call registerAllMigrations() after Game.init()
+ * 4. Migrations will automatically apply when players load old saves
+ *
+ * Example:
+ *
+ * ```typescript
+ * // src/index.tsx
+ * import { Game } from '@react-text-game/core';
+ * import { registerAllMigrations } from './game/migrations';
+ *
+ * async function init() {
+ *   await Game.init({
+ *     gameName: "My Adventure",
+ *     gameVersion: "3.0.0",
+ *     isDevMode: import.meta.env.DEV
+ *   });
+ *
+ *   registerAllMigrations();
+ *
+ *   // Dev mode will validate your migration chain
+ *   // and warn if there are any issues
+ * }
+ * ```
+ */
+//# sourceMappingURL=EXAMPLE.js.map

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

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

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

@@ -0,0 +1,41 @@
+/**
+ * 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";
+export type { MigrationOptions, MigrationResult, SaveMigration, SaveMigrationFn, } from "./types";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","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;AAClE,YAAY,EACR,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,eAAe,GAClB,MAAM,SAAS,CAAC"}

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":"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"}