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

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.5 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 1.7s
 
 ./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.4s
 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.5 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.5 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,19 @@
 # @milaboratories/milaboratories.pool-explorer.model
 
+## 1.1.5
+
+### Patch Changes
+
+- Updated dependencies [57799dd]
+  - @platforma-sdk/model@1.53.2
+
+## 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,38 @@
      * 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,
+                // 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);
+    }
     // =============================================================================
     // Data Access & Update Functions
     // =============================================================================
@@ -7502,7 +7529,7 @@
         }
     }
 
-    var version = "1.53.0";
+    var version = "1.53.2";
 
     const PlatformaSDKVersion = version;
 
@@ -7534,7 +7561,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
@@ -7570,7 +7597,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,7 +7663,7 @@
         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:
@@ -7662,26 +7690,26 @@
                 __data: data,
             });
         };
-        // Get the upgrade callback (registered by DataModel.registerCallbacks())
-        const upgradeCallback = ctx.callbackRegistry['__pl_data_upgrade'];
-        if (typeof upgradeCallback !== 'function') {
+        // Get the migrate callback (registered by DataModel.registerCallbacks())
+        const migrateCallback = ctx.callbackRegistry['__pl_data_upgrade'];
+        if (typeof migrateCallback !== 'function') {
             return { error: '__pl_data_upgrade 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,112 +8006,193 @@
         }
     }
 
-    /** Internal builder for chaining migrations */
-    class DataModelBuilder {
-        migrationSteps;
-        constructor(steps = []) {
-            this.migrationSteps = steps;
-        }
-        /** Start a migration chain from an initial type */
-        static from() {
-            return new DataModelBuilder();
-        }
-        /** Add a migration step */
-        migrate(fn) {
-            return new DataModelBuilder([...this.migrationSteps, fn]);
-        }
-        /** Finalize with initial data, creating the DataModel */
-        create(initialData, ..._) {
-            return DataModel._fromBuilder(this.migrationSteps, initialData);
+    /** 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.
+     * 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);
+    };
+    /** Symbol for internal builder creation method */
+    const FROM_BUILDER = Symbol('fromBuilder');
     /**
      * 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
-     * const dataModel = DataModel
-     *   .from<V1>()
-     *   .migrate((data) => ({ ...data, labels: [] }))  // v1 → v2
-     *   .migrate((data) => ({ ...data, description: '' }))  // v2 → v3
-     *   .create<BlockData>(() => ({ numbers: [], labels: [], description: '' }));
+     * 2. **With migrations** - Use `new DataModelBuilder<VersionedData>()`:
+     * @example
+     * 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 = new DataModelBuilder<VersionedData>()
+     *   .from(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);
+     *   })
+     *   .init(() => ({ numbers: [], labels: [], description: '' }));
      */
     class DataModel {
+        versionChain;
         steps;
-        _initialData;
-        constructor(steps, initialData) {
+        initialDataFn;
+        recoverFn;
+        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._initialData = initialData;
-        }
-        /** Start a migration chain from an initial type */
-        static from() {
-            return DataModelBuilder.from();
+            this.initialDataFn = initialDataFn;
+            this.recoverFn = recoverFn;
         }
-        /** Create a data model with just initial data (no migrations) */
-        static create(initialData) {
-            return new DataModel([], initialData);
+        /**
+         * 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({
+                versionChain: [version],
+                steps: [],
+                initialDataFn: initialData,
+            });
         }
-        /** Create from builder (internal use) */
-        static _fromBuilder(steps, initialData) {
-            return new DataModel(steps, initialData);
+        /**
+         * 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 number.
-         * Version 1 = initial state, each migration adds 1.
+         * The latest (current) version key in the migration chain.
          */
         get version() {
-            return this.steps.length + 1;
+            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._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 { 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.
-         * Applies only the migrations needed (skips already-applied ones).
-         * If a migration fails, returns default data with a warning.
+         * Migrate versioned data from any version to the latest.
+         *
+         * - If data is already at latest version, returns as-is
+         * - If version is in chain, applies needed migrations
+         * - If version is unknown, calls recover function
+         * - If migration/recovery fails, returns default data with warning
+         *
+         * @param versioned - Data with version tag
+         * @returns Migration result with data at latest version
          */
-        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}`,
                     };
                 }
             }
@@ -8093,14 +8202,11 @@
          * 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_upgrade`: upgrades versioned data from any version to latest
-         * - `__pl_storage_initial`: returns initial BlockStorage as JSON string
+         * @internal
          */
         registerCallbacks() {
-            tryRegisterCallback('__pl_data_initial', () => this._initialData());
-            tryRegisterCallback('__pl_data_upgrade', (versioned) => this.upgrade(versioned));
+            tryRegisterCallback('__pl_data_initial', () => this.initialDataFn());
+            tryRegisterCallback('__pl_data_upgrade', (versioned) => this.migrate(versioned));
             tryRegisterCallback('__pl_storage_initial', () => {
                 const { version, data } = this.getDefaultData();
                 const storage = createBlockStorage(data, version);