@platforma-sdk/model 1.54.10 → 1.55.0

package/dist/block_migrations.js

@@ -1,39 +1,3 @@
-import { tryRegisterCallback } from './internal.js';
-import { createBlockStorage } from './block_storage.js';
-
-/**
- * Helper to define version keys with literal type inference and runtime validation.
- * - Validates that all version values are unique
- * - Validates that no version value is empty
- * - Eliminates need for `as const` assertion
- *
- * @throws Error if duplicate or empty version values are found
- *
- * @example
- * const Version = defineDataVersions({
- *   Initial: 'v1',
- *   AddedLabels: 'v2',
- * });
- *
- * type VersionedData = {
- *   [Version.Initial]: DataV1;
- *   [Version.AddedLabels]: DataV2;
- * };
- */
-function defineDataVersions(versions) {
-    const values = Object.values(versions);
-    const keys = Object.keys(versions);
-    const emptyKeys = keys.filter((key) => versions[key] === "");
-    if (emptyKeys.length > 0) {
-        throw new Error(`Version values must be non-empty strings (empty: ${emptyKeys.join(", ")})`);
-    }
-    const unique = new Set(values);
-    if (unique.size !== values.length) {
-        const duplicates = values.filter((v, i) => values.indexOf(v) !== i);
-        throw new Error(`Duplicate version values: ${[...new Set(duplicates)].join(", ")}`);
-    }
-    return versions;
-}
 /** Create a DataVersioned wrapper with correct shape */
 function makeDataVersioned(version, data) {
     return { version, data };
@@ -66,186 +30,260 @@ const defaultRecover = (version, _data) => {
 /** Symbol for internal builder creation method */
 const FROM_BUILDER = Symbol("fromBuilder");
 /**
- * Final builder state after recover() is called.
- * Only allows calling create() to finalize the DataModel.
+ * Abstract base for both migration chain types.
+ * Holds shared state, buildStep() helper, and init().
+ * migrate() cannot be shared due to a TypeScript limitation: when the base class
+ * migrate() return type is abstract, subclasses cannot narrow it without losing type safety.
+ * Each subclass therefore owns its migrate() with the correct concrete return type.
  *
- * @typeParam VersionedData - Map of version keys to their data types
- * @typeParam CurrentVersion - The current (final) version in the chain
  * @internal
  */
-class DataModelBuilderWithRecover {
+class MigrationChainBase {
     versionChain;
     migrationSteps;
-    recoverFn;
-    /** @internal */
-    constructor({ versionChain, steps, recoverFn, }) {
-        this.versionChain = versionChain;
-        this.migrationSteps = steps;
-        this.recoverFn = recoverFn;
+    constructor(state) {
+        this.versionChain = state.versionChain;
+        this.migrationSteps = state.steps;
+    }
+    /** Appends a migration step and returns the new versionChain and steps arrays. */
+    buildStep(nextVersion, fn) {
+        if (this.versionChain.includes(nextVersion)) {
+            throw new Error(`Duplicate version '${nextVersion}' in migration chain`);
+        }
+        const fromVersion = this.versionChain[this.versionChain.length - 1];
+        const step = {
+            fromVersion,
+            toVersion: nextVersion,
+            migrate: fn,
+        };
+        return {
+            versionChain: [...this.versionChain, nextVersion],
+            steps: [...this.migrationSteps, step],
+        };
+    }
+    /** Returns recover-specific fields for DataModel construction. Overridden by WithRecover. */
+    recoverState() {
+        return {};
     }
     /**
      * Finalize the DataModel with initial data factory.
      *
-     * The initial data factory is called when creating new blocks or when
-     * migration/recovery fails and data must be reset.
-     *
-     * @param initialData - Factory function returning initial state (must exactly match CurrentVersion's data type)
+     * @param initialData - Factory function returning the initial state
      * @returns Finalized DataModel instance
-     *
-     * @example
-     * .init(() => ({ numbers: [], labels: [], description: '' }))
      */
-    init(initialData, 
-    // Compile-time check: S must have exactly the same keys as VersionedData[CurrentVersion]
-    ..._noExtraKeys) {
+    init(initialData) {
         return DataModel[FROM_BUILDER]({
             versionChain: this.versionChain,
             steps: this.migrationSteps,
             initialDataFn: initialData,
-            recoverFn: this.recoverFn,
+            ...this.recoverState(),
         });
     }
 }
 /**
- * Internal builder for constructing DataModel with type-safe migration chains.
+ * Migration chain after recover() or upgradeLegacy() has been called.
+ * Further migrate() calls are allowed; recover() and upgradeLegacy() are not
+ * (enforced by type — no such methods on this class).
  *
- * Tracks the current version through the generic type system, ensuring:
- * - Migration functions receive correctly typed input
- * - Migration functions must return the correct output type
- * - Version keys must exist in the VersionedData map
- * - All versions must be covered before calling init()
+ * @typeParam Current - Data type at the current point in the chain
+ * @internal
+ */
+class DataModelMigrationChainWithRecover extends MigrationChainBase {
+    recoverFn;
+    recoverFromIndex;
+    upgradeLegacyFn;
+    /** @internal */
+    constructor(state) {
+        super(state);
+        this.recoverFn = state.recoverFn;
+        this.recoverFromIndex = state.recoverFromIndex;
+        this.upgradeLegacyFn = state.upgradeLegacyFn;
+    }
+    recoverState() {
+        return {
+            recoverFn: this.recoverFn,
+            recoverFromIndex: this.recoverFromIndex,
+            upgradeLegacyFn: this.upgradeLegacyFn,
+        };
+    }
+    /**
+     * Add a migration step. Same semantics as on the base chain.
+     * recover() and upgradeLegacy() are not available — one has already been called.
+     */
+    migrate(nextVersion, fn) {
+        const { versionChain, steps } = this.buildStep(nextVersion, fn);
+        return new DataModelMigrationChainWithRecover({
+            versionChain,
+            steps,
+            recoverFn: this.recoverFn,
+            recoverFromIndex: this.recoverFromIndex,
+            upgradeLegacyFn: this.upgradeLegacyFn,
+        });
+    }
+}
+/**
+ * Migration chain builder.
+ * Each migrate() call advances the current data type. recover() can be called once
+ * at any point — it removes itself from the returned chain so it cannot be called again.
+ * Duplicate version keys throw at runtime.
  *
- * @typeParam VersionedData - Map of version keys to their data types
- * @typeParam CurrentVersion - The current version in the migration chain
- * @typeParam RemainingVersions - Versions not yet covered by migrations
+ * @typeParam Current - Data type at the current point in the migration chain
  * @internal
  */
-class DataModelMigrationChain {
-    versionChain;
-    migrationSteps;
+class DataModelMigrationChain extends MigrationChainBase {
     /** @internal */
     constructor({ versionChain, steps = [], }) {
-        this.versionChain = versionChain;
-        this.migrationSteps = steps;
+        super({ versionChain, steps });
     }
     /**
-     * Add a migration step to transform data from current version to next version.
-     *
-     * Migration functions:
-     * - Receive data typed as the current version's data type (readonly)
-     * - Must return data matching the target version's data type
-     * - Should be pure functions (no side effects)
-     * - May throw errors (will result in data reset with warning)
+     * Add a migration step transforming data from the current version to the next.
      *
-     * @typeParam NextVersion - The target version key (must be in RemainingVersions)
-     * @param nextVersion - The version key to migrate to
-     * @param fn - Migration function transforming current data to next version
-     * @returns Builder with updated current version
+     * @typeParam Next - Data type of the next version
+     * @param nextVersion - Version key to migrate to (must be unique in the chain)
+     * @param fn - Migration function
+     * @returns Builder with the next version as current
      *
      * @example
-     * .migrate(Version.V2, (data) => ({ ...data, labels: [] }))
+     * .migrate<BlockDataV2>("v2", (v1) => ({ ...v1, labels: [] }))
      */
     migrate(nextVersion, fn) {
-        if (this.versionChain.includes(nextVersion)) {
-            throw new Error(`Duplicate version '${nextVersion}' in migration chain`);
-        }
-        const fromVersion = this.versionChain[this.versionChain.length - 1];
-        const step = {
-            fromVersion,
-            toVersion: nextVersion,
-            migrate: fn,
-        };
-        return new DataModelMigrationChain({
-            versionChain: [...this.versionChain, nextVersion],
-            steps: [...this.migrationSteps, step],
-        });
+        const { versionChain, steps } = this.buildStep(nextVersion, fn);
+        return new DataModelMigrationChain({ versionChain, steps });
     }
     /**
      * Set a recovery handler for unknown or legacy versions.
      *
      * The recover function is called when data has a version not in the migration chain.
-     * It should either:
-     * - Transform the data to the current version's format and return it
-     * - Call `defaultRecover(version, data)` to signal unrecoverable data
+     * It must return data of the type at this point in the chain (Current). Any migrate()
+     * steps added after recover() will then run on the recovered data.
      *
-     * Can only be called once. After calling, only `init()` is available.
+     * Can only be called once — the returned chain has no recover() method.
+     * Mutually exclusive with upgradeLegacy().
      *
-     * @param fn - Recovery function that transforms unknown data or throws
-     * @returns Builder with only init() method available
+     * @param fn - Recovery function returning Current (the type at this chain position)
+     * @returns Builder with migrate() and init() but without recover() or upgradeLegacy()
      *
      * @example
-     * .recover((version, data) => {
-     *   if (version === 'legacy' && isLegacyFormat(data)) {
-     *     return transformLegacy(data);
-     *   }
-     *   return defaultRecover(version, data);
-     * })
+     * // Recover between migrations — recovered data goes through v3 migration
+     * new DataModelBuilder<V1>("v1")
+     *   .migrate<V2>("v2", (v1) => ({ ...v1, label: "" }))
+     *   .recover((version, data) => {
+     *     if (version === 'legacy') return transformLegacy(data); // returns V2
+     *     return defaultRecover(version, data);
+     *   })
+     *   .migrate<V3>("v3", (v2) => ({ ...v2, description: "" }))
+     *   .init(() => ({ count: 0, label: "", description: "" }));
      */
     recover(fn) {
-        return new DataModelBuilderWithRecover({
-            versionChain: [...this.versionChain],
-            steps: [...this.migrationSteps],
+        return new DataModelMigrationChainWithRecover({
+            versionChain: this.versionChain,
+            steps: this.migrationSteps,
             recoverFn: fn,
+            recoverFromIndex: this.migrationSteps.length,
         });
     }
     /**
-     * Finalize the DataModel with initial data factory.
+     * Handle legacy V1 model state ({ args, uiState }) when upgrading a block from
+     * BlockModel V1 to BlockModelV3.
      *
-     * Can only be called when all versions in VersionedData have been covered
-     * by the migration chain (RemainingVersions is empty).
+     * When a V1 block is upgraded, its stored state `{ args, uiState }` arrives at the
+     * initial version (DATA_MODEL_DEFAULT_VERSION) in the migration chain. This method
+     * detects the legacy shape and transforms it to the current chain type using the
+     * provided typed callback. Non-legacy data passes through unchanged.
      *
-     * The initial data factory is called when creating new blocks or when
-     * migration/recovery fails and data must be reset.
+     * Should be called right after `.from()` (before any `.migrate()` calls), since legacy
+     * data always arrives at the initial version. Any `.migrate()` steps added after
+     * `upgradeLegacy()` will run on the transformed result.
      *
-     * @param initialData - Factory function returning initial state (must exactly match CurrentVersion's data type)
-     * @returns Finalized DataModel instance
+     * Can only be called once — the returned chain has no upgradeLegacy() method.
+     * Mutually exclusive with recover().
+     *
+     * @typeParam Args - Type of the legacy block args
+     * @typeParam UiState - Type of the legacy block uiState
+     * @param fn - Typed transform from { args, uiState } to Current
+     * @returns Builder with migrate() and init() but without recover() or upgradeLegacy()
      *
      * @example
-     * .init(() => ({ numbers: [], labels: [], description: '' }))
+     * type OldArgs = { inputFile: string; threshold: number };
+     * type OldUiState = { selectedTab: string };
+     * type BlockData = { inputFile: string; threshold: number; selectedTab: string };
+     *
+     * const dataModel = new DataModelBuilder()
+     *   .from<BlockData>(DATA_MODEL_DEFAULT_VERSION)
+     *   .upgradeLegacy<OldArgs, OldUiState>(({ args, uiState }) => ({
+     *     inputFile: args.inputFile,
+     *     threshold: args.threshold,
+     *     selectedTab: uiState.selectedTab,
+     *   }))
+     *   .init(() => ({ inputFile: '', threshold: 0, selectedTab: 'main' }));
      */
-    init(initialData, 
-    // Compile-time check: S must have exactly the same keys as VersionedData[CurrentVersion]
-    ..._noExtraKeys) {
-        return DataModel[FROM_BUILDER]({
+    upgradeLegacy(fn) {
+        const wrappedFn = (data) => {
+            if (data !== null && typeof data === "object" && "args" in data) {
+                return fn(data);
+            }
+            return data;
+        };
+        return new DataModelMigrationChainWithRecover({
             versionChain: this.versionChain,
             steps: this.migrationSteps,
-            initialDataFn: initialData,
+            upgradeLegacyFn: wrappedFn,
         });
     }
 }
 /**
  * Builder entry point for creating DataModel with type-safe migrations.
  *
- * @typeParam VersionedData - Map of version keys to their data types
+ * @example
+ * // Simple (no migrations):
+ * const dataModel = new DataModelBuilder()
+ *   .from<BlockData>(DATA_MODEL_DEFAULT_VERSION)
+ *   .init(() => ({ numbers: [] }));
+ *
+ * @example
+ * // With migrations:
+ * const dataModel = new DataModelBuilder()
+ *   .from<BlockDataV1>(DATA_MODEL_DEFAULT_VERSION)
+ *   .migrate<BlockDataV2>("v2", (v1) => ({ ...v1, labels: [] }))
+ *   .migrate<BlockDataV3>("v3", (v2) => ({ ...v2, description: '' }))
+ *   .init(() => ({ numbers: [], labels: [], description: '' }));
  *
  * @example
- * const Version = defineDataVersions({
- *   V1: 'v1',
- *   V2: 'v2',
- * });
+ * // With recover() between migrations — recovered data goes through remaining migrations:
+ * const dataModelChain = new DataModelBuilder()
+ *   .from<BlockDataV1>(DATA_MODEL_DEFAULT_VERSION)
+ *   .migrate<BlockDataV2>("v2", (v1) => ({ ...v1, labels: [] }));
  *
- * type VersionedData = {
- *   [Version.V1]: { count: number };
- *   [Version.V2]: { count: number; label: string };
- * };
+ * // recover() placed before the v3 migration: recovered data goes through v3
+ * const dataModel = dataModelChain
+ *   .recover((version, data) => {
+ *     if (version === 'legacy' && isLegacyData(data)) return transformLegacy(data); // returns V2
+ *     return defaultRecover(version, data);
+ *   })
+ *   .migrate<BlockDataV3>("v3", (v2) => ({ ...v2, description: '' }))
+ *   .init(() => ({ numbers: [], labels: [], description: '' }));
  *
- * const dataModel = new DataModelBuilder<VersionedData>()
- *   .from(Version.V1)
- *   .migrate(Version.V2, (data) => ({ ...data, label: '' }))
- *   .init(() => ({ count: 0, label: '' }));
+ * @example
+ * // With upgradeLegacy() — typed upgrade from BlockModel V1 state:
+ * type OldArgs = { inputFile: string };
+ * type OldUiState = { selectedTab: string };
+ * type BlockData = { inputFile: string; selectedTab: string };
+ *
+ * const dataModel = new DataModelBuilder()
+ *   .from<BlockData>(DATA_MODEL_DEFAULT_VERSION)
+ *   .upgradeLegacy<OldArgs, OldUiState>(({ args, uiState }) => ({
+ *     inputFile: args.inputFile,
+ *     selectedTab: uiState.selectedTab,
+ *   }))
+ *   .init(() => ({ inputFile: '', selectedTab: 'main' }));
  */
 class DataModelBuilder {
     /**
-     * Start a migration chain from an initial version.
+     * Start the migration chain with the given initial data type and version key.
      *
-     * @typeParam InitialVersion - The starting version key (inferred from argument)
-     * @param initialVersion - The version key to start from
-     * @returns Migration chain builder for adding migrations
-     *
-     * @example
-     * new DataModelBuilder<VersionedData>()
-     *   .from(Version.V1)
-     *   .migrate(Version.V2, (data) => ({ ...data, newField: '' }))
+     * @typeParam T - Data type for the initial version
+     * @param initialVersion - Version key string (e.g. DATA_MODEL_DEFAULT_VERSION or "v1")
+     * @returns Migration chain builder
      */
     from(initialVersion) {
         return new DataModelMigrationChain({ versionChain: [initialVersion] });
@@ -255,56 +293,43 @@ class DataModelBuilder {
  * DataModel defines the block's data structure, initial values, and migrations.
  * Used by BlockModelV3 to manage data state.
  *
- * Use `new DataModelBuilder<VersionedData>()` to create a DataModel:
+ * Use `new DataModelBuilder()` to create a DataModel.
  *
- * **Simple (no migrations):**
  * @example
- * const Version = defineDataVersions({ V1: DATA_MODEL_DEFAULT_VERSION });
- * type VersionedData = { [Version.V1]: BlockData };
- *
- * const dataModel = new DataModelBuilder<VersionedData>()
- *   .from(Version.V1)
- *   .init(() => ({ numbers: [], labels: [] }));
- *
- * **With migrations:**
- * @example
- * const Version = defineDataVersions({
- *   V1: DATA_MODEL_DEFAULT_VERSION,
- *   V2: 'v2',
- *   V3: 'v3',
- * });
- *
- * type VersionedData = {
- *   [Version.V1]: { numbers: number[] };
- *   [Version.V2]: { numbers: number[]; labels: string[] };
- *   [Version.V3]: { numbers: number[]; labels: string[]; description: string };
- * };
- *
- * const dataModel = new DataModelBuilder<VersionedData>()
- *   .from(Version.V1)
- *   .migrate(Version.V2, (data) => ({ ...data, labels: [] }))
- *   .migrate(Version.V3, (data) => ({ ...data, description: '' }))
+ * // With recover() between migrations:
+ * // Recovered data (V2) goes through the v2→v3 migration automatically.
+ * const dataModel = new DataModelBuilder()
+ *   .from<V1>(DATA_MODEL_DEFAULT_VERSION)
+ *   .migrate<V2>("v2", (v1) => ({ ...v1, label: "" }))
  *   .recover((version, data) => {
- *     if (version === 'legacy' && typeof data === 'object' && data !== null && 'numbers' in data) {
- *       return { numbers: (data as { numbers: number[] }).numbers, labels: [], description: '' };
- *     }
+ *     if (version === "legacy") return transformLegacy(data); // returns V2
  *     return defaultRecover(version, data);
  *   })
- *   .init(() => ({ numbers: [], labels: [], description: '' }));
+ *   .migrate<V3>("v3", (v2) => ({ ...v2, description: "" }))
+ *   .init(() => ({ count: 0, label: "", description: "" }));
  */
 class DataModel {
-    versionChain;
+    /** Latest version key — O(1) access for the common "already current" check. */
+    latestVersion;
+    /** Maps each known version key to the index of the first step to run from it. O(1) lookup. */
+    stepsByFromVersion;
     steps;
     initialDataFn;
     recoverFn;
-    constructor({ versionChain, steps, initialDataFn, recoverFn = defaultRecover, }) {
+    recoverFromIndex;
+    /** Transforms legacy V1 model data at the initial version before running migrations. */
+    upgradeLegacyFn;
+    constructor({ versionChain, steps, initialDataFn, recoverFn = defaultRecover, recoverFromIndex, upgradeLegacyFn, }) {
         if (versionChain.length === 0) {
             throw new Error("DataModel requires at least one version key");
         }
-        this.versionChain = versionChain;
+        this.latestVersion = versionChain[versionChain.length - 1];
+        this.stepsByFromVersion = new Map(versionChain.map((v, i) => [v, i]));
         this.steps = steps;
         this.initialDataFn = initialDataFn;
         this.recoverFn = recoverFn;
+        this.recoverFromIndex = recoverFromIndex ?? steps.length;
+        this.upgradeLegacyFn = upgradeLegacyFn;
     }
     /**
      * Internal method for creating DataModel from builder.
@@ -318,13 +343,7 @@ class DataModel {
      * The latest (current) version key in the migration chain.
      */
     get version() {
-        return this.versionChain[this.versionChain.length - 1];
-    }
-    /**
-     * Number of migration steps defined.
-     */
-    get migrationCount() {
-        return this.steps.length;
+        return this.latestVersion;
     }
     /**
      * Get a fresh copy of the initial data.
@@ -337,11 +356,13 @@ class DataModel {
      * Used when creating new blocks or resetting to defaults.
      */
     getDefaultData() {
-        return makeDataVersioned(this.version, this.initialDataFn());
+        return makeDataVersioned(this.latestVersion, this.initialDataFn());
     }
     recoverFrom(data, version) {
+        // Step 1: call the recover function to get data at the recover point
+        let currentData;
         try {
-            return { version: this.version, data: this.recoverFn(version, data) };
+            currentData = this.recoverFn(version, data);
         }
         catch (error) {
             if (isDataUnrecoverableError(error)) {
@@ -353,13 +374,27 @@ class DataModel {
                 warning: `Recover failed for version '${version}': ${errorMessage}`,
             };
         }
+        // Step 2: run any migrations that were added after recover() in the chain
+        for (let i = this.recoverFromIndex; i < this.steps.length; i++) {
+            const step = this.steps[i];
+            try {
+                currentData = step.migrate(currentData);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                return {
+                    ...this.getDefaultData(),
+                    warning: `Migration ${step.fromVersion}→${step.toVersion} failed: ${errorMessage}`,
+                };
+            }
+        }
+        return { version: this.latestVersion, data: currentData };
     }
     /**
      * Migrate versioned data from any version to the latest.
      *
-     * - If data is already at latest version, returns as-is
-     * - If version is in chain, applies needed migrations
-     * - If version is unknown, calls recover function
+     * - If version is in chain, applies needed migrations (O(1) lookup)
+     * - If version is unknown, calls recover function then runs remaining migrations
      * - If migration/recovery fails, returns default data with warning
      *
      * @param versioned - Data with version tag
@@ -367,14 +402,27 @@ class DataModel {
      */
     migrate(versioned) {
         const { version: fromVersion, data } = versioned;
-        if (fromVersion === this.version) {
-            return { version: this.version, data: data };
+        if (fromVersion === this.latestVersion) {
+            return { version: this.latestVersion, data: data };
         }
-        const startIndex = this.versionChain.indexOf(fromVersion);
-        if (startIndex < 0) {
+        const startIndex = this.stepsByFromVersion.get(fromVersion);
+        if (startIndex === undefined) {
             return this.recoverFrom(data, fromVersion);
         }
         let currentData = data;
+        // Legacy V1 upgrade: detect and transform { args, uiState } at the initial version
+        if (startIndex === 0 && this.upgradeLegacyFn) {
+            try {
+                currentData = this.upgradeLegacyFn(currentData);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                return {
+                    ...this.getDefaultData(),
+                    warning: `Legacy upgrade failed: ${errorMessage}`,
+                };
+            }
+        }
         for (let i = startIndex; i < this.steps.length; i++) {
             const step = this.steps[i];
             try {
@@ -388,24 +436,9 @@ class DataModel {
                 };
             }
         }
-        return { version: this.version, data: currentData };
-    }
-    /**
-     * Register callbacks for use in the VM.
-     * Called by BlockModelV3.create() to set up internal callbacks.
-     *
-     * @internal
-     */
-    registerCallbacks() {
-        tryRegisterCallback("__pl_data_initial", () => this.initialDataFn());
-        tryRegisterCallback("__pl_data_upgrade", (versioned) => this.migrate(versioned));
-        tryRegisterCallback("__pl_storage_initial", () => {
-            const { version, data } = this.getDefaultData();
-            const storage = createBlockStorage(data, version);
-            return JSON.stringify(storage);
-        });
+        return { version: this.latestVersion, data: currentData };
     }
 }
 
-export { DataModel, DataModelBuilder, DataUnrecoverableError, defaultRecover, defineDataVersions, isDataUnrecoverableError, makeDataVersioned };
+export { DataModel, DataModelBuilder, DataUnrecoverableError, defaultRecover, isDataUnrecoverableError, makeDataVersioned };
 //# sourceMappingURL=block_migrations.js.map