@platforma-sdk/model 1.53.1 → 1.53.2

package/dist/block_migrations.js

@@ -4,9 +4,10 @@ import { DATA_MODEL_DEFAULT_VERSION, createBlockStorage } from './block_storage.
 /**
  * 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 version values are found
+ * @throws Error if duplicate or empty version values are found
  *
  * @example
  * const Version = defineDataVersions({
@@ -21,7 +22,8 @@ import { DATA_MODEL_DEFAULT_VERSION, createBlockStorage } from './block_storage.
  */
 function defineDataVersions(versions) {
     const values = Object.values(versions);
-    const emptyKeys = Object.keys(versions).filter((key) => versions[key] === '');
+    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(', ')})`);
     }
@@ -46,54 +48,220 @@ class DataUnrecoverableError extends Error {
 function isDataUnrecoverableError(error) {
     return error instanceof Error && error.name === 'DataUnrecoverableError';
 }
-/** Default recover function for unknown versions */
+/**
+ * Default recover function for unknown versions.
+ * Use as fallback at the end of custom recover functions.
+ *
+ * @example
+ * .recover((version, data) => {
+ *   if (version === 'legacy') {
+ *     return transformLegacyData(data);
+ *   }
+ *   return defaultRecover(version, data);
+ * })
+ */
 const defaultRecover = (version, _data) => {
     throw new DataUnrecoverableError(version);
 };
-/** Internal builder for chaining migrations */
-class DataModelBuilder {
+/** 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.
+ *
+ * @typeParam VersionedData - Map of version keys to their data types
+ * @typeParam CurrentVersion - The current (final) version in the chain
+ * @internal
+ */
+class DataModelBuilderWithRecover {
     versionChain;
     migrationSteps;
     recoverFn;
-    constructor(versionChain, steps = [], recoverFn) {
+    /** @internal */
+    constructor({ versionChain, steps, recoverFn, }) {
         this.versionChain = versionChain;
         this.migrationSteps = steps;
         this.recoverFn = recoverFn;
     }
-    /** Start a migration chain from an initial version */
-    static from(initialVersion) {
-        return new DataModelBuilder([initialVersion]);
+    /**
+     * 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)
+     * @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) {
+        return DataModel[FROM_BUILDER]({
+            versionChain: this.versionChain,
+            steps: this.migrationSteps,
+            initialDataFn: initialData,
+            recoverFn: this.recoverFn,
+        });
+    }
+}
+/**
+ * Internal builder for constructing DataModel with type-safe migration chains.
+ *
+ * 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 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
+ * @internal
+ */
+class DataModelMigrationChain {
+    versionChain;
+    migrationSteps;
+    /** @internal */
+    constructor({ versionChain, steps = [], }) {
+        this.versionChain = versionChain;
+        this.migrationSteps = steps;
     }
-    /** Add a migration step to the target version */
+    /**
+     * 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)
+     *
+     * @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
+     *
+     * @example
+     * .migrate(Version.V2, (data) => ({ ...data, 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 DataModelBuilder([...this.versionChain, nextVersion], [...this.migrationSteps, step]);
+        return new DataModelMigrationChain({
+            versionChain: [...this.versionChain, nextVersion],
+            steps: [...this.migrationSteps, step],
+        });
     }
-    /** Set recovery handler for unknown or unsupported versions */
+    /**
+     * 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
+     *
+     * Can only be called once. After calling, only `init()` is available.
+     *
+     * @param fn - Recovery function that transforms unknown data or throws
+     * @returns Builder with only init() method available
+     *
+     * @example
+     * .recover((version, data) => {
+     *   if (version === 'legacy' && isLegacyFormat(data)) {
+     *     return transformLegacy(data);
+     *   }
+     *   return defaultRecover(version, data);
+     * })
+     */
     recover(fn) {
-        return new DataModelBuilder([...this.versionChain], [...this.migrationSteps], fn);
+        return new DataModelBuilderWithRecover({
+            versionChain: [...this.versionChain],
+            steps: [...this.migrationSteps],
+            recoverFn: fn,
+        });
+    }
+    /**
+     * Finalize the DataModel with initial data factory.
+     *
+     * Can only be called when all versions in VersionedData have been covered
+     * by the migration chain (RemainingVersions is empty).
+     *
+     * 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)
+     * @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) {
+        return DataModel[FROM_BUILDER]({
+            versionChain: this.versionChain,
+            steps: this.migrationSteps,
+            initialDataFn: initialData,
+        });
     }
-    /** Finalize with initial data, creating the DataModel */
-    create(initialData, ..._) {
-        return DataModel._fromBuilder(this.versionChain, this.migrationSteps, initialData, this.recoverFn);
+}
+/**
+ * Builder entry point for creating DataModel with type-safe migrations.
+ *
+ * @typeParam VersionedData - Map of version keys to their data types
+ *
+ * @example
+ * const Version = defineDataVersions({
+ *   V1: 'v1',
+ *   V2: 'v2',
+ * });
+ *
+ * type VersionedData = {
+ *   [Version.V1]: { count: number };
+ *   [Version.V2]: { count: number; label: string };
+ * };
+ *
+ * const dataModel = new DataModelBuilder<VersionedData>()
+ *   .from(Version.V1)
+ *   .migrate(Version.V2, (data) => ({ ...data, label: '' }))
+ *   .init(() => ({ count: 0, label: '' }));
+ */
+class DataModelBuilder {
+    /**
+     * Start a migration chain from an initial version.
+     *
+     * @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: '' }))
+     */
+    from(initialVersion) {
+        return new DataModelMigrationChain({ versionChain: [initialVersion] });
     }
 }
 /**
  * DataModel defines the block's data structure, initial values, and migrations.
  * Used by BlockModelV3 to manage data state.
  *
+ * Two ways to create a DataModel:
+ *
+ * 1. **Simple (no migrations)** - Use `DataModel.create()`:
  * @example
- * // Simple data model (no migrations)
  * const dataModel = DataModel.create<BlockData>(() => ({
  *   numbers: [],
  *   labels: [],
  * }));
  *
- * // Data model with migrations
+ * 2. **With migrations** - Use `new DataModelBuilder<VersionedData>()`:
+ * @example
  * const Version = defineDataVersions({
  *   V1: 'v1',
  *   V2: 'v2',
@@ -106,8 +274,8 @@ class DataModelBuilder {
  *   [Version.V3]: { numbers: number[]; labels: string[]; description: string };
  * };
  *
- * const dataModel = DataModel
- *   .from<VersionedData>(Version.V1)
+ * const dataModel = new DataModelBuilder<VersionedData>()
+ *   .from(Version.V1)
  *   .migrate(Version.V2, (data) => ({ ...data, labels: [] }))
  *   .migrate(Version.V3, (data) => ({ ...data, description: '' }))
  *   .recover((version, data) => {
@@ -116,49 +284,76 @@ class DataModelBuilder {
  *     }
  *     return defaultRecover(version, data);
  *   })
- *   .create(() => ({ numbers: [], labels: [], description: '' }));
+ *   .init(() => ({ numbers: [], labels: [], description: '' }));
  */
 class DataModel {
     versionChain;
     steps;
     initialDataFn;
     recoverFn;
-    constructor(versionChain, steps, initialData, recover = defaultRecover) {
+    constructor({ versionChain, steps, initialDataFn, recoverFn = defaultRecover, }) {
         if (versionChain.length === 0) {
             throw new Error('DataModel requires at least one version key');
         }
         this.versionChain = versionChain;
         this.steps = steps;
-        this.initialDataFn = initialData;
-        this.recoverFn = recover;
-    }
-    /** Start a migration chain from an initial type */
-    static from(initialVersion) {
-        return DataModelBuilder.from(initialVersion);
+        this.initialDataFn = initialDataFn;
+        this.recoverFn = recoverFn;
     }
-    /** Create a data model with just initial data (no migrations) */
+    /**
+     * Create a DataModel with just initial data (no migrations).
+     *
+     * Use this for simple blocks that don't need version migrations.
+     * The version will be set to an internal default value.
+     *
+     * @typeParam S - The state type
+     * @param initialData - Factory function returning initial state
+     * @param version - Optional custom version key (defaults to internal version)
+     * @returns Finalized DataModel instance
+     *
+     * @example
+     * const dataModel = DataModel.create<BlockData>(() => ({
+     *   numbers: [],
+     *   labels: [],
+     * }));
+     */
     static create(initialData, version = DATA_MODEL_DEFAULT_VERSION) {
-        return new DataModel([version], [], initialData);
+        return new DataModel({
+            versionChain: [version],
+            steps: [],
+            initialDataFn: initialData,
+        });
     }
-    /** Create from builder (internal use) */
-    static _fromBuilder(versionChain, steps, initialData, recover) {
-        return new DataModel(versionChain, steps, initialData, recover);
+    /**
+     * Internal method for creating DataModel from builder.
+     * Uses Symbol key to prevent external access.
+     * @internal
+     */
+    static [FROM_BUILDER](state) {
+        return new DataModel(state);
     }
     /**
-     * Latest version key.
+     * The latest (current) version key in the migration chain.
      */
     get version() {
         return this.versionChain[this.versionChain.length - 1];
     }
-    /** Number of migration steps */
+    /**
+     * Number of migration steps defined.
+     */
     get migrationCount() {
         return this.steps.length;
     }
-    /** Get initial data */
+    /**
+     * Get a fresh copy of the initial data.
+     */
     initialData() {
         return this.initialDataFn();
     }
-    /** Get default data wrapped with current version */
+    /**
+     * Get initial data wrapped with current version.
+     * Used when creating new blocks or resetting to defaults.
+     */
     getDefaultData() {
         return makeDataVersioned(this.version, this.initialDataFn());
     }
@@ -179,8 +374,14 @@ class DataModel {
     }
     /**
      * Migrate versioned data from any version to the latest.
-     * Applies only the migrations needed (skips already-applied ones).
-     * If a migration fails, returns default data with a warning.
+     *
+     * - 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 migration/recovery fails, returns default data with warning
+     *
+     * @param versioned - Data with version tag
+     * @returns Migration result with data at latest version
      */
     migrate(versioned) {
         const { version: fromVersion, data } = versioned;
@@ -211,14 +412,11 @@ class DataModel {
      * Register callbacks for use in the VM.
      * Called by BlockModelV3.create() to set up internal callbacks.
      *
-     * All callbacks are prefixed with `__pl_` to indicate internal SDK use:
-     * - `__pl_data_initial`: returns initial data for new blocks
-     * - `__pl_data_migrate`: migrates versioned data from any version to latest
-     * - `__pl_storage_initial`: returns initial BlockStorage as JSON string
+     * @internal
      */
     registerCallbacks() {
         tryRegisterCallback('__pl_data_initial', () => this.initialDataFn());
-        tryRegisterCallback('__pl_data_migrate', (versioned) => this.migrate(versioned));
+        tryRegisterCallback('__pl_data_upgrade', (versioned) => this.migrate(versioned));
         tryRegisterCallback('__pl_storage_initial', () => {
             const { version, data } = this.getDefaultData();
             const storage = createBlockStorage(data, version);
@@ -227,5 +425,5 @@ class DataModel {
     }
 }
 
-export { DataModel, DataUnrecoverableError, defaultRecover, defineDataVersions, isDataUnrecoverableError, makeDataVersioned };
+export { DataModel, DataModelBuilder, DataUnrecoverableError, defaultRecover, defineDataVersions, isDataUnrecoverableError, makeDataVersioned };
 //# sourceMappingURL=block_migrations.js.map

package/dist/block_migrations.js.map

@@ -1 +1 @@
-{"version":3,"file":"block_migrations.js","sources":["../src/block_migrations.ts"],"sourcesContent":["import { tryRegisterCallback } from './internal';\nimport { createBlockStorage, DATA_MODEL_DEFAULT_VERSION } from './block_storage';\n\nexport type DataVersionKey = string;\nexport type DataVersionMap = Record<string, unknown>;\nexport type DataMigrateFn<From, To> = (prev: Readonly<From>) => To;\nexport type DataCreateFn<T> = () => T;\nexport type DataRecoverFn<T> = (version: DataVersionKey, data: unknown) => T;\n\n/**\n * Helper to define version keys with literal type inference and runtime validation.\n * - Validates that all version values are unique\n * - Eliminates need for `as const` assertion\n *\n * @throws Error if duplicate version values are found\n *\n * @example\n * const Version = defineDataVersions({\n *   Initial: 'v1',\n *   AddedLabels: 'v2',\n * });\n *\n * type VersionedData = {\n *   [Version.Initial]: DataV1;\n *   [Version.AddedLabels]: DataV2;\n * };\n */\nexport function defineDataVersions<const T extends Record<string, string>>(versions: T): T {\n  const values = Object.values(versions);\n  const emptyKeys = Object.keys(versions).filter((key) => versions[key] === '');\n  if (emptyKeys.length > 0) {\n    throw new Error(`Version values must be non-empty strings (empty: ${emptyKeys.join(', ')})`);\n  }\n  const unique = new Set(values);\n  if (unique.size !== values.length) {\n    const duplicates = values.filter((v, i) => values.indexOf(v) !== i);\n    throw new Error(`Duplicate version values: ${[...new Set(duplicates)].join(', ')}`);\n  }\n  return versions;\n}\n\n/** Versioned data wrapper for persistence */\nexport type DataVersioned<T> = {\n  version: DataVersionKey;\n  data: T;\n};\n\n/** Create a DataVersioned wrapper with correct shape */\nexport function makeDataVersioned<T>(version: DataVersionKey, data: T): DataVersioned<T> {\n  return { version, data };\n}\n\n/** Result of migration operation, may include warning if migration failed */\nexport type DataMigrationResult<T> = DataVersioned<T> & {\n  warning?: string;\n};\n\n/** Thrown by recover() to signal unrecoverable data. */\nexport class DataUnrecoverableError extends Error {\n  name = 'DataUnrecoverableError';\n  constructor(dataVersion: DataVersionKey) {\n    super(`Unknown version '${dataVersion}'`);\n  }\n}\n\nexport function isDataUnrecoverableError(error: unknown): error is DataUnrecoverableError {\n  return error instanceof Error && error.name === 'DataUnrecoverableError';\n}\n\ntype MigrationStep = {\n  fromVersion: DataVersionKey;\n  toVersion: DataVersionKey;\n  migrate: (data: unknown) => unknown;\n};\n\n/** Default recover function for unknown versions */\nexport const defaultRecover: DataRecoverFn<never> = (version, _data) => {\n  throw new DataUnrecoverableError(version);\n};\n\n/** Internal builder for chaining migrations */\nclass DataModelBuilder<\n  VersionedData extends DataVersionMap,\n  CurrentVersion extends keyof VersionedData & string,\n> {\n  private readonly versionChain: DataVersionKey[];\n  private readonly migrationSteps: MigrationStep[];\n  private readonly recoverFn?: DataRecoverFn<VersionedData[CurrentVersion]>;\n\n  private constructor(\n    versionChain: DataVersionKey[],\n    steps: MigrationStep[] = [],\n    recoverFn?: DataRecoverFn<VersionedData[CurrentVersion]>,\n  ) {\n    this.versionChain = versionChain;\n    this.migrationSteps = steps;\n    this.recoverFn = recoverFn;\n  }\n\n  /** Start a migration chain from an initial version */\n  static from<\n    VersionedData extends DataVersionMap,\n    InitialVersion extends keyof VersionedData & string = keyof VersionedData & string,\n  >(initialVersion: InitialVersion): DataModelBuilder<VersionedData, InitialVersion> {\n    return new DataModelBuilder<VersionedData, InitialVersion>([initialVersion]);\n  }\n\n  /** Add a migration step to the target version */\n  migrate<NextVersion extends keyof VersionedData & string>(\n    nextVersion: NextVersion,\n    fn: DataMigrateFn<VersionedData[CurrentVersion], VersionedData[NextVersion]>,\n  ): DataModelBuilder<VersionedData, NextVersion> {\n    if (this.versionChain.includes(nextVersion)) {\n      throw new Error(`Duplicate version '${nextVersion}' in migration chain`);\n    }\n    const fromVersion = this.versionChain[this.versionChain.length - 1];\n    const step: MigrationStep = { fromVersion, toVersion: nextVersion, migrate: fn as (data: unknown) => unknown };\n    return new DataModelBuilder<VersionedData, NextVersion>(\n      [...this.versionChain, nextVersion],\n      [...this.migrationSteps, step],\n    );\n  }\n\n  /** Set recovery handler for unknown or unsupported versions */\n  recover(\n    fn: DataRecoverFn<VersionedData[CurrentVersion]>,\n  ): DataModelBuilder<VersionedData, CurrentVersion> {\n    return new DataModelBuilder<VersionedData, CurrentVersion>(\n      [...this.versionChain],\n      [...this.migrationSteps],\n      fn,\n    );\n  }\n\n  /** Finalize with initial data, creating the DataModel */\n  create<S extends VersionedData[CurrentVersion]>(\n    initialData: DataCreateFn<S>,\n    ..._: [VersionedData[CurrentVersion]] extends [S] ? [] : [never]\n  ): DataModel<S> {\n    return DataModel._fromBuilder<S>(\n      this.versionChain,\n      this.migrationSteps,\n      initialData,\n      this.recoverFn as DataRecoverFn<S> | undefined,\n    );\n  }\n}\n\n/**\n * DataModel defines the block's data structure, initial values, and migrations.\n * Used by BlockModelV3 to manage data state.\n *\n * @example\n * // Simple data model (no migrations)\n * const dataModel = DataModel.create<BlockData>(() => ({\n *   numbers: [],\n *   labels: [],\n * }));\n *\n * // Data model with migrations\n * const Version = defineDataVersions({\n *   V1: 'v1',\n *   V2: 'v2',\n *   V3: 'v3',\n * });\n *\n * type VersionedData = {\n *   [Version.V1]: { numbers: number[] };\n *   [Version.V2]: { numbers: number[]; labels: string[] };\n *   [Version.V3]: { numbers: number[]; labels: string[]; description: string };\n * };\n *\n * const dataModel = DataModel\n *   .from<VersionedData>(Version.V1)\n *   .migrate(Version.V2, (data) => ({ ...data, labels: [] }))\n *   .migrate(Version.V3, (data) => ({ ...data, description: '' }))\n *   .recover((version, data) => {\n *     if (version === 'legacy' && typeof data === 'object' && data !== null && 'numbers' in data) {\n *       return { numbers: (data as { numbers: number[] }).numbers, labels: [], description: '' };\n *     }\n *     return defaultRecover(version, data);\n *   })\n *   .create(() => ({ numbers: [], labels: [], description: '' }));\n */\nexport class DataModel<State> {\n  private readonly versionChain: DataVersionKey[];\n  private readonly steps: MigrationStep[];\n  private readonly initialDataFn: () => State;\n  private readonly recoverFn: DataRecoverFn<State>;\n\n  private constructor(\n    versionChain: DataVersionKey[],\n    steps: MigrationStep[],\n    initialData: () => State,\n    recover: DataRecoverFn<State> = defaultRecover as DataRecoverFn<State>,\n  ) {\n    if (versionChain.length === 0) {\n      throw new Error('DataModel requires at least one version key');\n    }\n    this.versionChain = versionChain;\n    this.steps = steps;\n    this.initialDataFn = initialData;\n    this.recoverFn = recover;\n  }\n\n  /** Start a migration chain from an initial type */\n  static from<\n    VersionedData extends DataVersionMap,\n    InitialVersion extends keyof VersionedData & string = keyof VersionedData & string,\n  >(initialVersion: InitialVersion): DataModelBuilder<VersionedData, InitialVersion> {\n    return DataModelBuilder.from<VersionedData, InitialVersion>(initialVersion);\n  }\n\n  /** Create a data model with just initial data (no migrations) */\n  static create<S>(initialData: () => S, version: DataVersionKey = DATA_MODEL_DEFAULT_VERSION): DataModel<S> {\n    return new DataModel<S>([version], [], initialData);\n  }\n\n  /** Create from builder (internal use) */\n  static _fromBuilder<S>(\n    versionChain: DataVersionKey[],\n    steps: MigrationStep[],\n    initialData: () => S,\n    recover?: DataRecoverFn<S>,\n  ): DataModel<S> {\n    return new DataModel<S>(versionChain, steps, initialData, recover);\n  }\n\n  /**\n   * Latest version key.\n   */\n  get version(): DataVersionKey {\n    return this.versionChain[this.versionChain.length - 1];\n  }\n\n  /** Number of migration steps */\n  get migrationCount(): number {\n    return this.steps.length;\n  }\n\n  /** Get initial data */\n  initialData(): State {\n    return this.initialDataFn();\n  }\n\n  /** Get default data wrapped with current version */\n  getDefaultData(): DataVersioned<State> {\n    return makeDataVersioned(this.version, this.initialDataFn());\n  }\n\n  private recoverFrom(data: unknown, version: DataVersionKey): DataMigrationResult<State> {\n    try {\n      return { version: this.version, data: this.recoverFn(version, data) };\n    } catch (error) {\n      if (isDataUnrecoverableError(error)) {\n        return { ...this.getDefaultData(), warning: error.message };\n      }\n      const errorMessage = error instanceof Error ? error.message : String(error);\n      return {\n        ...this.getDefaultData(),\n        warning: `Recover failed for version '${version}': ${errorMessage}`,\n      };\n    }\n  }\n\n  /**\n   * Migrate versioned data from any version to the latest.\n   * Applies only the migrations needed (skips already-applied ones).\n   * If a migration fails, returns default data with a warning.\n   */\n  migrate(versioned: DataVersioned<unknown>): DataMigrationResult<State> {\n    const { version: fromVersion, data } = versioned;\n\n    if (fromVersion === this.version) {\n      return { version: this.version, data: data as State };\n    }\n\n    const startIndex = this.versionChain.indexOf(fromVersion);\n    if (startIndex < 0) {\n      return this.recoverFrom(data, fromVersion);\n    }\n\n    let currentData: unknown = data;\n    for (let i = startIndex; i < this.steps.length; i++) {\n      const step = this.steps[i];\n      try {\n        currentData = step.migrate(currentData);\n      } catch (error) {\n        const errorMessage = error instanceof Error ? error.message : String(error);\n        return {\n          ...this.getDefaultData(),\n          warning: `Migration ${step.fromVersion}→${step.toVersion} failed: ${errorMessage}`,\n        };\n      }\n    }\n\n    return { version: this.version, data: currentData as State };\n  }\n\n  /**\n   * Register callbacks for use in the VM.\n   * Called by BlockModelV3.create() to set up internal callbacks.\n   *\n   * All callbacks are prefixed with `__pl_` to indicate internal SDK use:\n   * - `__pl_data_initial`: returns initial data for new blocks\n   * - `__pl_data_migrate`: migrates versioned data from any version to latest\n   * - `__pl_storage_initial`: returns initial BlockStorage as JSON string\n   */\n  registerCallbacks(): void {\n    tryRegisterCallback('__pl_data_initial', () => this.initialDataFn());\n    tryRegisterCallback('__pl_data_migrate', (versioned: DataVersioned<unknown>) => this.migrate(versioned));\n    tryRegisterCallback('__pl_storage_initial', () => {\n      const { version, data } = this.getDefaultData();\n      const storage = createBlockStorage(data, version);\n      return JSON.stringify(storage);\n    });\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"block_migrations.js","sources":["../src/block_migrations.ts"],"sourcesContent":["import { tryRegisterCallback } from './internal';\nimport { createBlockStorage, DATA_MODEL_DEFAULT_VERSION } from './block_storage';\n\nexport type DataVersionKey = string;\nexport type DataVersionMap = Record<string, unknown>;\nexport type DataMigrateFn<From, To> = (prev: Readonly<From>) => To;\nexport type DataCreateFn<T> = () => T;\nexport type DataRecoverFn<T> = (version: DataVersionKey, data: unknown) => T;\n\n/**\n * Helper to define version keys with literal type inference and runtime validation.\n * - Validates that all version values are unique\n * - Validates that no version value is empty\n * - Eliminates need for `as const` assertion\n *\n * @throws Error if duplicate or empty version values are found\n *\n * @example\n * const Version = defineDataVersions({\n *   Initial: 'v1',\n *   AddedLabels: 'v2',\n * });\n *\n * type VersionedData = {\n *   [Version.Initial]: DataV1;\n *   [Version.AddedLabels]: DataV2;\n * };\n */\nexport function defineDataVersions<const T extends Record<string, string>>(versions: T): T {\n  const values = Object.values(versions) as (string & keyof T)[];\n  const keys = Object.keys(versions) as (keyof T)[];\n  const emptyKeys = keys.filter((key) => versions[key] === '');\n  if (emptyKeys.length > 0) {\n    throw new Error(`Version values must be non-empty strings (empty: ${emptyKeys.join(', ')})`);\n  }\n  const unique = new Set(values);\n  if (unique.size !== values.length) {\n    const duplicates = values.filter((v, i) => values.indexOf(v) !== i);\n    throw new Error(`Duplicate version values: ${[...new Set(duplicates)].join(', ')}`);\n  }\n  return versions;\n}\n\n/** Versioned data wrapper for persistence */\nexport type DataVersioned<T> = {\n  version: DataVersionKey;\n  data: T;\n};\n\n/** Create a DataVersioned wrapper with correct shape */\nexport function makeDataVersioned<T>(version: DataVersionKey, data: T): DataVersioned<T> {\n  return { version, data };\n}\n\n/** Result of migration operation, may include warning if migration failed */\nexport type DataMigrationResult<T> = DataVersioned<T> & {\n  warning?: string;\n};\n\n/** Thrown by recover() to signal unrecoverable data. */\nexport class DataUnrecoverableError extends Error {\n  name = 'DataUnrecoverableError';\n  constructor(dataVersion: DataVersionKey) {\n    super(`Unknown version '${dataVersion}'`);\n  }\n}\n\nexport function isDataUnrecoverableError(error: unknown): error is DataUnrecoverableError {\n  return error instanceof Error && error.name === 'DataUnrecoverableError';\n}\n\ntype MigrationStep = {\n  fromVersion: DataVersionKey;\n  toVersion: DataVersionKey;\n  migrate: (data: unknown) => unknown;\n};\n\n/**\n * Default recover function for unknown versions.\n * Use as fallback at the end of custom recover functions.\n *\n * @example\n * .recover((version, data) => {\n *   if (version === 'legacy') {\n *     return transformLegacyData(data);\n *   }\n *   return defaultRecover(version, data);\n * })\n */\nexport const defaultRecover: DataRecoverFn<never> = (version, _data) => {\n  throw new DataUnrecoverableError(version);\n};\n\n/** Symbol for internal builder creation method */\nconst FROM_BUILDER = Symbol('fromBuilder');\n\n/** Internal state passed from builder to DataModel */\ntype BuilderState<S> = {\n  versionChain: DataVersionKey[];\n  steps: MigrationStep[];\n  initialDataFn: () => S;\n  recoverFn?: DataRecoverFn<S>;\n};\n\n/**\n * Final builder state after recover() is called.\n * Only allows calling create() to finalize the DataModel.\n *\n * @typeParam VersionedData - Map of version keys to their data types\n * @typeParam CurrentVersion - The current (final) version in the chain\n * @internal\n */\nclass DataModelBuilderWithRecover<\n  VersionedData extends DataVersionMap,\n  CurrentVersion extends keyof VersionedData & string,\n> {\n  private readonly versionChain: DataVersionKey[];\n  private readonly migrationSteps: MigrationStep[];\n  private readonly recoverFn: DataRecoverFn<VersionedData[CurrentVersion]>;\n\n  /** @internal */\n  constructor({\n    versionChain,\n    steps,\n    recoverFn,\n  }: {\n    versionChain: DataVersionKey[];\n    steps: MigrationStep[];\n    recoverFn: DataRecoverFn<VersionedData[CurrentVersion]>;\n  }) {\n    this.versionChain = versionChain;\n    this.migrationSteps = steps;\n    this.recoverFn = recoverFn;\n  }\n\n  /**\n   * Finalize the DataModel with initial data factory.\n   *\n   * The initial data factory is called when creating new blocks or when\n   * migration/recovery fails and data must be reset.\n   *\n   * @param initialData - Factory function returning initial state (must exactly match CurrentVersion's data type)\n   * @returns Finalized DataModel instance\n   *\n   * @example\n   * .init(() => ({ numbers: [], labels: [], description: '' }))\n   */\n  init<S extends VersionedData[CurrentVersion]>(\n    initialData: DataCreateFn<S>,\n    // Compile-time check: S must have exactly the same keys as VersionedData[CurrentVersion]\n    ..._noExtraKeys: Exclude<keyof S, keyof VersionedData[CurrentVersion]> extends never ? [] : [never]\n  ): DataModel<VersionedData[CurrentVersion]> {\n    return DataModel[FROM_BUILDER]<VersionedData[CurrentVersion]>({\n      versionChain: this.versionChain,\n      steps: this.migrationSteps,\n      initialDataFn: initialData as DataCreateFn<VersionedData[CurrentVersion]>,\n      recoverFn: this.recoverFn,\n    });\n  }\n}\n\n/**\n * Internal builder for constructing DataModel with type-safe migration chains.\n *\n * Tracks the current version through the generic type system, ensuring:\n * - Migration functions receive correctly typed input\n * - Migration functions must return the correct output type\n * - Version keys must exist in the VersionedData map\n * - All versions must be covered before calling init()\n *\n * @typeParam VersionedData - Map of version keys to their data types\n * @typeParam CurrentVersion - The current version in the migration chain\n * @typeParam RemainingVersions - Versions not yet covered by migrations\n * @internal\n */\nclass DataModelMigrationChain<\n  VersionedData extends DataVersionMap,\n  CurrentVersion extends keyof VersionedData & string,\n  RemainingVersions extends keyof VersionedData & string = Exclude<keyof VersionedData & string, CurrentVersion>,\n> {\n  private readonly versionChain: DataVersionKey[];\n  private readonly migrationSteps: MigrationStep[];\n\n  /** @internal */\n  constructor({\n    versionChain,\n    steps = [],\n  }: {\n    versionChain: DataVersionKey[];\n    steps?: MigrationStep[];\n  }) {\n    this.versionChain = versionChain;\n    this.migrationSteps = steps;\n  }\n\n  /**\n   * Add a migration step to transform data from current version to next version.\n   *\n   * Migration functions:\n   * - Receive data typed as the current version's data type (readonly)\n   * - Must return data matching the target version's data type\n   * - Should be pure functions (no side effects)\n   * - May throw errors (will result in data reset with warning)\n   *\n   * @typeParam NextVersion - The target version key (must be in RemainingVersions)\n   * @param nextVersion - The version key to migrate to\n   * @param fn - Migration function transforming current data to next version\n   * @returns Builder with updated current version\n   *\n   * @example\n   * .migrate(Version.V2, (data) => ({ ...data, labels: [] }))\n   */\n  migrate<NextVersion extends RemainingVersions>(\n    nextVersion: NextVersion,\n    fn: DataMigrateFn<VersionedData[CurrentVersion], VersionedData[NextVersion]>,\n  ): DataModelMigrationChain<VersionedData, NextVersion, Exclude<RemainingVersions, NextVersion>> {\n    if (this.versionChain.includes(nextVersion)) {\n      throw new Error(`Duplicate version '${nextVersion}' in migration chain`);\n    }\n    const fromVersion = this.versionChain[this.versionChain.length - 1];\n    const step: MigrationStep = { fromVersion, toVersion: nextVersion, migrate: fn as (data: unknown) => unknown };\n    return new DataModelMigrationChain<VersionedData, NextVersion, Exclude<RemainingVersions, NextVersion>>({\n      versionChain: [...this.versionChain, nextVersion],\n      steps: [...this.migrationSteps, step],\n    });\n  }\n\n  /**\n   * Set a recovery handler for unknown or legacy versions.\n   *\n   * The recover function is called when data has a version not in the migration chain.\n   * It should either:\n   * - Transform the data to the current version's format and return it\n   * - Call `defaultRecover(version, data)` to signal unrecoverable data\n   *\n   * Can only be called once. After calling, only `init()` is available.\n   *\n   * @param fn - Recovery function that transforms unknown data or throws\n   * @returns Builder with only init() method available\n   *\n   * @example\n   * .recover((version, data) => {\n   *   if (version === 'legacy' && isLegacyFormat(data)) {\n   *     return transformLegacy(data);\n   *   }\n   *   return defaultRecover(version, data);\n   * })\n   */\n  recover(\n    fn: DataRecoverFn<VersionedData[CurrentVersion]>,\n  ): DataModelBuilderWithRecover<VersionedData, CurrentVersion> {\n    return new DataModelBuilderWithRecover<VersionedData, CurrentVersion>({\n      versionChain: [...this.versionChain],\n      steps: [...this.migrationSteps],\n      recoverFn: fn,\n    });\n  }\n\n  /**\n   * Finalize the DataModel with initial data factory.\n   *\n   * Can only be called when all versions in VersionedData have been covered\n   * by the migration chain (RemainingVersions is empty).\n   *\n   * The initial data factory is called when creating new blocks or when\n   * migration/recovery fails and data must be reset.\n   *\n   * @param initialData - Factory function returning initial state (must exactly match CurrentVersion's data type)\n   * @returns Finalized DataModel instance\n   *\n   * @example\n   * .init(() => ({ numbers: [], labels: [], description: '' }))\n   */\n  init<S extends VersionedData[CurrentVersion]>(\n    // Compile-time check: RemainingVersions must be empty (all versions covered)\n    this: DataModelMigrationChain<VersionedData, CurrentVersion, never>,\n    initialData: DataCreateFn<S>,\n    // Compile-time check: S must have exactly the same keys as VersionedData[CurrentVersion]\n    ..._noExtraKeys: Exclude<keyof S, keyof VersionedData[CurrentVersion]> extends never ? [] : [never]\n  ): DataModel<VersionedData[CurrentVersion]> {\n    return DataModel[FROM_BUILDER]<VersionedData[CurrentVersion]>({\n      versionChain: this.versionChain,\n      steps: this.migrationSteps,\n      initialDataFn: initialData as DataCreateFn<VersionedData[CurrentVersion]>,\n    });\n  }\n}\n\n/**\n * Builder entry point for creating DataModel with type-safe migrations.\n *\n * @typeParam VersionedData - Map of version keys to their data types\n *\n * @example\n * const Version = defineDataVersions({\n *   V1: 'v1',\n *   V2: 'v2',\n * });\n *\n * type VersionedData = {\n *   [Version.V1]: { count: number };\n *   [Version.V2]: { count: number; label: string };\n * };\n *\n * const dataModel = new DataModelBuilder<VersionedData>()\n *   .from(Version.V1)\n *   .migrate(Version.V2, (data) => ({ ...data, label: '' }))\n *   .init(() => ({ count: 0, label: '' }));\n */\nexport class DataModelBuilder<VersionedData extends DataVersionMap> {\n  /**\n   * Start a migration chain from an initial version.\n   *\n   * @typeParam InitialVersion - The starting version key (inferred from argument)\n   * @param initialVersion - The version key to start from\n   * @returns Migration chain builder for adding migrations\n   *\n   * @example\n   * new DataModelBuilder<VersionedData>()\n   *   .from(Version.V1)\n   *   .migrate(Version.V2, (data) => ({ ...data, newField: '' }))\n   */\n  from<InitialVersion extends keyof VersionedData & string>(\n    initialVersion: InitialVersion,\n  ): DataModelMigrationChain<VersionedData, InitialVersion, Exclude<keyof VersionedData & string, InitialVersion>> {\n    return new DataModelMigrationChain<\n      VersionedData,\n      InitialVersion,\n      Exclude<keyof VersionedData & string, InitialVersion>\n    >({ versionChain: [initialVersion] });\n  }\n}\n\n/**\n * DataModel defines the block's data structure, initial values, and migrations.\n * Used by BlockModelV3 to manage data state.\n *\n * Two ways to create a DataModel:\n *\n * 1. **Simple (no migrations)** - Use `DataModel.create()`:\n * @example\n * const dataModel = DataModel.create<BlockData>(() => ({\n *   numbers: [],\n *   labels: [],\n * }));\n *\n * 2. **With migrations** - Use `new DataModelBuilder<VersionedData>()`:\n * @example\n * const Version = defineDataVersions({\n *   V1: 'v1',\n *   V2: 'v2',\n *   V3: 'v3',\n * });\n *\n * type VersionedData = {\n *   [Version.V1]: { numbers: number[] };\n *   [Version.V2]: { numbers: number[]; labels: string[] };\n *   [Version.V3]: { numbers: number[]; labels: string[]; description: string };\n * };\n *\n * const dataModel = new DataModelBuilder<VersionedData>()\n *   .from(Version.V1)\n *   .migrate(Version.V2, (data) => ({ ...data, labels: [] }))\n *   .migrate(Version.V3, (data) => ({ ...data, description: '' }))\n *   .recover((version, data) => {\n *     if (version === 'legacy' && typeof data === 'object' && data !== null && 'numbers' in data) {\n *       return { numbers: (data as { numbers: number[] }).numbers, labels: [], description: '' };\n *     }\n *     return defaultRecover(version, data);\n *   })\n *   .init(() => ({ numbers: [], labels: [], description: '' }));\n */\nexport class DataModel<State> {\n  private readonly versionChain: DataVersionKey[];\n  private readonly steps: MigrationStep[];\n  private readonly initialDataFn: () => State;\n  private readonly recoverFn: DataRecoverFn<State>;\n\n  private constructor({\n    versionChain,\n    steps,\n    initialDataFn,\n    recoverFn = defaultRecover as DataRecoverFn<State>,\n  }: {\n    versionChain: DataVersionKey[];\n    steps: MigrationStep[];\n    initialDataFn: () => State;\n    recoverFn?: DataRecoverFn<State>;\n  }) {\n    if (versionChain.length === 0) {\n      throw new Error('DataModel requires at least one version key');\n    }\n    this.versionChain = versionChain;\n    this.steps = steps;\n    this.initialDataFn = initialDataFn;\n    this.recoverFn = recoverFn;\n  }\n\n  /**\n   * Create a DataModel with just initial data (no migrations).\n   *\n   * Use this for simple blocks that don't need version migrations.\n   * The version will be set to an internal default value.\n   *\n   * @typeParam S - The state type\n   * @param initialData - Factory function returning initial state\n   * @param version - Optional custom version key (defaults to internal version)\n   * @returns Finalized DataModel instance\n   *\n   * @example\n   * const dataModel = DataModel.create<BlockData>(() => ({\n   *   numbers: [],\n   *   labels: [],\n   * }));\n   */\n  static create<S>(initialData: () => S, version: DataVersionKey = DATA_MODEL_DEFAULT_VERSION): DataModel<S> {\n    return new DataModel<S>({\n      versionChain: [version],\n      steps: [],\n      initialDataFn: initialData,\n    });\n  }\n\n  /**\n   * Internal method for creating DataModel from builder.\n   * Uses Symbol key to prevent external access.\n   * @internal\n   */\n  static [FROM_BUILDER]<S>(state: BuilderState<S>): DataModel<S> {\n    return new DataModel<S>(state);\n  }\n\n  /**\n   * The latest (current) version key in the migration chain.\n   */\n  get version(): DataVersionKey {\n    return this.versionChain[this.versionChain.length - 1];\n  }\n\n  /**\n   * Number of migration steps defined.\n   */\n  get migrationCount(): number {\n    return this.steps.length;\n  }\n\n  /**\n   * Get a fresh copy of the initial data.\n   */\n  initialData(): State {\n    return this.initialDataFn();\n  }\n\n  /**\n   * Get initial data wrapped with current version.\n   * Used when creating new blocks or resetting to defaults.\n   */\n  getDefaultData(): DataVersioned<State> {\n    return makeDataVersioned(this.version, this.initialDataFn());\n  }\n\n  private recoverFrom(data: unknown, version: DataVersionKey): DataMigrationResult<State> {\n    try {\n      return { version: this.version, data: this.recoverFn(version, data) };\n    } catch (error) {\n      if (isDataUnrecoverableError(error)) {\n        return { ...this.getDefaultData(), warning: error.message };\n      }\n      const errorMessage = error instanceof Error ? error.message : String(error);\n      return {\n        ...this.getDefaultData(),\n        warning: `Recover failed for version '${version}': ${errorMessage}`,\n      };\n    }\n  }\n\n  /**\n   * Migrate versioned data from any version to the latest.\n   *\n   * - If data is already at latest version, returns as-is\n   * - If version is in chain, applies needed migrations\n   * - If version is unknown, calls recover function\n   * - If migration/recovery fails, returns default data with warning\n   *\n   * @param versioned - Data with version tag\n   * @returns Migration result with data at latest version\n   */\n  migrate(versioned: DataVersioned<unknown>): DataMigrationResult<State> {\n    const { version: fromVersion, data } = versioned;\n\n    if (fromVersion === this.version) {\n      return { version: this.version, data: data as State };\n    }\n\n    const startIndex = this.versionChain.indexOf(fromVersion);\n    if (startIndex < 0) {\n      return this.recoverFrom(data, fromVersion);\n    }\n\n    let currentData: unknown = data;\n    for (let i = startIndex; i < this.steps.length; i++) {\n      const step = this.steps[i];\n      try {\n        currentData = step.migrate(currentData);\n      } catch (error) {\n        const errorMessage = error instanceof Error ? error.message : String(error);\n        return {\n          ...this.getDefaultData(),\n          warning: `Migration ${step.fromVersion}→${step.toVersion} failed: ${errorMessage}`,\n        };\n      }\n    }\n\n    return { version: this.version, data: currentData as State };\n  }\n\n  /**\n   * Register callbacks for use in the VM.\n   * Called by BlockModelV3.create() to set up internal callbacks.\n   *\n   * @internal\n   */\n  registerCallbacks(): void {\n    tryRegisterCallback('__pl_data_initial', () => this.initialDataFn());\n    tryRegisterCallback('__pl_data_upgrade', (versioned: DataVersioned<unknown>) => this.migrate(versioned));\n    tryRegisterCallback('__pl_storage_initial', () => {\n      const { version, data } = this.getDefaultData();\n      const storage = createBlockStorage(data, version);\n      return JSON.stringify(storage);\n    });\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/block_storage.cjs

@@ -68,7 +68,13 @@ function createBlockStorage(initialData = {}, version = DATA_MODEL_DEFAULT_VERSI
 function normalizeBlockStorage(raw) {
     if (isBlockStorage(raw)) {
         const storage = raw;
-        return { ...storage, __dataVersion: String(storage.__dataVersion) };
+        return {
+            ...storage,
+            // Fix for early released version where __dataVersion was a number
+            __dataVersion: typeof storage.__dataVersion === 'number'
+                ? DATA_MODEL_DEFAULT_VERSION
+                : storage.__dataVersion,
+        };
     }
     // Legacy format: raw is the state directly
     return createBlockStorage(raw);

package/dist/block_storage.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"block_storage.cjs","sources":["../src/block_storage.ts"],"sourcesContent":["/**\n * BlockStorage - Typed storage abstraction for block persistent data.\n *\n * This module provides:\n * - A typed structure for block storage with versioning and plugin support\n * - Utility functions for manipulating storage\n * - Handler interfaces for model-level customization\n *\n * @module block_storage\n */\n\n// =============================================================================\n// Core Types\n// =============================================================================\n\n/**\n * Discriminator key for BlockStorage format detection.\n * This unique hash-based key identifies data as BlockStorage vs legacy formats.\n */\nexport const BLOCK_STORAGE_KEY = '__pl_a7f3e2b9__';\n\n/**\n * Current BlockStorage schema version.\n * Increment this when the storage structure itself changes (not block state migrations).\n */\nexport const BLOCK_STORAGE_SCHEMA_VERSION = 'v1';\n\n/**\n * Default data version for new blocks without migrations.\n * Unique identifier ensures blocks are created via DataModel API.\n */\nexport const DATA_MODEL_DEFAULT_VERSION = '__pl_v1_d4e8f2a1__';\n\n/**\n * Type for valid schema versions\n */\nexport type BlockStorageSchemaVersion = 'v1'; // Add 'v2', 'v3', etc. as schema evolves\n\n/**\n * Plugin key type - keys starting with `@plugin/` are reserved for plugin data\n */\nexport type PluginKey = `@plugin/${string}`;\n\n/**\n * Core BlockStorage type that holds:\n * - __pl_a7f3e2b9__: Schema version (discriminator key identifies BlockStorage format)\n * - __dataVersion: Version key for block data migrations\n * - __data: The block's user-facing data (state)\n * - @plugin/*: Optional plugin-specific data\n */\nexport type BlockStorage<TState = unknown> = {\n  /** Schema version - the key itself is the discriminator */\n  readonly [BLOCK_STORAGE_KEY]: BlockStorageSchemaVersion;\n  /** Version of the block data, used for migrations */\n  __dataVersion: string;\n  /** The block's user-facing data (state) */\n  __data: TState;\n} & {\n  /** Plugin-specific data, keyed by `@plugin/<pluginName>` */\n  [K in PluginKey]?: unknown;\n};\n\n/**\n * Type guard to check if a value is a valid BlockStorage object.\n * Checks for the discriminator key and valid schema version.\n */\nexport function isBlockStorage(value: unknown): value is BlockStorage {\n  if (value === null || typeof value !== 'object') return false;\n  const obj = value as Record<string, unknown>;\n  const schemaVersion = obj[BLOCK_STORAGE_KEY];\n  // Currently only 'v1' is valid, but this allows future versions\n  return schemaVersion === 'v1'; // Add more versions as schema evolves\n}\n\n// =============================================================================\n// Factory Functions\n// =============================================================================\n\n/**\n * Creates a BlockStorage with the given initial data\n *\n * @param initialData - The initial data value (defaults to empty object)\n * @param version - The initial data version key (defaults to DATA_MODEL_DEFAULT_VERSION)\n * @returns A new BlockStorage instance with discriminator key\n */\nexport function createBlockStorage<TState = unknown>(\n  initialData: TState = {} as TState,\n  version: string = DATA_MODEL_DEFAULT_VERSION,\n): BlockStorage<TState> {\n  return {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: version,\n    __data: initialData,\n  };\n}\n\n/**\n * Normalizes raw storage data to BlockStorage format.\n * If the input is already a BlockStorage, returns it as-is.\n * If the input is legacy format (raw state), wraps it in BlockStorage structure.\n *\n * @param raw - Raw storage data (may be legacy format or BlockStorage)\n * @returns Normalized BlockStorage\n */\nexport function normalizeBlockStorage<TState = unknown>(raw: unknown): BlockStorage<TState> {\n  if (isBlockStorage(raw)) {\n    const storage = raw as BlockStorage<TState>;\n    return { ...storage, __dataVersion: String(storage.__dataVersion) };\n  }\n  // Legacy format: raw is the state directly\n  return createBlockStorage(raw as TState);\n}\n\n// =============================================================================\n// Data Access & Update Functions\n// =============================================================================\n\n/**\n * Gets the data from BlockStorage\n *\n * @param storage - The BlockStorage instance\n * @returns The data value\n */\nexport function getStorageData<TState>(storage: BlockStorage<TState>): TState {\n  return storage.__data;\n}\n\n/**\n * Derives data from raw block storage.\n * This function is meant to be called from sdk/ui-vue to extract\n * user-facing data from the raw storage returned by the middle layer.\n *\n * The middle layer returns raw storage (opaque to it), and the UI\n * uses this function to derive the actual data value.\n *\n * @param rawStorage - Raw storage data from middle layer (may be any format)\n * @returns The extracted data value, or undefined if storage is undefined/null\n */\nexport function deriveDataFromStorage<TData = unknown>(\n  rawStorage: unknown,\n): TData {\n  // Normalize to BlockStorage format (handles legacy formats too)\n  const storage = normalizeBlockStorage<TData>(rawStorage);\n  return getStorageData(storage);\n}\n\n/** Payload for storage mutation operations. SDK defines specific operations. */\nexport type MutateStoragePayload<T = unknown> = { operation: 'update-data'; value: T };\n\n/**\n * Updates the data in BlockStorage (immutable)\n *\n * @param storage - The current BlockStorage\n * @param payload - The update payload with operation and value\n * @returns A new BlockStorage with updated data\n */\nexport function updateStorageData<TValue = unknown>(\n  storage: BlockStorage<TValue>,\n  payload: MutateStoragePayload<TValue>,\n): BlockStorage<TValue> {\n  switch (payload.operation) {\n    case 'update-data':\n      return { ...storage, __data: payload.value };\n    default:\n      throw new Error(`Unknown storage operation: ${(payload as { operation: string }).operation}`);\n  }\n}\n\n/**\n * Gets the data version from BlockStorage\n *\n * @param storage - The BlockStorage instance\n * @returns The data version key\n */\nexport function getStorageDataVersion(storage: BlockStorage): string {\n  return storage.__dataVersion;\n}\n\n/**\n * Updates the data version in BlockStorage (immutable)\n *\n * @param storage - The current BlockStorage\n * @param version - The new version key\n * @returns A new BlockStorage with updated version\n */\nexport function updateStorageDataVersion<TState>(\n  storage: BlockStorage<TState>,\n  version: string,\n): BlockStorage<TState> {\n  return { ...storage, __dataVersion: version };\n}\n\n/**\n * Storage debug view returned by __pl_storage_debugView callback.\n * Used by developer tools to display block storage info.\n */\nexport interface StorageDebugView {\n  /** Current data version key */\n  dataVersion: string;\n  /** Raw data payload stored in BlockStorage */\n  data: unknown;\n}\n\n// =============================================================================\n// Plugin Data Functions\n// =============================================================================\n\n/**\n * Gets plugin-specific data from BlockStorage\n *\n * @param storage - The BlockStorage instance\n * @param pluginName - The plugin name (without `@plugin/` prefix)\n * @returns The plugin data or undefined if not set\n */\nexport function getPluginData<TData = unknown>(\n  storage: BlockStorage,\n  pluginName: string,\n): TData | undefined {\n  const key: PluginKey = `@plugin/${pluginName}`;\n  return storage[key] as TData | undefined;\n}\n\n/**\n * Sets plugin-specific data in BlockStorage (immutable)\n *\n * @param storage - The current BlockStorage\n * @param pluginName - The plugin name (without `@plugin/` prefix)\n * @param data - The plugin data to store\n * @returns A new BlockStorage with updated plugin data\n */\nexport function setPluginData<TState>(\n  storage: BlockStorage<TState>,\n  pluginName: string,\n  data: unknown,\n): BlockStorage<TState> {\n  const key: PluginKey = `@plugin/${pluginName}`;\n  return { ...storage, [key]: data };\n}\n\n/**\n * Removes plugin-specific data from BlockStorage (immutable)\n *\n * @param storage - The current BlockStorage\n * @param pluginName - The plugin name (without `@plugin/` prefix)\n * @returns A new BlockStorage with the plugin data removed\n */\nexport function removePluginData<TState>(\n  storage: BlockStorage<TState>,\n  pluginName: string,\n): BlockStorage<TState> {\n  const key: PluginKey = `@plugin/${pluginName}`;\n  const { [key]: _, ...rest } = storage;\n  return rest as BlockStorage<TState>;\n}\n\n/**\n * Gets all plugin names that have data stored\n *\n * @param storage - The BlockStorage instance\n * @returns Array of plugin names (without `@plugin/` prefix)\n */\nexport function getPluginNames(storage: BlockStorage): string[] {\n  return Object.keys(storage)\n    .filter((key): key is PluginKey => key.startsWith('@plugin/'))\n    .map((key) => key.slice('@plugin/'.length));\n}\n\n// =============================================================================\n// Generic Storage Access\n// =============================================================================\n\n/**\n * Gets a value from BlockStorage by key\n *\n * @param storage - The BlockStorage instance\n * @param key - The key to retrieve\n * @returns The value at the given key\n */\nexport function getFromStorage<\n  TState,\n  K extends keyof BlockStorage<TState>,\n>(storage: BlockStorage<TState>, key: K): BlockStorage<TState>[K] {\n  return storage[key];\n}\n\n/**\n * Updates a value in BlockStorage by key (immutable)\n *\n * @param storage - The current BlockStorage\n * @param key - The key to update\n * @param value - The new value\n * @returns A new BlockStorage with the updated value\n */\nexport function updateStorage<\n  TState,\n  K extends keyof BlockStorage<TState>,\n>(\n  storage: BlockStorage<TState>,\n  key: K,\n  value: BlockStorage<TState>[K],\n): BlockStorage<TState> {\n  return { ...storage, [key]: value };\n}\n\n// =============================================================================\n// Storage Handlers (for Phase 2 - Model-Level Customization)\n// =============================================================================\n\n/**\n * Interface for model-configurable storage operations.\n * These handlers allow block models to customize how storage is managed.\n */\nexport interface BlockStorageHandlers<TState = unknown> {\n  /**\n   * Called when setState is invoked - transforms the new state before storing.\n   * Default behavior: replaces the state directly.\n   *\n   * @param currentStorage - The current BlockStorage\n   * @param newState - The new state being set\n   * @returns The updated BlockStorage\n   */\n  transformStateForStorage?: (\n    currentStorage: BlockStorage<TState>,\n    newState: TState,\n  ) => BlockStorage<TState>;\n\n  /**\n   * Called when reading state for args derivation.\n   * Default behavior: returns the state directly.\n   *\n   * @param storage - The current BlockStorage\n   * @returns The state to use for args derivation\n   */\n  deriveStateForArgs?: (storage: BlockStorage<TState>) => TState;\n\n  /**\n   * Called during storage schema migration.\n   * Default behavior: updates stateVersion only.\n   *\n   * @param oldStorage - The storage before migration\n   * @param fromVersion - The version migrating from\n   * @param toVersion - The version migrating to\n   * @returns The migrated BlockStorage\n   */\n  migrateStorage?: (\n    oldStorage: BlockStorage<TState>,\n    fromVersion: string,\n    toVersion: string,\n  ) => BlockStorage<TState>;\n}\n\n/**\n * Default implementations of storage handlers\n */\nexport const defaultBlockStorageHandlers: Required<BlockStorageHandlers<unknown>> = {\n  transformStateForStorage: <TState>(\n    storage: BlockStorage<TState>,\n    newState: TState,\n  ): BlockStorage<TState> => updateStorageData(storage, { operation: 'update-data', value: newState }),\n\n  deriveStateForArgs: <TState>(storage: BlockStorage<TState>): TState => getStorageData(storage),\n\n  migrateStorage: <TState>(\n    storage: BlockStorage<TState>,\n    _fromVersion: string,\n    toVersion: string,\n  ): BlockStorage<TState> => updateStorageDataVersion(storage, toVersion),\n};\n\n/**\n * Merges custom handlers with defaults\n *\n * @param customHandlers - Custom handlers to merge\n * @returns Complete handlers with defaults for missing functions\n */\nexport function mergeBlockStorageHandlers<TState>(\n  customHandlers?: BlockStorageHandlers<TState>,\n): Required<BlockStorageHandlers<TState>> {\n  return {\n    ...defaultBlockStorageHandlers,\n    ...customHandlers,\n  } as Required<BlockStorageHandlers<TState>>;\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"block_storage.cjs","sources":["../src/block_storage.ts"],"sourcesContent":["/**\n * BlockStorage - Typed storage abstraction for block persistent data.\n *\n * This module provides:\n * - A typed structure for block storage with versioning and plugin support\n * - Utility functions for manipulating storage\n * - Handler interfaces for model-level customization\n *\n * @module block_storage\n */\n\n// =============================================================================\n// Core Types\n// =============================================================================\n\n/**\n * Discriminator key for BlockStorage format detection.\n * This unique hash-based key identifies data as BlockStorage vs legacy formats.\n */\nexport const BLOCK_STORAGE_KEY = '__pl_a7f3e2b9__';\n\n/**\n * Current BlockStorage schema version.\n * Increment this when the storage structure itself changes (not block state migrations).\n */\nexport const BLOCK_STORAGE_SCHEMA_VERSION = 'v1';\n\n/**\n * Default data version for new blocks without migrations.\n * Unique identifier ensures blocks are created via DataModel API.\n */\nexport const DATA_MODEL_DEFAULT_VERSION = '__pl_v1_d4e8f2a1__';\n\n/**\n * Type for valid schema versions\n */\nexport type BlockStorageSchemaVersion = 'v1'; // Add 'v2', 'v3', etc. as schema evolves\n\n/**\n * Plugin key type - keys starting with `@plugin/` are reserved for plugin data\n */\nexport type PluginKey = `@plugin/${string}`;\n\n/**\n * Core BlockStorage type that holds:\n * - __pl_a7f3e2b9__: Schema version (discriminator key identifies BlockStorage format)\n * - __dataVersion: Version key for block data migrations\n * - __data: The block's user-facing data (state)\n * - @plugin/*: Optional plugin-specific data\n */\nexport type BlockStorage<TState = unknown> = {\n  /** Schema version - the key itself is the discriminator */\n  readonly [BLOCK_STORAGE_KEY]: BlockStorageSchemaVersion;\n  /** Version of the block data, used for migrations */\n  __dataVersion: string;\n  /** The block's user-facing data (state) */\n  __data: TState;\n} & {\n  /** Plugin-specific data, keyed by `@plugin/<pluginName>` */\n  [K in PluginKey]?: unknown;\n};\n\n/**\n * Type guard to check if a value is a valid BlockStorage object.\n * Checks for the discriminator key and valid schema version.\n */\nexport function isBlockStorage(value: unknown): value is BlockStorage {\n  if (value === null || typeof value !== 'object') return false;\n  const obj = value as Record<string, unknown>;\n  const schemaVersion = obj[BLOCK_STORAGE_KEY];\n  // Currently only 'v1' is valid, but this allows future versions\n  return schemaVersion === 'v1'; // Add more versions as schema evolves\n}\n\n// =============================================================================\n// Factory Functions\n// =============================================================================\n\n/**\n * Creates a BlockStorage with the given initial data\n *\n * @param initialData - The initial data value (defaults to empty object)\n * @param version - The initial data version key (defaults to DATA_MODEL_DEFAULT_VERSION)\n * @returns A new BlockStorage instance with discriminator key\n */\nexport function createBlockStorage<TState = unknown>(\n  initialData: TState = {} as TState,\n  version: string = DATA_MODEL_DEFAULT_VERSION,\n): BlockStorage<TState> {\n  return {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: version,\n    __data: initialData,\n  };\n}\n\n/**\n * Normalizes raw storage data to BlockStorage format.\n * If the input is already a BlockStorage, returns it as-is.\n * If the input is legacy format (raw state), wraps it in BlockStorage structure.\n *\n * @param raw - Raw storage data (may be legacy format or BlockStorage)\n * @returns Normalized BlockStorage\n */\nexport function normalizeBlockStorage<TState = unknown>(raw: unknown): BlockStorage<TState> {\n  if (isBlockStorage(raw)) {\n    const storage = raw as BlockStorage<TState>;\n    return {\n      ...storage,\n      // Fix for early released version where __dataVersion was a number\n      __dataVersion: typeof storage.__dataVersion === 'number'\n        ? DATA_MODEL_DEFAULT_VERSION\n        : storage.__dataVersion,\n    };\n  }\n  // Legacy format: raw is the state directly\n  return createBlockStorage(raw as TState);\n}\n\n// =============================================================================\n// Data Access & Update Functions\n// =============================================================================\n\n/**\n * Gets the data from BlockStorage\n *\n * @param storage - The BlockStorage instance\n * @returns The data value\n */\nexport function getStorageData<TState>(storage: BlockStorage<TState>): TState {\n  return storage.__data;\n}\n\n/**\n * Derives data from raw block storage.\n * This function is meant to be called from sdk/ui-vue to extract\n * user-facing data from the raw storage returned by the middle layer.\n *\n * The middle layer returns raw storage (opaque to it), and the UI\n * uses this function to derive the actual data value.\n *\n * @param rawStorage - Raw storage data from middle layer (may be any format)\n * @returns The extracted data value, or undefined if storage is undefined/null\n */\nexport function deriveDataFromStorage<TData = unknown>(\n  rawStorage: unknown,\n): TData {\n  // Normalize to BlockStorage format (handles legacy formats too)\n  const storage = normalizeBlockStorage<TData>(rawStorage);\n  return getStorageData(storage);\n}\n\n/** Payload for storage mutation operations. SDK defines specific operations. */\nexport type MutateStoragePayload<T = unknown> = { operation: 'update-data'; value: T };\n\n/**\n * Updates the data in BlockStorage (immutable)\n *\n * @param storage - The current BlockStorage\n * @param payload - The update payload with operation and value\n * @returns A new BlockStorage with updated data\n */\nexport function updateStorageData<TValue = unknown>(\n  storage: BlockStorage<TValue>,\n  payload: MutateStoragePayload<TValue>,\n): BlockStorage<TValue> {\n  switch (payload.operation) {\n    case 'update-data':\n      return { ...storage, __data: payload.value };\n    default:\n      throw new Error(`Unknown storage operation: ${(payload as { operation: string }).operation}`);\n  }\n}\n\n/**\n * Gets the data version from BlockStorage\n *\n * @param storage - The BlockStorage instance\n * @returns The data version key\n */\nexport function getStorageDataVersion(storage: BlockStorage): string {\n  return storage.__dataVersion;\n}\n\n/**\n * Updates the data version in BlockStorage (immutable)\n *\n * @param storage - The current BlockStorage\n * @param version - The new version key\n * @returns A new BlockStorage with updated version\n */\nexport function updateStorageDataVersion<TState>(\n  storage: BlockStorage<TState>,\n  version: string,\n): BlockStorage<TState> {\n  return { ...storage, __dataVersion: version };\n}\n\n/**\n * Storage debug view returned by __pl_storage_debugView callback.\n * Used by developer tools to display block storage info.\n */\nexport interface StorageDebugView {\n  /** Current data version key */\n  dataVersion: string;\n  /** Raw data payload stored in BlockStorage */\n  data: unknown;\n}\n\n// =============================================================================\n// Plugin Data Functions\n// =============================================================================\n\n/**\n * Gets plugin-specific data from BlockStorage\n *\n * @param storage - The BlockStorage instance\n * @param pluginName - The plugin name (without `@plugin/` prefix)\n * @returns The plugin data or undefined if not set\n */\nexport function getPluginData<TData = unknown>(\n  storage: BlockStorage,\n  pluginName: string,\n): TData | undefined {\n  const key: PluginKey = `@plugin/${pluginName}`;\n  return storage[key] as TData | undefined;\n}\n\n/**\n * Sets plugin-specific data in BlockStorage (immutable)\n *\n * @param storage - The current BlockStorage\n * @param pluginName - The plugin name (without `@plugin/` prefix)\n * @param data - The plugin data to store\n * @returns A new BlockStorage with updated plugin data\n */\nexport function setPluginData<TState>(\n  storage: BlockStorage<TState>,\n  pluginName: string,\n  data: unknown,\n): BlockStorage<TState> {\n  const key: PluginKey = `@plugin/${pluginName}`;\n  return { ...storage, [key]: data };\n}\n\n/**\n * Removes plugin-specific data from BlockStorage (immutable)\n *\n * @param storage - The current BlockStorage\n * @param pluginName - The plugin name (without `@plugin/` prefix)\n * @returns A new BlockStorage with the plugin data removed\n */\nexport function removePluginData<TState>(\n  storage: BlockStorage<TState>,\n  pluginName: string,\n): BlockStorage<TState> {\n  const key: PluginKey = `@plugin/${pluginName}`;\n  const { [key]: _, ...rest } = storage;\n  return rest as BlockStorage<TState>;\n}\n\n/**\n * Gets all plugin names that have data stored\n *\n * @param storage - The BlockStorage instance\n * @returns Array of plugin names (without `@plugin/` prefix)\n */\nexport function getPluginNames(storage: BlockStorage): string[] {\n  return Object.keys(storage)\n    .filter((key): key is PluginKey => key.startsWith('@plugin/'))\n    .map((key) => key.slice('@plugin/'.length));\n}\n\n// =============================================================================\n// Generic Storage Access\n// =============================================================================\n\n/**\n * Gets a value from BlockStorage by key\n *\n * @param storage - The BlockStorage instance\n * @param key - The key to retrieve\n * @returns The value at the given key\n */\nexport function getFromStorage<\n  TState,\n  K extends keyof BlockStorage<TState>,\n>(storage: BlockStorage<TState>, key: K): BlockStorage<TState>[K] {\n  return storage[key];\n}\n\n/**\n * Updates a value in BlockStorage by key (immutable)\n *\n * @param storage - The current BlockStorage\n * @param key - The key to update\n * @param value - The new value\n * @returns A new BlockStorage with the updated value\n */\nexport function updateStorage<\n  TState,\n  K extends keyof BlockStorage<TState>,\n>(\n  storage: BlockStorage<TState>,\n  key: K,\n  value: BlockStorage<TState>[K],\n): BlockStorage<TState> {\n  return { ...storage, [key]: value };\n}\n\n// =============================================================================\n// Storage Handlers (for Phase 2 - Model-Level Customization)\n// =============================================================================\n\n/**\n * Interface for model-configurable storage operations.\n * These handlers allow block models to customize how storage is managed.\n */\nexport interface BlockStorageHandlers<TState = unknown> {\n  /**\n   * Called when setState is invoked - transforms the new state before storing.\n   * Default behavior: replaces the state directly.\n   *\n   * @param currentStorage - The current BlockStorage\n   * @param newState - The new state being set\n   * @returns The updated BlockStorage\n   */\n  transformStateForStorage?: (\n    currentStorage: BlockStorage<TState>,\n    newState: TState,\n  ) => BlockStorage<TState>;\n\n  /**\n   * Called when reading state for args derivation.\n   * Default behavior: returns the state directly.\n   *\n   * @param storage - The current BlockStorage\n   * @returns The state to use for args derivation\n   */\n  deriveStateForArgs?: (storage: BlockStorage<TState>) => TState;\n\n  /**\n   * Called during storage schema migration.\n   * Default behavior: updates stateVersion only.\n   *\n   * @param oldStorage - The storage before migration\n   * @param fromVersion - The version migrating from\n   * @param toVersion - The version migrating to\n   * @returns The migrated BlockStorage\n   */\n  migrateStorage?: (\n    oldStorage: BlockStorage<TState>,\n    fromVersion: string,\n    toVersion: string,\n  ) => BlockStorage<TState>;\n}\n\n/**\n * Default implementations of storage handlers\n */\nexport const defaultBlockStorageHandlers: Required<BlockStorageHandlers<unknown>> = {\n  transformStateForStorage: <TState>(\n    storage: BlockStorage<TState>,\n    newState: TState,\n  ): BlockStorage<TState> => updateStorageData(storage, { operation: 'update-data', value: newState }),\n\n  deriveStateForArgs: <TState>(storage: BlockStorage<TState>): TState => getStorageData(storage),\n\n  migrateStorage: <TState>(\n    storage: BlockStorage<TState>,\n    _fromVersion: string,\n    toVersion: string,\n  ): BlockStorage<TState> => updateStorageDataVersion(storage, toVersion),\n};\n\n/**\n * Merges custom handlers with defaults\n *\n * @param customHandlers - Custom handlers to merge\n * @returns Complete handlers with defaults for missing functions\n */\nexport function mergeBlockStorageHandlers<TState>(\n  customHandlers?: BlockStorageHandlers<TState>,\n): Required<BlockStorageHandlers<TState>> {\n  return {\n    ...defaultBlockStorageHandlers,\n    ...customHandlers,\n  } as Required<BlockStorageHandlers<TState>>;\n}\n"],"names":[],"mappings":"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"}

package/dist/block_storage.d.ts.map

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

package/dist/block_storage.js

@@ -66,7 +66,13 @@ function createBlockStorage(initialData = {}, version = DATA_MODEL_DEFAULT_VERSI
 function normalizeBlockStorage(raw) {
     if (isBlockStorage(raw)) {
         const storage = raw;
-        return { ...storage, __dataVersion: String(storage.__dataVersion) };
+        return {
+            ...storage,
+            // Fix for early released version where __dataVersion was a number
+            __dataVersion: typeof storage.__dataVersion === 'number'
+                ? DATA_MODEL_DEFAULT_VERSION
+                : storage.__dataVersion,
+        };
     }
     // Legacy format: raw is the state directly
     return createBlockStorage(raw);