@platforma-sdk/model 1.53.0 → 1.53.2

package/src/block_storage.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest';
 import {
   BLOCK_STORAGE_KEY,
   BLOCK_STORAGE_SCHEMA_VERSION,
+  DATA_MODEL_DEFAULT_VERSION,
   createBlockStorage,
   defaultBlockStorageHandlers,
   getFromStorage,
@@ -57,11 +58,11 @@ describe('BlockStorage', () => {
     });
 
     it('should return false for objects without discriminator', () => {
-      expect(isBlockStorage({ __dataVersion: 1, __data: {} })).toBe(false);
+      expect(isBlockStorage({ __dataVersion: 'v1', __data: {} })).toBe(false);
     });
 
     it('should return false for objects with wrong discriminator value', () => {
-      expect(isBlockStorage({ [BLOCK_STORAGE_KEY]: 'wrong', __dataVersion: 1, __data: {} })).toBe(false);
+      expect(isBlockStorage({ [BLOCK_STORAGE_KEY]: 'wrong', __dataVersion: 'v1', __data: {} })).toBe(false);
     });
   });
 
@@ -69,7 +70,7 @@ describe('BlockStorage', () => {
     it('should create storage with discriminator key and default values', () => {
       const storage = createBlockStorage();
       expect(storage[BLOCK_STORAGE_KEY]).toBe(BLOCK_STORAGE_SCHEMA_VERSION);
-      expect(storage.__dataVersion).toBe(1);
+      expect(storage.__dataVersion).toBe(DATA_MODEL_DEFAULT_VERSION);
       expect(storage.__data).toEqual({});
     });
 
@@ -77,21 +78,21 @@ describe('BlockStorage', () => {
       const data = { numbers: [1, 2, 3] };
       const storage = createBlockStorage(data);
       expect(storage[BLOCK_STORAGE_KEY]).toBe(BLOCK_STORAGE_SCHEMA_VERSION);
-      expect(storage.__dataVersion).toBe(1);
+      expect(storage.__dataVersion).toBe(DATA_MODEL_DEFAULT_VERSION);
       expect(storage.__data).toEqual(data);
     });
 
     it('should create storage with custom version', () => {
-      const storage = createBlockStorage({ foo: 'bar' }, 5);
+      const storage = createBlockStorage({ foo: 'bar' }, 'v5');
       expect(storage[BLOCK_STORAGE_KEY]).toBe(BLOCK_STORAGE_SCHEMA_VERSION);
-      expect(storage.__dataVersion).toBe(5);
+      expect(storage.__dataVersion).toBe('v5');
       expect(storage.__data).toEqual({ foo: 'bar' });
     });
   });
 
   describe('normalizeBlockStorage', () => {
     it('should return BlockStorage as-is', () => {
-      const storage = createBlockStorage({ data: 'test' }, 2);
+      const storage = createBlockStorage({ data: 'test' }, 'v2');
       const normalized = normalizeBlockStorage(storage);
       expect(normalized).toEqual(storage);
     });
@@ -100,52 +101,52 @@ describe('BlockStorage', () => {
       const legacyData = { numbers: [1, 2, 3], name: 'test' };
       const normalized = normalizeBlockStorage(legacyData);
       expect(normalized[BLOCK_STORAGE_KEY]).toBe(BLOCK_STORAGE_SCHEMA_VERSION);
-      expect(normalized.__dataVersion).toBe(1);
+      expect(normalized.__dataVersion).toBe(DATA_MODEL_DEFAULT_VERSION);
       expect(normalized.__data).toEqual(legacyData);
     });
 
     it('should wrap primitive legacy data', () => {
       const normalized = normalizeBlockStorage('simple string');
       expect(normalized[BLOCK_STORAGE_KEY]).toBe(BLOCK_STORAGE_SCHEMA_VERSION);
-      expect(normalized.__dataVersion).toBe(1);
+      expect(normalized.__dataVersion).toBe(DATA_MODEL_DEFAULT_VERSION);
       expect(normalized.__data).toBe('simple string');
     });
 
     it('should wrap null legacy data', () => {
       const normalized = normalizeBlockStorage(null);
       expect(normalized[BLOCK_STORAGE_KEY]).toBe(BLOCK_STORAGE_SCHEMA_VERSION);
-      expect(normalized.__dataVersion).toBe(1);
+      expect(normalized.__dataVersion).toBe(DATA_MODEL_DEFAULT_VERSION);
       expect(normalized.__data).toBeNull();
     });
   });
 
   describe('Data access functions', () => {
-    const storage = createBlockStorage({ count: 42 }, 3);
+    const storage = createBlockStorage({ count: 42 }, 'v3');
 
     it('getStorageData should return the data', () => {
       expect(getStorageData(storage)).toEqual({ count: 42 });
     });
 
     it('getStorageDataVersion should return the version', () => {
-      expect(getStorageDataVersion(storage)).toBe(3);
+      expect(getStorageDataVersion(storage)).toBe('v3');
     });
 
     it('updateStorageData should return new storage with updated data', () => {
       const newStorage = updateStorageData(storage, { operation: 'update-data', value: { count: 100 } });
       expect(newStorage.__data).toEqual({ count: 100 });
-      expect(newStorage.__dataVersion).toBe(3);
+      expect(newStorage.__dataVersion).toBe('v3');
       expect(newStorage[BLOCK_STORAGE_KEY]).toBe(BLOCK_STORAGE_SCHEMA_VERSION);
       // Original should be unchanged
       expect(storage.__data).toEqual({ count: 42 });
     });
 
     it('updateStorageDataVersion should return new storage with updated version', () => {
-      const newStorage = updateStorageDataVersion(storage, 5);
-      expect(newStorage.__dataVersion).toBe(5);
+      const newStorage = updateStorageDataVersion(storage, 'v5');
+      expect(newStorage.__dataVersion).toBe('v5');
       expect(newStorage.__data).toEqual({ count: 42 });
       expect(newStorage[BLOCK_STORAGE_KEY]).toBe(BLOCK_STORAGE_SCHEMA_VERSION);
       // Original should be unchanged
-      expect(storage.__dataVersion).toBe(3);
+      expect(storage.__dataVersion).toBe('v3');
     });
   });
 
