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

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.6 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 2.8s
 
 ./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 4.8s
 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.6 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.6 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,20 @@
 # @milaboratories/milaboratories.pool-explorer.model
 
+## 1.1.6
+
+### Patch Changes
+
+- f459e5a: Refined DataModel
+- Updated dependencies [f459e5a]
+  - @platforma-sdk/model@1.53.3
+
+## 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.3";
 
     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;
@@ -7810,7 +7816,14 @@
          * Creates a new BlockModelV3 builder with the specified data model and options.
          *
          * @example
-         * const dataModel = DataModel.create<BlockData>(() => ({ numbers: [], labels: [] }));
+         * const Version = defineDataVersions({ V1: DATA_MODEL_DEFAULT_VERSION });
+         *
+         * type VersionedData = { [Version.V1]: BlockData };
+         *
+         * const dataModel = new DataModelBuilder<VersionedData>()
+         *   .from(Version.V1)
+         *   .init(() => ({ numbers: [], labels: [] }));
+         *
          * BlockModelV3.create({ dataModel })
          *   .args((data) => ({ numbers: data.numbers }))
          *   .sections(() => [{ type: 'link', href: '/', label: 'Main' }])
@@ -7842,7 +7855,11 @@
                 ...this.config,
                 outputs: {
                     ...this.config.outputs,
-                    [key]: createAndRegisterRenderLambda({ handle: `output#${key}`, lambda: () => cfgOrRf(new RenderCtx()), ...flags }),
+                    [key]: createAndRegisterRenderLambda({
+                        handle: `output#${key}`,
+                        lambda: () => cfgOrRf(new RenderCtx()),
+                        ...flags,
+                    }),
                 },
             });
         }
@@ -7896,7 +7913,10 @@
         prerunArgs(fn) {
             return new BlockModelV3({
                 ...this.config,
-                prerunArgs: createAndRegisterRenderLambda({ handle: 'prerunArgs', lambda: fn }),
+                prerunArgs: createAndRegisterRenderLambda({
+                    handle: 'prerunArgs',
+                    lambda: fn,
+                }),
             });
         }
         /** Sets the lambda to generate list of sections in the left block overviews panel. */
@@ -7911,19 +7931,28 @@
         title(rf) {
             return new BlockModelV3({
                 ...this.config,
-                title: createAndRegisterRenderLambda({ handle: 'title', lambda: () => rf(new RenderCtx()) }),
+                title: createAndRegisterRenderLambda({
+                    handle: 'title',
+                    lambda: () => rf(new RenderCtx()),
+                }),
             });
         }
         subtitle(rf) {
             return new BlockModelV3({
                 ...this.config,
-                subtitle: createAndRegisterRenderLambda({ handle: 'subtitle', lambda: () => rf(new RenderCtx()) }),
+                subtitle: createAndRegisterRenderLambda({
+                    handle: 'subtitle',
+                    lambda: () => rf(new RenderCtx()),
+                }),
             });
         }
         tags(rf) {
             return new BlockModelV3({
                 ...this.config,
-                tags: createAndRegisterRenderLambda({ handle: 'tags', lambda: () => rf(new RenderCtx()) }),
+                tags: createAndRegisterRenderLambda({
+                    handle: 'tags',
+                    lambda: () => rf(new RenderCtx()),
+                }),
             });
         }
         /** Sets or overrides feature flags for the block. */
