@milaboratories/milaboratories.pool-explorer.model 1.1.3 → 1.1.4

package/.turbo/turbo-build.log

@@ -1,16 +1,16 @@
  WARN  Issue while reading "/home/runner/_work/platforma/platforma/.npmrc". Failed to replace env in config: ${NPMJS_TOKEN}
 
-> @milaboratories/milaboratories.pool-explorer.model@1.1.3 build /home/runner/_work/platforma/platforma/etc/blocks/pool-explorer/model
+> @milaboratories/milaboratories.pool-explorer.model@1.1.4 build /home/runner/_work/platforma/platforma/etc/blocks/pool-explorer/model
 > ts-builder build --target block-model && block-tools build-model
 
 Building block-model project...
 ↳ rollup -c /configs/rollup.block-model.config.js
 
 ./src/index.ts → dist, dist...
-created dist, dist in 2.3s
+created dist, dist in 2.4s
 
 ./src/index.ts → dist...
 (!) Circular dependency
 ../../../../sdk/model/dist/components/PFrameForGraphs.js -> ../../../../sdk/model/dist/pframe_utils/columns.js -> ../../../../sdk/model/dist/components/PFrameForGraphs.js
-created dist in 3.6s
+created dist in 3.7s
 Build completed successfully

package/.turbo/turbo-lint.log

@@ -1,5 +1,5 @@
  WARN  Issue while reading "/home/runner/_work/platforma/platforma/.npmrc". Failed to replace env in config: ${NPMJS_TOKEN}
 
-> @milaboratories/milaboratories.pool-explorer.model@1.1.3 lint /home/runner/_work/platforma/platforma/etc/blocks/pool-explorer/model
+> @milaboratories/milaboratories.pool-explorer.model@1.1.4 lint /home/runner/_work/platforma/platforma/etc/blocks/pool-explorer/model
 > eslint .
 

package/.turbo/turbo-type-check.log

@@ -1,6 +1,6 @@
  WARN  Issue while reading "/home/runner/_work/platforma/platforma/.npmrc". Failed to replace env in config: ${NPMJS_TOKEN}
 
-> @milaboratories/milaboratories.pool-explorer.model@1.1.3 type-check /home/runner/_work/platforma/platforma/etc/blocks/pool-explorer/model
+> @milaboratories/milaboratories.pool-explorer.model@1.1.4 type-check /home/runner/_work/platforma/platforma/etc/blocks/pool-explorer/model
 > ts-builder types --target block-model
 
 ↳ tsc --noEmit --project ./tsconfig.json --customConditions ,

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @milaboratories/milaboratories.pool-explorer.model
 
+## 1.1.4
+
+### Patch Changes
+
+- Updated dependencies [a748b92]
+  - @platforma-sdk/model@1.53.1
+
 ## 1.1.3
 
 ### Patch Changes

package/dist/bundle.js

@@ -27,6 +27,11 @@
      * Increment this when the storage structure itself changes (not block state migrations).
      */
     const BLOCK_STORAGE_SCHEMA_VERSION = 'v1';
+    /**
+     * Default data version for new blocks without migrations.
+     * Unique identifier ensures blocks are created via DataModel API.
+     */
+    const DATA_MODEL_DEFAULT_VERSION = '__pl_v1_d4e8f2a1__';
     /**
      * Type guard to check if a value is a valid BlockStorage object.
      * Checks for the discriminator key and valid schema version.
@@ -46,16 +51,32 @@
      * 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
      */
-    function createBlockStorage(initialData = {}, version = 1) {
+    function createBlockStorage(initialData = {}, version = DATA_MODEL_DEFAULT_VERSION) {
         return {
             [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,
             __dataVersion: version,
             __data: initialData,
         };
     }
+    /**
+     * Normalizes raw storage data to BlockStorage format.
+     * If the input is already a BlockStorage, returns it as-is.
+     * If the input is legacy format (raw state), wraps it in BlockStorage structure.
+     *
+     * @param raw - Raw storage data (may be legacy format or BlockStorage)
+     * @returns Normalized BlockStorage
+     */
+    function normalizeBlockStorage(raw) {
+        if (isBlockStorage(raw)) {
+            const storage = raw;
+            return { ...storage, __dataVersion: String(storage.__dataVersion) };
+        }
+        // Legacy format: raw is the state directly
+        return createBlockStorage(raw);
+    }
     // =============================================================================
     // Data Access & Update Functions
     // =============================================================================
@@ -7502,7 +7523,7 @@
         }
     }
 
-    var version = "1.53.0";
+    var version = "1.53.1";
 
     const PlatformaSDKVersion = version;
 
@@ -7534,7 +7555,7 @@
      *
      * Callbacks registered by DataModel.registerCallbacks():
      * - `__pl_data_initial`: () => initial data