@@ -189,14 +190,14 @@ describe('BlockStorage', () => {
   });
 
   describe('Generic storage access', () => {
-    const storage = createBlockStorage('hello', 2);
+    const storage = createBlockStorage('hello', 'v2');
 
     it('getFromStorage should get __data', () => {
       expect(getFromStorage(storage, '__data')).toBe('hello');
     });
 
     it('getFromStorage should get __dataVersion', () => {
-      expect(getFromStorage(storage, '__dataVersion')).toBe(2);
+      expect(getFromStorage(storage, '__dataVersion')).toBe('v2');
     });
 
     it('updateStorage should update any key', () => {
@@ -212,7 +213,7 @@ describe('BlockStorage', () => {
         const storage = createBlockStorage('old');
         const result = defaultBlockStorageHandlers.transformStateForStorage(storage, 'new');
         expect(result.__data).toBe('new');
-        expect(result.__dataVersion).toBe(1);
+        expect(result.__dataVersion).toBe(DATA_MODEL_DEFAULT_VERSION);
       });
 
       it('deriveStateForArgs should return data directly', () => {
@@ -222,8 +223,8 @@ describe('BlockStorage', () => {
 
       it('migrateStorage should update version only', () => {
         const storage = createBlockStorage({ data: 'test' });
-        const result = defaultBlockStorageHandlers.migrateStorage(storage, 1, 3);
-        expect(result.__dataVersion).toBe(3);
+        const result = defaultBlockStorageHandlers.migrateStorage(storage, 'v1', 'v3');
+        expect(result.__dataVersion).toBe('v3');
         expect(result.__data).toEqual({ data: 'test' });
       });
     });
@@ -242,7 +243,7 @@ describe('BlockStorage', () => {
         const customTransform = <T>(storage: ReturnType<typeof createBlockStorage<T>>, data: T) => ({
           ...storage,
           __data: data,
-          __dataVersion: storage.__dataVersion + 1,
+          __dataVersion: `${storage.__dataVersion}-next`,
         });
 
         const handlers = mergeBlockStorageHandlers({

package/src/block_storage.ts

@@ -25,6 +25,12 @@ export const BLOCK_STORAGE_KEY = '__pl_a7f3e2b9__';
  */
 export const BLOCK_STORAGE_SCHEMA_VERSION = 'v1';
 
+/**
+ * Default data version for new blocks without migrations.
+ * Unique identifier ensures blocks are created via DataModel API.
+ */
+export const DATA_MODEL_DEFAULT_VERSION = '__pl_v1_d4e8f2a1__';
+
 /**
  * Type for valid schema versions
  */
@@ -38,7 +44,7 @@ export type PluginKey = `@plugin/${string}`;
 /**
  * Core BlockStorage type that holds:
  * - __pl_a7f3e2b9__: Schema version (discriminator key identifies BlockStorage format)
- * - __dataVersion: Version number for block data migrations
+ * - __dataVersion: Version key for block data migrations
  * - __data: The block's user-facing data (state)
  * - @plugin/*: Optional plugin-specific data
  */
@@ -46,7 +52,7 @@ export type BlockStorage<TState = unknown> = {
   /** Schema version - the key itself is the discriminator */
   readonly [BLOCK_STORAGE_KEY]: BlockStorageSchemaVersion;
   /** Version of the block data, used for migrations */
-  __dataVersion: number;
+  __dataVersion: string;
   /** The block's user-facing data (state) */
   __data: TState;
 } & {
@@ -74,12 +80,12 @@ export function isBlockStorage(value: unknown): value is BlockStorage {
  * Creates a BlockStorage with the given initial data
  *
  * @param initialData - The initial data value (defaults to empty object)
- * @param version - The initial data version (defaults to 1)
+ * @param version - The initial data version key (defaults to DATA_MODEL_DEFAULT_VERSION)
  * @returns A new BlockStorage instance with discriminator key
  */
 export function createBlockStorage<TState = unknown>(
   initialData: TState = {} as TState,
-  version: number = 1,
+  version: string = DATA_MODEL_DEFAULT_VERSION,
 ): BlockStorage<TState> {
   return {
     [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,
@@ -98,10 +104,17 @@ export function createBlockStorage<TState = unknown>(
  */
 export function normalizeBlockStorage<TState = unknown>(raw: unknown): BlockStorage<TState> {
   if (isBlockStorage(raw)) {
-    return raw as BlockStorage<TState>;
+    const storage = raw as BlockStorage<TState>;
+    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 as TState, 1);
+  return createBlockStorage(raw as TState);
 }
 
 // =============================================================================
@@ -163,9 +176,9 @@ export function updateStorageData<TValue = unknown>(
  * Gets the data version from BlockStorage
  *
  * @param storage - The BlockStorage instance
- * @returns The data version number
+ * @returns The data version key
  */
-export function getStorageDataVersion(storage: BlockStorage): number {
+export function getStorageDataVersion(storage: BlockStorage): string {
   return storage.__dataVersion;
 }
 
@@ -173,12 +186,12 @@ export function getStorageDataVersion(storage: BlockStorage): number {
  * Updates the data version in BlockStorage (immutable)
  *
  * @param storage - The current BlockStorage
- * @param version - The new version number
+ * @param version - The new version key
  * @returns A new BlockStorage with updated version
  */
 export function updateStorageDataVersion<TState>(
   storage: BlockStorage<TState>,
-  version: number,
+  version: string,
 ): BlockStorage<TState> {
   return { ...storage, __dataVersion: version };
 }
@@ -188,8 +201,8 @@ export function updateStorageDataVersion<TState>(
  * Used by developer tools to display block storage info.
  */
 export interface StorageDebugView {
-  /** Current data version (1-based, starts at 1) */
-  dataVersion: number;
+  /** Current data version key */
+  dataVersion: string;
   /** Raw data payload stored in BlockStorage */
   data: unknown;
 }
@@ -337,8 +350,8 @@ export interface BlockStorageHandlers<TState = unknown> {
    */
   migrateStorage?: (
     oldStorage: BlockStorage<TState>,
-    fromVersion: number,
-    toVersion: number,
+    fromVersion: string,
+    toVersion: string,
   ) => BlockStorage<TState>;
 }
 
@@ -355,8 +368,8 @@ export const defaultBlockStorageHandlers: Required<BlockStorageHandlers<unknown>
 
   migrateStorage: <TState>(
     storage: BlockStorage<TState>,
-    _fromVersion: number,
-    toVersion: number,
+    _fromVersion: string,
+    toVersion: string,
   ): BlockStorage<TState> => updateStorageDataVersion(storage, toVersion),
 };
 

package/src/block_storage_vm.ts

@@ -14,7 +14,7 @@
  *
  * Callbacks registered by DataModel.registerCallbacks():
  * - `__pl_data_initial`: () => initial data
- * - `__pl_data_upgrade`: (versioned) => UpgradeResult
+ * - `__pl_data_upgrade`: (versioned) => DataMigrationResult
  * - `__pl_storage_initial`: () => initial BlockStorage as JSON string
  *
  * @module block_storage_vm
@@ -30,6 +30,7 @@ import {
   createBlockStorage,
   getStorageData,
   isBlockStorage,
+  normalizeBlockStorage,
   updateStorageData,
 } from './block_storage';
 import { stringifyJson, type StringifiedJson } from '@milaboratories/pl-model-common';
@@ -76,7 +77,8 @@ function normalizeStorage(rawStorage: unknown): NormalizeStorageResult {
 
   // Check for BlockStorage format (has discriminator)
   if (isBlockStorage(parsed)) {
-    return { storage: parsed, data: getStorageData(parsed) };
+    const storage = normalizeBlockStorage(parsed);
+    return { storage, data: getStorageData(storage) };
   }
 
   // Check for legacy V1/V2 format: { args, uiState }
@@ -165,15 +167,15 @@ export type MigrationResult =
   | { error: string }
   | { error?: undefined; newStorageJson: string; info: string; warn?: string };
 
-/** Result from Migrator.upgrade() */
-interface UpgradeResult {
-  version: number;
+/** Result from DataModel.migrate() */
+interface DataMigrationResult {
+  version: string;
   data: unknown;
   warning?: string;
 }
 
 /**
- * Runs storage migration using the DataModel's upgrade callback.
+ * Runs storage migration using the DataModel's migrate callback.
  * This is the main entry point for the middle layer to trigger migrations.
  *
  * Uses the '__pl_data_upgrade' callback registered by DataModel.registerCallbacks() which:
@@ -195,7 +197,7 @@ function migrateStorage(currentStorageJson: string | undefined): MigrationResult
   const currentVersion = currentStorage.__dataVersion;
 
   // Helper to create storage with given data and version
-  const createStorageJson = (data: unknown, version: number): string => {
+  const createStorageJson = (data: unknown, version: string): string => {
     return JSON.stringify({
       ...currentStorage,
       __dataVersion: version,
@@ -203,27 +205,27 @@ function migrateStorage(currentStorageJson: string | undefined): MigrationResult
     });
   };
 
-  // Get the upgrade callback (registered by DataModel.registerCallbacks())
-  const upgradeCallback = ctx.callbackRegistry['__pl_data_upgrade'] as ((v: { version: number; data: unknown }) => UpgradeResult) | undefined;
-  if (typeof upgradeCallback !== 'function') {
+  // Get the migrate callback (registered by DataModel.registerCallbacks())
+  const migrateCallback = ctx.callbackRegistry['__pl_data_upgrade'] as ((v: { version: string; data: unknown }) => DataMigrationResult) | undefined;
+  if (typeof migrateCallback !== 'function') {
     return { error: '__pl_data_upgrade callback not found (DataModel not registered)' };
   }
 
-  // Call the migrator's upgrade function
-  let result: UpgradeResult;
+  // Call the migrator's migrate function
+  let result: DataMigrationResult;
   try {
-    result = upgradeCallback({ version: currentVersion, data: currentData });
+    result = migrateCallback({ version: currentVersion, data: currentData });
   } catch (e) {
     const errorMsg = e instanceof Error ? e.message : String(e);
-    return { error: `upgrade() threw: ${errorMsg}` };
+    return { error: `migrate() threw: ${errorMsg}` };
   }
 
   // Build info message
   const info = result.version === currentVersion
-    ? `No migration needed (v${currentVersion})`
+    ? `No migration needed (${currentVersion})`
     : result.warning
-      ? `Reset to initial data (v${result.version})`
-      : `Migrated v${currentVersion}→v${result.version}`;
+      ? `Reset to initial data (${result.version})`
+      : `Migrated ${currentVersion}→${result.version}`;
 
   return {
     newStorageJson: createStorageJson(result.data, result.version),

package/src/index.ts

@@ -3,7 +3,15 @@ export * from './block_state_util';
 export * from './block_storage';
 export * from './builder';
 export { BlockModelV3 } from './block_model';
-export { DataModel } from './block_migrations';
+export {
+  DataModel,
+  DataModelBuilder,
+  DataUnrecoverableError,
+  isDataUnrecoverableError,
+  defineDataVersions,
+  defaultRecover,
+  makeDataVersioned,
+} from './block_migrations';
 export * from './bconfig';
 export * from './components';
 export * from './config';