@@ -7940,7 +7969,10 @@
         enriches(lambda) {
             return new BlockModelV3({
                 ...this.config,
-                enrichmentTargets: createAndRegisterRenderLambda({ handle: 'enrichmentTargets', lambda: lambda }),
+                enrichmentTargets: createAndRegisterRenderLambda({
+                    handle: 'enrichmentTargets',
+                    lambda: lambda,
+                }),
             });
         }
         /** Renders all provided block settings into a pre-configured platforma API
@@ -7980,7 +8012,10 @@
                 sdkVersion: PlatformaSDKVersion,
                 renderingMode: this.config.renderingMode,
                 sections: this.config.sections,
-                outputs: Object.fromEntries(Object.entries(this.config.outputs).map(([key, value]) => [key, downgradeCfgOrLambda(value)])),
+                outputs: Object.fromEntries(Object.entries(this.config.outputs).map(([key, value]) => [
+                    key,
+                    downgradeCfgOrLambda(value),
+                ])),
             };
             globalThis.platformaApiVersion = apiVersion;
             if (!isInUI())
@@ -7989,17 +8024,55 @@
             // normal operation inside the UI
             else
                 return {
-                    ...getPlatformaInstance({ sdkVersion: PlatformaSDKVersion, apiVersion }),
+                    ...getPlatformaInstance({
+                        sdkVersion: PlatformaSDKVersion,
+                        apiVersion,
+                    }),
                     blockModelInfo: {
-                        outputs: Object.fromEntries(Object.entries(this.config.outputs)
-                            .map(([key, value]) => [key, {
+                        outputs: Object.fromEntries(Object.entries(this.config.outputs).map(([key, value]) => [
+                            key,
+                            {
                                 withStatus: Boolean(isConfigLambda(value) && value.withStatus),
-                            }])),
+                            },
+                        ])),
                     },
                 };
         }
     }
 
+    /**
+     * 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 or empty version values are found
+     *
+     * @example
+     * const Version = defineDataVersions({
+     *   Initial: 'v1',
+     *   AddedLabels: 'v2',
+     * });
+     *
+     * type VersionedData = {
+     *   [Version.Initial]: DataV1;
+     *   [Version.AddedLabels]: DataV2;
+     * };
+     */
+    function defineDataVersions(versions) {
+        const values = Object.values(versions);
+        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(', ')})`);
+        }
+        const unique = new Set(values);
+        if (unique.size !== values.length) {
+            const duplicates = values.filter((v, i) => values.indexOf(v) !== i);
+            throw new Error(`Duplicate version values: ${[...new Set(duplicates)].join(', ')}`);
+        }
+        return versions;
+    }
     /** Create a DataVersioned wrapper with correct shape */
     function makeDataVersioned(version, data) {
         return { version, data };
@@ -8014,56 +8087,228 @@
     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,
+            });
         }
-        /** Add a migration step to the target version */
+    }
+    /**
+     * 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 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]);
+            const step = {
+                fromVersion,
+                toVersion: nextVersion,
+                migrate: fn,
+            };
+            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 with initial data, creating the DataModel */
-        create(initialData, ..._) {
-            return DataModel._fromBuilder(this.versionChain, this.migrationSteps, initialData, this.recoverFn);
+        /**
+         * 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,
+            });
+        }
+    }
+    /**
+     * 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.
      *
+     * Use `new DataModelBuilder<VersionedData>()` to create a DataModel:
+     *
+     * **Simple (no migrations):**
      * @example
-     * // Simple data model (no migrations)
-     * const dataModel = DataModel.create<BlockData>(() => ({
-     *   numbers: [],
-     *   labels: [],
-     * }));
+     * const Version = defineDataVersions({ V1: DATA_MODEL_DEFAULT_VERSION });
+     * type VersionedData = { [Version.V1]: BlockData };
+     *
+     * const dataModel = new DataModelBuilder<VersionedData>()
+     *   .from(Version.V1)
+     *   .init(() => ({ numbers: [], labels: [] }));
      *
-     * // Data model with migrations
+     * **With migrations:**
+     * @example
      * const Version = defineDataVersions({
-     *   V1: 'v1',
+     *   V1: DATA_MODEL_DEFAULT_VERSION,
      *   V2: 'v2',
      *   V3: 'v3',
      * });
@@ -8074,8 +8319,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 +8329,52 @@
      *     }
      *     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);
-        }
-        /** Create a data model with just initial data (no migrations) */
-        static create(initialData, version = DATA_MODEL_DEFAULT_VERSION) {
-            return new DataModel([version], [], initialData);
+            this.initialDataFn = initialDataFn;
+            this.recoverFn = recoverFn;
         }
-        /** 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 +8395,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 +8433,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);
@@ -8275,7 +8526,10 @@
         errors: z.lazy(() => ErrorShape.array()).optional(),
     });
 
-    const dataModel = DataModel.create(() => ({ titleArgs: 'The title' }));
+    const Version = defineDataVersions({ V1: DATA_MODEL_DEFAULT_VERSION });
+    const dataModel = new DataModelBuilder()
+        .from(Version.V1)
+        .init(() => ({ titleArgs: 'The title' }));
     const platforma = BlockModelV3.create({ dataModel, renderingMode: 'Heavy' })
         .args((data) => {
         return { titleArgs: data.titleArgs };