@platforma-sdk/model 1.58.3 → 1.58.9

package/src/block_storage_callbacks.ts

@@ -1,5 +1,5 @@
 /**
- * BlockStorage Callback Implementations - wired to facade callbacks in BlockModelV3._done().
+ * BlockStorage Callback Implementations - wired to facade callbacks in BlockModelV3.done().
  *
  * Provides pure functions for storage operations (migration, initialization,
  * args derivation, updates, debug views). Each function takes its dependencies
@@ -27,7 +27,7 @@ import {
 import type { PluginHandle } from "./plugin_handle";
 
 import { stringifyJson, type StringifiedJson } from "@milaboratories/pl-model-common";
-import type { DataVersioned } from "./block_migrations";
+import type { DataVersioned, TransferRecord } from "./block_migrations";
 
 // =============================================================================
 // Hook interfaces for dependency injection
@@ -35,13 +35,18 @@ import type { DataVersioned } from "./block_migrations";
 
 /** Dependencies for storage migration */
 export interface MigrationHooks {
-  migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown>;
+  migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown> & {
+    transfers: TransferRecord;
+  };
   getPluginRegistry: () => PluginRegistry;
   migratePluginData: (
     handle: PluginHandle,
     versioned: DataVersioned<unknown>,
   ) => DataVersioned<unknown> | undefined;
-  createPluginData: (handle: PluginHandle) => DataVersioned<unknown>;
+  createPluginData: (
+    handle: PluginHandle,
+    transfer?: DataVersioned<unknown>,
+  ) => DataVersioned<unknown>;
 }
 
 /** Dependencies for initial storage creation */

package/src/env_value.ts

