@milaboratories/milaboratories.pool-explorer.model 1.1.4 → 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.4 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.4s
+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.7s
+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.4 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.4 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,12 @@
 # @milaboratories/milaboratories.pool-explorer.model
 
+## 1.1.5
+
+### Patch Changes
+
+- Updated dependencies [57799dd]
+  - @platforma-sdk/model@1.53.2
+
 ## 1.1.4
 
 ### Patch Changes

package/dist/bundle.js

@@ -72,7 +72,13 @@
     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);
@@ -7523,7 +7529,7 @@
         }
     }
 
-    var version = "1.53.1";
+    var version = "1.53.2";
 
     const PlatformaSDKVersion = version;
 
@@ -7555,7 +7561,7 @@
      *
      * Callbacks registered by DataModel.registerCallbacks():
      * - `__pl_data_initial`: () => initial data
-     * - `__pl_data_migrate`: (versioned) => DataMigrationResult
+     * - `__pl_data_upgrade`: (versioned) => DataMigrationResult
      * - `__pl_storage_initial`: () => initial BlockStorage as JSON string
      *
      * @module block_storage_vm
@@ -7660,7 +7666,7 @@
      * 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_migrate' callback registered by DataModel.registerCallbacks() which:
+     * Uses the '__pl_data_upgrade' callback registered by DataModel.registerCallbacks() which:
      * - Handles all migration logic internally
      * - Returns { version, data, warning? } - warning present if reset to initial data
      *
@@ -7685,9 +7691,9 @@
             });
         };
         // Get the migrate callback (registered by DataModel.registerCallbacks())
-        const migrateCallback = ctx.callbackRegistry['__pl_data_migrate'];
+        const migrateCallback = ctx.callbackRegistry['__pl_data_upgrade'];
         if (typeof migrateCallback !== 'function') {
-            return { error: '__pl_data_migrate callback not found (DataModel not registered)' };
+            return { error: '__pl_data_upgrade callback not found (DataModel not registered)' };
         }
         // Call the migrator's migrate function
         let result;
@@ -8014,54 +8020,38 @@
     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 {
-        versionChain;
-        migrationSteps;
-        recoverFn;
-        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]);
-        }
-        /** 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.versionChain, this.migrationSteps, initialData, this.recoverFn);
-        }
-    }
+    /** 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
+     * 2. **With migrations** - Use `new DataModelBuilder<VersionedData>()`:
+     * @example
      * const Version = defineDataVersions({
      *   V1: 'v1',
      *   V2: 'v2',
@@ -8074,8 +8064,8 @@
      *   [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) => {
@@ -8084,49 +8074,76 @@
      *     }
      *     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());
         }
@@ -8147,8 +8164,14 @@
         }
         /**
          * 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;
@@ -8179,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_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);