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

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.5 build /home/runner/_work/platforma/platforma/etc/blocks/pool-explorer/model
+> @milaboratories/milaboratories.pool-explorer.model@1.1.7 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 1.7s
+created dist, dist in 2s
 
 ./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.4s
+created dist in 2.5s
 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.5 lint /home/runner/_work/platforma/platforma/etc/blocks/pool-explorer/model
+> @milaboratories/milaboratories.pool-explorer.model@1.1.7 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.5 type-check /home/runner/_work/platforma/platforma/etc/blocks/pool-explorer/model
+> @milaboratories/milaboratories.pool-explorer.model@1.1.7 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.7
+
+### Patch Changes
+
+- @platforma-sdk/model@1.53.4
+
+## 1.1.6
+
+### Patch Changes
+
+- f459e5a: Refined DataModel
+- Updated dependencies [f459e5a]
+  - @platforma-sdk/model@1.53.3
+
 ## 1.1.5
 
 ### Patch Changes

package/dist/bundle.js

@@ -7529,7 +7529,7 @@
         }
     }
 
-    var version = "1.53.2";
+    var version = "1.53.4";
 
     const PlatformaSDKVersion = version;
 
@@ -7816,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' }])
@@ -7848,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,
+                    }),
                 },
             });
         }
@@ -7902,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. */
@@ -7917,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. */
@@ -7946,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
@@ -7986,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())
@@ -7995,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 };
@@ -8037,23 +8104,211 @@
     };
     /** 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;
+        /** @internal */
+        constructor({ versionChain, steps, recoverFn, }) {
+            this.versionChain = versionChain;
+            this.migrationSteps = steps;
+            this.recoverFn = recoverFn;
+        }
+        /**
+         * 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,
+            });
+        }
+    }
+    /**
+     * 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 DataModelMigrationChain({
+                versionChain: [...this.versionChain, nextVersion],
+                steps: [...this.migrationSteps, step],
+            });
+        }
+        /**
+         * 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 DataModelBuilderWithRecover({
+                versionChain: [...this.versionChain],
+                steps: [...this.migrationSteps],
+                recoverFn: fn,
+            });
+        }
+        /**
+         * 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.
      *
-     * Two ways to create a DataModel:
+     * Use `new DataModelBuilder<VersionedData>()` to create a DataModel:
      *
-     * 1. **Simple (no migrations)** - Use `DataModel.create()`:
+     * **Simple (no migrations):**
      * @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: [] }));
      *
-     * 2. **With migrations** - Use `new DataModelBuilder<VersionedData>()`:
+     * **With migrations:**
      * @example
      * const Version = defineDataVersions({
-     *   V1: 'v1',
+     *   V1: DATA_MODEL_DEFAULT_VERSION,
      *   V2: 'v2',
      *   V3: 'v3',
      * });
@@ -8090,30 +8345,6 @@
             this.initialDataFn = initialDataFn;
             this.recoverFn = recoverFn;
         }
-        /**
-         * 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,
-            });
-        }
         /**
          * Internal method for creating DataModel from builder.
          * Uses Symbol key to prevent external access.
@@ -8295,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 };