@@ -1,5 +1,3 @@
-import {} from "./global";
-
 export function getEnvironmentValue(name: string): string | undefined {
   if (typeof globalThis.getEnvironmentValue !== "function") return undefined;
   else return globalThis.getEnvironmentValue(name);

package/src/filters/distill.ts

@@ -6,6 +6,7 @@ import {
 } from "@milaboratories/pl-model-common";
 import { traverseFilterSpec } from "./traverse";
 import { InferFilterSpecLeaf } from "@milaboratories/pl-model-common";
+import { isEmpty } from "es-toolkit/compat";
 
 /** All possible field names that can appear in any FilterSpecLeaf variant. */
 type FilterSpecLeafKey = DistributiveKeys<FilterSpecLeaf<string>>;
@@ -27,19 +28,29 @@ const KNOWN_LEAF_KEYS_TUPLE: UnionToTuples<FilterSpecLeafKey> = [
 const KNOWN_LEAF_KEYS: Set<FilterSpecLeafKey> = new Set(KNOWN_LEAF_KEYS_TUPLE);
 
 /** Returns true if the leaf is filled — type is defined and no required fields are undefined. */
-function isFilledLeaf(node: Record<string, unknown>): boolean {
+function isFilledLeaf<T>(node: FilterSpecLeaf<T>): boolean {
   if (node.type == null) return false;
-  return !Object.values(node).some((v) => v === undefined);
+  return !Object.values(node).some((value) => {
+    switch (typeof value) {
+      case "number":
+      case "boolean":
+        return false;
+      case "string":
+        return value.trim() === "";
+      default: // undefined, null, empty objects/arrays
+        return isEmpty(value);
+    }
+  });
 }
 
-function distillLeaf(node: Record<string, unknown>): FilterSpecLeaf<string> {
+function distillLeaf<T>(node: FilterSpecLeaf<T>): FilterSpecLeaf<T> {
   const result: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(node)) {
     if (KNOWN_LEAF_KEYS.has(key as FilterSpecLeafKey)) {
       result[key] = value;
     }
   }
-  return result as FilterSpecLeaf<string>;
+  return result as FilterSpecLeaf<T>;
 }
 
 /**
@@ -55,8 +66,8 @@ export function distillFilterSpec<
   if (filter == null) return null;
   return traverseFilterSpec<FS, null | R>(filter, {
     leaf: (leaf) => {
-      if (!isFilledLeaf(leaf as Record<string, unknown>)) return null;
-      return distillLeaf(leaf as Record<string, unknown>) as R;
+      const distilled = distillLeaf(leaf);
+      return isFilledLeaf(distilled) ? (distilled as R) : null;
     },
     and: (results) => {
       const filtered = results.filter((f): f is NonNullable<typeof f> => f !== null);

package/src/index.ts

@@ -25,18 +25,19 @@ export {
 export * from "./block_storage_facade";
 export * from "./block_model_legacy";
 export { BlockModelV3 } from "./block_model";
-export type { PluginInstance, ParamsInput } from "./block_model";
+export type { PluginRecord, ParamsInput } from "./block_model";
+export { DataModel, DataModelBuilder } from "./block_migrations";
 export {
-  DataModel,
-  DataModelBuilder,
-  DataMigrationError,
-  DataUnrecoverableError,
-  isDataUnrecoverableError,
-  defaultRecover,
-  makeDataVersioned,
-} from "./block_migrations";
-export type { LegacyV1State } from "./block_migrations";
-export * from "./plugin_model";
+  type PluginData,
+  type PluginParams,
+  type PluginOutputs,
+  type PluginConfig,
+  PluginDataModel,
+  PluginDataModelBuilder,
+  PluginInstance,
+  PluginModel,
+  type PluginFactory,
+} from "./plugin_model";
 export * from "./bconfig";
 export * from "./components";
 export * from "./config";

package/src/internal.ts

@@ -1,5 +1,4 @@
 import type { OutputWithStatus } from "@milaboratories/pl-model-common";
-import {} from "./global";
 import type { Platforma, PlatformaApiVersion } from "./platforma";
 import type { FutureHandle, GlobalCfgRenderCtx } from "./render/internal";
 import type { ConfigRenderLambda, ConfigRenderLambdaFlags } from "./bconfig";

package/src/platforma.ts

@@ -9,7 +9,7 @@ import type {
 } from "@milaboratories/pl-model-common";
 import type { SdkInfo } from "./version";
 import type { BlockStatePatch } from "./block_state_patch";
-import type { PluginInstance } from "./block_model";
+import type { PluginRecord } from "./block_model";
 import type { PluginHandle, PluginFactoryLike } from "./plugin_handle";
 
 /** Defines all methods to interact with the platform environment from within a block UI. @deprecated */
@@ -134,7 +134,7 @@ export type InferPluginNames<Pl> =
 export type InferPluginData<Pl, PluginId extends string> =
   Pl extends PlatformaV3<unknown, unknown, BlockOutputsBase, `/${string}`, infer P>
     ? PluginId extends keyof P
-      ? P[PluginId] extends PluginInstance<infer D, any, any>
+      ? P[PluginId] extends PluginRecord<infer D, any, any>
         ? D
         : never
       : never
@@ -143,10 +143,10 @@ export type InferPluginData<Pl, PluginId extends string> =
 /**
  * Map each plugin instance to a type-safe opaque handle branded with normalized phantom.
  * Uses the same brand structure as InferPluginHandle — only data/params/outputs, no config —
- * because PluginInstance doesn't carry Config (it's lost after factory.create()).
+ * because PluginRecord doesn't carry Config (lost after factory.create()).
  */
 export type InferPluginHandles<T extends Record<string, unknown>> = {
-  readonly [K in keyof T]: T[K] extends PluginInstance<infer Data, infer Params, infer Outputs>
+  readonly [K in keyof T]: T[K] extends PluginRecord<infer Data, infer Params, infer Outputs>
     ? PluginHandle<PluginFactoryLike<Data, Params, Outputs>>
     : never;
 };

package/src/plugin_handle.ts

@@ -13,7 +13,7 @@ import type { Branded } from "@milaboratories/helpers";
 /**
  * Phantom-only base type for constraining PluginHandle's type parameter.
  *
- * PluginFactory has create() → PluginModel with function properties, making it invariant
+ * PluginFactory has create() → PluginInstance with function properties, making it invariant
  * under strictFunctionTypes. PluginFactoryLike exposes only the covariant `__types` phantom,
  * avoiding the contravariance chain. Handles only need `__types` for type extraction.
  *

package/src/plugin_model.test.ts

@@ -1,14 +1,15 @@
 import { describe, expect, it } from "vitest";
-import { PluginModel } from "./plugin_model";
+import {
+  PluginModel,
+  PluginDataModelBuilder,
+  PluginInstance,
+  CREATE_PLUGIN_MODEL,
+} from "./plugin_model";
 import type { PluginRenderCtx } from "./plugin_model";
 import { DataModelBuilder } from "./block_migrations";
-import { type PluginName } from "./block_storage";
+import { type PluginName, DATA_MODEL_LEGACY_VERSION } from "./block_storage";
 import type { ResultPool } from "./render";
 
-// =============================================================================
-// Test Fixtures
-// =============================================================================
-
 type Data = { count: number; label: string };
 
 const dataModelChain = new DataModelBuilder().from<Data>("v1");
@@ -16,10 +17,6 @@ const dataModelChain = new DataModelBuilder().from<Data>("v1");
 // Mock ResultPool for testing
 const mockResultPool = {} as ResultPool;
 
-// =============================================================================
-// Tests
-// =============================================================================
-
 describe("PluginModel", () => {
   it("creates PluginModel with required fields", () => {
     const factory = PluginModel.define<Data>({
@@ -27,7 +24,8 @@ describe("PluginModel", () => {
       data: () => dataModelChain.init(() => ({ count: 0, label: "" })),
     }).build();
 
-    const plugin = factory.create();
+    const instance = factory.create({ pluginId: "test" });
+    const plugin = instance[CREATE_PLUGIN_MODEL]();
     expect(plugin.name).toBe("testPlugin");
     expect(plugin.outputs).toEqual({});
   });
@@ -40,7 +38,8 @@ describe("PluginModel", () => {
       data: (cfg) => dataModelChain.init(() => ({ count: cfg.initialCount, label: "initialized" })),
     }).build();
 
-    const plugin = factory.create({ initialCount: 100 });
+    const instance = factory.create({ pluginId: "inst1", config: { initialCount: 100 } });
+    const plugin = instance[CREATE_PLUGIN_MODEL]();
     expect(plugin.name).toBe("factoryPlugin");
     expect(plugin.dataModel.initialData()).toEqual({ count: 100, label: "initialized" });
   });
@@ -53,7 +52,8 @@ describe("PluginModel", () => {
       .output("doubled", (ctx) => ctx.data.count * ctx.params.multiplier)
       .build();
 
-    const plugin = factory.create();
+    const instance = factory.create({ pluginId: "inst1" });
+    const plugin = instance[CREATE_PLUGIN_MODEL]();
     expect(Object.keys(plugin.outputs)).toEqual(["doubled"]);
   });
 
@@ -67,7 +67,8 @@ describe("PluginModel", () => {
       .output("isReady", (ctx) => ctx.data.count > 0)
       .build();
 
-    const plugin = factory.create();
+    const instance = factory.create({ pluginId: "inst1" });
+    const plugin = instance[CREATE_PLUGIN_MODEL]();
     expect(Object.keys(plugin.outputs).sort()).toEqual(["formattedCount", "isReady", "upperLabel"]);
   });
 
@@ -79,7 +80,8 @@ describe("PluginModel", () => {
       .output("computed", (ctx) => ctx.data.count * ctx.params.factor)
       .build();
 
-    const plugin = factory.create();
+    const instance = factory.create({ pluginId: "inst1" });
+    const plugin = instance[CREATE_PLUGIN_MODEL]();
 
     const ctx: PluginRenderCtx<Data, { factor: number }> = {
       data: { count: 5, label: "" },
@@ -99,7 +101,8 @@ describe("PluginModel", () => {
       .output("hasResultPool", (ctx) => ctx.resultPool !== undefined)
       .build();
 
-    const plugin = factory.create();
+    const instance = factory.create({ pluginId: "inst1" });
+    const plugin = instance[CREATE_PLUGIN_MODEL]();
 
     const ctx: PluginRenderCtx<Data> = {
       data: { count: 0, label: "" },
@@ -119,7 +122,8 @@ describe("PluginModel", () => {
       .output("hasSelection", (ctx) => ctx.data.count >= 0)
       .build();
 
-    const plugin = factory.create({ option: true });
+    const instance = factory.create({ pluginId: "inst1", config: { option: true } });
+    const plugin = instance[CREATE_PLUGIN_MODEL]();
     expect(plugin.name).toBe("completePlugin");
     expect(Object.keys(plugin.outputs).sort()).toEqual(["currentItem", "hasSelection"]);
   });
@@ -130,7 +134,8 @@ describe("PluginModel", () => {
       data: () => dataModelChain.init(() => ({ count: 0, label: "" })),
     }).build();
 
-    const plugin = factory.create();
+    const instance = factory.create({ pluginId: "inst1" });
+    const plugin = instance[CREATE_PLUGIN_MODEL]();
     expect(plugin.outputs).toEqual({});
   });
 
@@ -143,7 +148,11 @@ describe("PluginModel", () => {
         dataModelChain.init(() => ({ count: cfg.defaultCount, label: cfg.defaultLabel })),
     }).build();
 
-    const plugin = factory.create({ defaultCount: 10, defaultLabel: "default" });
+    const instance = factory.create({
+      pluginId: "inst1",
+      config: { defaultCount: 10, defaultLabel: "default" },
+    });
+    const plugin = instance[CREATE_PLUGIN_MODEL]();
     expect(plugin.dataModel.initialData()).toEqual({ count: 10, label: "default" });
   });
 
@@ -159,10 +168,197 @@ describe("PluginModel", () => {
     const factory1 = pluginWithOutput1.build();
     const factory2 = pluginWithOutput2.build();
 
-    const plugin1 = factory1.create(undefined);
-    const plugin2 = factory2.create(undefined);
+    const plugin1 = factory1.create({ pluginId: "p1" })[CREATE_PLUGIN_MODEL]();
+    const plugin2 = factory2.create({ pluginId: "p2" })[CREATE_PLUGIN_MODEL]();
 
     expect(Object.keys(plugin1.outputs)).toEqual(["first"]);
     expect(Object.keys(plugin2.outputs)).toEqual(["second"]);
   });
 });
+
+describe("PluginDataModel", () => {
+  it("creates default data via new PluginDataModelBuilder().from().init()", () => {
+    type PData = { items: string[] };
+    const pdm = new PluginDataModelBuilder().from<PData>("v1").init(() => ({ items: [] }));
+
+    const defaultData = pdm.getDefaultData();
+    expect(defaultData.version).toBe("v1");
+    expect(defaultData.data).toStrictEqual({ items: [] });
+  });
+
+  it("getDefaultData passes config to init function", () => {
+    type PData = { items: string[]; count: number };
+    type PConfig = { defaultCount: number };
+
+    const pdm = new PluginDataModelBuilder().from<PData>("v1").init<PConfig>((config?) => ({
+      items: [],
+      count: config?.defaultCount ?? 0,
+    }));
+
+    // Without config
+    const noConfig = pdm.getDefaultData();
+    expect(noConfig.data).toStrictEqual({ items: [], count: 0 });
+
+    // With config
+    const withConfig = pdm.getDefaultData({ defaultCount: 42 });
+    expect(withConfig.data).toStrictEqual({ items: [], count: 42 });
+  });
+
+  it("supports .recover() in the chain", () => {
+    type V1 = { value: number };
+    type V2 = { value: number; label: string };
+
+    const pdm = new PluginDataModelBuilder()
+      .from<V1>("v1")
+      .recover((version, data) => {
+        if (version === "legacy") return { value: (data as any).val || 0 };
+        throw new Error(`Unknown version: ${version}`);
+      })
+      .migrate<V2>("v2", (v1) => ({ ...v1, label: "recovered" }))
+      .init(() => ({ value: 0, label: "" }));
+
+    // Recovery path — test via inner dataModel
+    const result = pdm.dataModel.migrate({ version: "legacy", data: { val: 99 } });
+    expect(result.version).toBe("v2");
+    expect(result.data).toStrictEqual({ value: 99, label: "recovered" });
+  });
+
+  it("getDefaultData uses config from PluginDataModel path", () => {
+    type PData = { value: number };
+    type PConfig = { defaultValue: number };
+
+    const pdm = new PluginDataModelBuilder()
+      .from<PData>("v1")
+      .init<PConfig>((config?) => ({ value: config?.defaultValue ?? 0 }));
+
+    const factory = PluginModel.define({
+      name: "pdmTest" as PluginName,
+      data: pdm,
+    }).build();
+
+    const plugin = factory
+      .create({ pluginId: "inst1", config: { defaultValue: 42 } })
+      [CREATE_PLUGIN_MODEL]();
+    expect(plugin.getDefaultData().data).toStrictEqual({ value: 42 });
+  });
+
+  it("getDefaultData works for function-based data", () => {
+    const factory = PluginModel.define<Data>({
+      name: "fnTest" as PluginName,
+      data: () => dataModelChain.init(() => ({ count: 0, label: "" })),
+    }).build();
+
+    const plugin = factory.create({ pluginId: "inst1" })[CREATE_PLUGIN_MODEL]();
+    expect(plugin.getDefaultData().data).toStrictEqual({ count: 0, label: "" });
+  });
+
+  it("upgradeLegacy allows migrating from DATA_MODEL_LEGACY_VERSION", () => {
+    type V1 = { value: number };
+    type V2 = { value: number; extra: string };
+
+    const pdm = new PluginDataModelBuilder()
+      .from<V1>("v1")
+      .upgradeLegacy((data) => ({ value: (data as any).oldValue ?? 0 }))
+      .migrate<V2>("v2", (v1) => ({ ...v1, extra: "added" }))
+      .init(() => ({ value: 0, extra: "" }));
+
+    // Legacy path: data arrives with DATA_MODEL_LEGACY_VERSION
+    const result = pdm.dataModel.migrate({
+      version: DATA_MODEL_LEGACY_VERSION,
+      data: { oldValue: 42 },
+    });
+    expect(result.version).toBe("v2");
+    expect(result.data).toStrictEqual({ value: 42, extra: "added" });
+  });
+
+  it("upgradeLegacy is not needed for normal version migration", () => {
+    type V1 = { value: number };
+    type V2 = { value: number; extra: string };
+
+    const pdm = new PluginDataModelBuilder()
+      .from<V1>("v1")
+      .upgradeLegacy((data) => ({ value: (data as any).oldValue ?? 0 }))
+      .migrate<V2>("v2", (v1) => ({ ...v1, extra: "added" }))
+      .init(() => ({ value: 0, extra: "" }));
+
+    // Normal migration: v1 → v2
+    const result = pdm.dataModel.migrate({
+      version: "v1",
+      data: { value: 10 },
+    });
+    expect(result.version).toBe("v2");
+    expect(result.data).toStrictEqual({ value: 10, extra: "added" });
+  });
+});
+
+describe("PluginInstance", () => {
+  it("factory.create() returns a PluginInstance with correct id", () => {
+    const factory = PluginModel.define<Data>({
+      name: "instanceTest" as PluginName,
+      data: () => dataModelChain.init(() => ({ count: 0, label: "" })),
+    }).build();
+
+    const instance = factory.create({ pluginId: "myTable" });
+    expect(instance).toBeInstanceOf(PluginInstance);
+    expect(instance.id).toBe("myTable");
+  });
+
+  it("PluginInstance[CREATE_PLUGIN_MODEL]() delegates to factory", () => {
+    type Config = { initial: number };
+    const factory = PluginModel.define<Data, undefined, Config>({
+      name: "delegateTest" as PluginName,
+      data: (cfg) => dataModelChain.init(() => ({ count: cfg.initial, label: "" })),
+    }).build();
+
+    const instance = factory.create({ pluginId: "inst1", config: { initial: 42 } });
+    const plugin = instance[CREATE_PLUGIN_MODEL]();
+    expect(plugin.name).toBe("delegateTest");
+    expect(plugin.dataModel.initialData()).toStrictEqual({ count: 42, label: "" });
+  });
+
+  it("PluginInstance without transferAt has empty transferVersion", () => {
+    const factory = PluginModel.define<Data>({
+      name: "noTransfer" as PluginName,
+      data: () => dataModelChain.init(() => ({ count: 0, label: "" })),
+    }).build();
+
+    const instance = factory.create({ pluginId: "inst1" });
+    expect(instance.transferVersion).toBe("");
+  });
+
+  it("PluginInstance with transferAt has correct transferVersion", () => {
+    type V1 = { value: number };
+    type V2 = { value: number; label: string };
+    const pdm = new PluginDataModelBuilder()
+      .from<V1>("v1")
+      .migrate<V2>("v2", (v1) => ({ ...v1, label: "" }))
+      .init(() => ({ value: 0, label: "" }));
+
+    const factory = PluginModel.define({
+      name: "withTransfer" as PluginName,
+      data: pdm,
+    }).build();
+
+    const instance = factory.create({ pluginId: "inst1", transferAt: "v1" });
+    expect(instance.transferVersion).toBe("v1");
+  });
+
+  it("config is captured in getDefaultData closure", () => {
+    type PData = { items: string[]; count: number };
+    type PConfig = { defaultCount: number };
+
+    const pdm = new PluginDataModelBuilder().from<PData>("v1").init<PConfig>((config?) => ({
+      items: [],
+      count: config?.defaultCount ?? 0,
+    }));
+
+    const factory = PluginModel.define({
+      name: "configStore" as PluginName,
+      data: pdm,
+    }).build();
+
+    const instance = factory.create({ pluginId: "inst1", config: { defaultCount: 99 } });
+    const plugin = instance[CREATE_PLUGIN_MODEL]();
+    expect(plugin.getDefaultData().data).toStrictEqual({ items: [], count: 99 });
+  });
+});