-     * - `__pl_data_upgrade`: (versioned) => UpgradeResult
+     * - `__pl_data_migrate`: (versioned) => DataMigrationResult
      * - `__pl_storage_initial`: () => initial BlockStorage as JSON string
      *
      * @module block_storage_vm
@@ -7570,7 +7591,8 @@
         }
         // 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 }
         if (isLegacyModelV1ApiFormat(parsed)) {
@@ -7635,10 +7657,10 @@
         return getStorageDebugView(rawStorage);
     });
     /**
-     * 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:
+     * Uses the '__pl_data_migrate' callback registered by DataModel.registerCallbacks() which:
      * - Handles all migration logic internally
      * - Returns { version, data, warning? } - warning present if reset to initial data
      *
@@ -7662,26 +7684,26 @@
                 __data: data,
             });
         };
-        // Get the upgrade callback (registered by DataModel.registerCallbacks())
-        const upgradeCallback = ctx.callbackRegistry['__pl_data_upgrade'];
-        if (typeof upgradeCallback !== 'function') {
-            return { error: '__pl_data_upgrade callback not found (DataModel not registered)' };
+        // Get the migrate callback (registered by DataModel.registerCallbacks())
+        const migrateCallback = ctx.callbackRegistry['__pl_data_migrate'];
+        if (typeof migrateCallback !== 'function') {
+            return { error: '__pl_data_migrate callback not found (DataModel not registered)' };
         }
-        // Call the migrator's upgrade function
+        // Call the migrator's migrate function
         let result;
         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),
             info,
@@ -7978,23 +8000,54 @@
         }
     }
 
+    /** Create a DataVersioned wrapper with correct shape */
+    function makeDataVersioned(version, data) {
+        return { version, data };
+    }
+    /** Thrown by recover() to signal unrecoverable data. */
+    class DataUnrecoverableError extends Error {
+        name = 'DataUnrecoverableError';
+        constructor(dataVersion) {
+            super(`Unknown version '${dataVersion}'`);
+        }
+    }
+    function isDataUnrecoverableError(error) {
+        return error instanceof Error && error.name === 'DataUnrecoverableError';
+    }
+    /** Default recover function for unknown versions */
+    const defaultRecover = (version, _data) => {
+        throw new DataUnrecoverableError(version);
+    };
     /** Internal builder for chaining migrations */
     class DataModelBuilder {
+        versionChain;
         migrationSteps;
-        constructor(steps = []) {
+        recoverFn;
+        constructor(versionChain, steps = [], recoverFn) {
+            this.versionChain = versionChain;
             this.migrationSteps = steps;
+            this.recoverFn = recoverFn;
         }
-        /** Start a migration chain from an initial type */
-        static from() {
-            return new DataModelBuilder();
+        /** Start a migration chain from an initial version */
+        static from(initialVersion) {
+            return new DataModelBuilder([initialVersion]);
         }
-        /** Add a migration step */
-        migrate(fn) {
-            return new DataModelBuilder([...this.migrationSteps, fn]);
+        /** Add a migration step to the target version */
+        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]);
+        }
+        /** Set recovery handler for unknown or unsupported versions */
+        recover(fn) {
+            return new DataModelBuilder([...this.versionChain], [...this.migrationSteps], fn);
         }
         /** Finalize with initial data, creating the DataModel */
         create(initialData, ..._) {
-            return DataModel._fromBuilder(this.migrationSteps, initialData);
+            return DataModel._fromBuilder(this.versionChain, this.migrationSteps, initialData, this.recoverFn);
         }
     }
     /**
@@ -8009,37 +8062,61 @@
      * }));
      *
      * // Data model with migrations
+     * const Version = defineDataVersions({
+     *   V1: 'v1',
+     *   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 = DataModel
-     *   .from<V1>()
-     *   .migrate((data) => ({ ...data, labels: [] }))  // v1 → v2
-     *   .migrate((data) => ({ ...data, description: '' }))  // v2 → v3
-     *   .create<BlockData>(() => ({ numbers: [], labels: [], description: '' }));
+     *   .from<VersionedData>(Version.V1)
+     *   .migrate(Version.V2, (data) => ({ ...data, labels: [] }))
+     *   .migrate(Version.V3, (data) => ({ ...data, description: '' }))
+     *   .recover((version, data) => {
+     *     if (version === 'legacy' && typeof data === 'object' && data !== null && 'numbers' in data) {
+     *       return { numbers: (data as { numbers: number[] }).numbers, labels: [], description: '' };
+     *     }
+     *     return defaultRecover(version, data);
+     *   })
+     *   .create(() => ({ numbers: [], labels: [], description: '' }));
      */
     class DataModel {
+        versionChain;
         steps;
-        _initialData;
-        constructor(steps, initialData) {
+        initialDataFn;
+        recoverFn;
+        constructor(versionChain, steps, initialData, recover = defaultRecover) {
+            if (versionChain.length === 0) {
+                throw new Error('DataModel requires at least one version key');
+            }
+            this.versionChain = versionChain;
             this.steps = steps;
-            this._initialData = initialData;
+            this.initialDataFn = initialData;
+            this.recoverFn = recover;
         }
         /** Start a migration chain from an initial type */
-        static from() {
-            return DataModelBuilder.from();
+        static from(initialVersion) {
+            return DataModelBuilder.from(initialVersion);
         }
         /** Create a data model with just initial data (no migrations) */
-        static create(initialData) {
-            return new DataModel([], initialData);
+        static create(initialData, version = DATA_MODEL_DEFAULT_VERSION) {
+            return new DataModel([version], [], initialData);
         }
         /** Create from builder (internal use) */
-        static _fromBuilder(steps, initialData) {
-            return new DataModel(steps, initialData);
+        static _fromBuilder(versionChain, steps, initialData, recover) {
+            return new DataModel(versionChain, steps, initialData, recover);
         }
         /**
-         * Latest version number.
-         * Version 1 = initial state, each migration adds 1.
+         * Latest version key.
          */
         get version() {
-            return this.steps.length + 1;
+            return this.versionChain[this.versionChain.length - 1];
         }
         /** Number of migration steps */
         get migrationCount() {
@@ -8047,43 +8124,52 @@
         }
         /** Get initial data */
         initialData() {
-            return this._initialData();
+            return this.initialDataFn();
         }
         /** Get default data wrapped with current version */
         getDefaultData() {
-            return { version: this.version, data: this._initialData() };
+            return makeDataVersioned(this.version, this.initialDataFn());
+        }
+        recoverFrom(data, version) {
+            try {
+                return { version: this.version, data: this.recoverFn(version, data) };
+            }
+            catch (error) {
+                if (isDataUnrecoverableError(error)) {
+                    return { ...this.getDefaultData(), warning: error.message };
+                }
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                return {
+                    ...this.getDefaultData(),
+                    warning: `Recover failed for version '${version}': ${errorMessage}`,
+                };
+            }
         }
         /**
-         * Upgrade versioned data from any version to the latest.
+         * 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.
          */
-        upgrade(versioned) {
+        migrate(versioned) {
             const { version: fromVersion, data } = versioned;
-            if (fromVersion > this.version) {
-                throw new Error(`Cannot downgrade from version ${fromVersion} to ${this.version}`);
-            }
             if (fromVersion === this.version) {
                 return { version: this.version, data: data };
             }
-            // Apply migrations starting from (fromVersion - 1) index
-            // Version 1 -> no migrations applied yet -> start at index 0
-            // Version 2 -> migration[0] already applied -> start at index 1
-            const startIndex = fromVersion - 1;
-            const migrationsToApply = this.steps.slice(startIndex);
+            const startIndex = this.versionChain.indexOf(fromVersion);
+            if (startIndex < 0) {
+                return this.recoverFrom(data, fromVersion);
+            }
             let currentData = data;
-            for (let i = 0; i < migrationsToApply.length; i++) {
-                const stepIndex = startIndex + i;
-                const fromVer = stepIndex + 1;
-                const toVer = stepIndex + 2;
+            for (let i = startIndex; i < this.steps.length; i++) {
+                const step = this.steps[i];
                 try {
-                    currentData = migrationsToApply[i](currentData);
+                    currentData = step.migrate(currentData);
                 }
                 catch (error) {
                     const errorMessage = error instanceof Error ? error.message : String(error);
                     return {
                         ...this.getDefaultData(),
-                        warning: `Migration v${fromVer}→v${toVer} failed: ${errorMessage}`,
+                        warning: `Migration ${step.fromVersion}→${step.toVersion} failed: ${errorMessage}`,
                     };
                 }
             }
@@ -8095,12 +8181,12 @@
          *
          * All callbacks are prefixed with `__pl_` to indicate internal SDK use:
          * - `__pl_data_initial`: returns initial data for new blocks
-         * - `__pl_data_upgrade`: upgrades versioned data from any version to latest
+         * - `__pl_data_migrate`: migrates versioned data from any version to latest
          * - `__pl_storage_initial`: returns initial BlockStorage as JSON string
          */
         registerCallbacks() {
-            tryRegisterCallback('__pl_data_initial', () => this._initialData());
-            tryRegisterCallback('__pl_data_upgrade', (versioned) => this.upgrade(versioned));
+            tryRegisterCallback('__pl_data_initial', () => this.initialDataFn());
+            tryRegisterCallback('__pl_data_migrate', (versioned) => this.migrate(versioned));
             tryRegisterCallback('__pl_storage_initial', () => {
                 const { version, data } = this.getDefaultData();
                 const storage = createBlockStorage(data, version);