@platforma-sdk/model 1.54.13 → 1.56.0

package/src/plugin_model.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, it } from "vitest";
+import { PluginModel } from "./plugin_model";
+import type { PluginRenderCtx } from "./plugin_model";
+import { DataModelBuilder } from "./block_migrations";
+import { DATA_MODEL_DEFAULT_VERSION, type PluginName } from "./block_storage";
+import type { ResultPool } from "./render";
+
+// =============================================================================
+// Test Fixtures
+// =============================================================================
+
+type Data = { count: number; label: string };
+
+const dataModelChain = new DataModelBuilder().from<Data>(DATA_MODEL_DEFAULT_VERSION);
+
+// Mock ResultPool for testing
+const mockResultPool = {} as ResultPool;
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe("PluginModel", () => {
+  it("creates PluginModel with required fields", () => {
+    const factory = PluginModel.define<Data>({
+      name: "testPlugin" as PluginName,
+      data: () => dataModelChain.init(() => ({ count: 0, label: "" })),
+    }).build();
+
+    const plugin = factory.create();
+    expect(plugin.name).toBe("testPlugin");
+    expect(plugin.outputs).toEqual({});
+  });
+
+  it("creates PluginModel when calling create() with config", () => {
+    type Config = { initialCount: number };
+
+    const factory = PluginModel.define<Data, undefined, Config>({
+      name: "factoryPlugin" as PluginName,
+      data: (cfg) => dataModelChain.init(() => ({ count: cfg.initialCount, label: "initialized" })),
+    }).build();
+
+    const plugin = factory.create({ initialCount: 100 });
+    expect(plugin.name).toBe("factoryPlugin");
+    expect(plugin.dataModel.initialData()).toEqual({ count: 100, label: "initialized" });
+  });
+
+  it("adds single output", () => {
+    const factory = PluginModel.define<Data, { multiplier: number }>({
+      name: "singleOutput" as PluginName,
+      data: () => dataModelChain.init(() => ({ count: 0, label: "" })),
+    })
+      .output("doubled", (ctx) => ctx.data.count * ctx.params.multiplier)
+      .build();
+
+    const plugin = factory.create();
+    expect(Object.keys(plugin.outputs)).toEqual(["doubled"]);
+  });
+
+  it("accumulates multiple outputs", () => {
+    const factory = PluginModel.define<Data, { prefix: string }>({
+      name: "multiOutput" as PluginName,
+      data: () => dataModelChain.init(() => ({ count: 0, label: "" })),
+    })
+      .output("formattedCount", (ctx) => `${ctx.params.prefix}${ctx.data.count}`)
+      .output("upperLabel", (ctx) => ctx.data.label.toUpperCase())
+      .output("isReady", (ctx) => ctx.data.count > 0)
+      .build();
+
+    const plugin = factory.create();
+    expect(Object.keys(plugin.outputs).sort()).toEqual(["formattedCount", "isReady", "upperLabel"]);
+  });
+
+  it("executes output functions with correct context", () => {
+    const factory = PluginModel.define<Data, { factor: number }>({
+      name: "contextTest" as PluginName,
+      data: () => dataModelChain.init(() => ({ count: 0, label: "" })),
+    })
+      .output("computed", (ctx) => ctx.data.count * ctx.params.factor)
+      .build();
+
+    const plugin = factory.create();
+
+    const ctx: PluginRenderCtx<Data, { factor: number }> = {
+      data: { count: 5, label: "" },
+      params: { factor: 3 },
+      resultPool: mockResultPool,
+    };
+
+    const result = plugin.outputs.computed(ctx);
+    expect(result).toBe(15);
+  });
+
+  it("allows outputs to access resultPool", () => {
+    const factory = PluginModel.define<Data>({
+      name: "resultPoolTest" as PluginName,
+      data: () => dataModelChain.init(() => ({ count: 0, label: "" })),
+    })
+      .output("hasResultPool", (ctx) => ctx.resultPool !== undefined)
+      .build();
+
+    const plugin = factory.create();
+
+    const ctx: PluginRenderCtx<Data> = {
+      data: { count: 0, label: "" },
+      params: undefined,
+      resultPool: mockResultPool,
+    };
+
+    expect(plugin.outputs.hasResultPool(ctx)).toBe(true);
+  });
+
+  it("returns valid PluginModel from factory.create()", () => {
+    const factory = PluginModel.define<Data, { items: string[] }, { option: boolean }>({
+      name: "completePlugin" as PluginName,
+      data: () => dataModelChain.init(() => ({ count: -1, label: "" })),
+    })
+      .output("currentItem", (ctx) => ctx.params.items[ctx.data.count])
+      .output("hasSelection", (ctx) => ctx.data.count >= 0)
+      .build();
+
+    const plugin = factory.create({ option: true });
+    expect(plugin.name).toBe("completePlugin");
+    expect(Object.keys(plugin.outputs).sort()).toEqual(["currentItem", "hasSelection"]);
+  });
+
+  it("allows creating plugin without outputs", () => {
+    const factory = PluginModel.define<Data>({
+      name: "noOutputs" as PluginName,
+      data: () => dataModelChain.init(() => ({ count: 0, label: "" })),
+    }).build();
+
+    const plugin = factory.create();
+    expect(plugin.outputs).toEqual({});
+  });
+
+  it("passes config to data model factory for initialization", () => {
+    type Config = { defaultCount: number; defaultLabel: string };
+
+    const factory = PluginModel.define<Data, undefined, Config>({
+      name: "configInitPlugin" as PluginName,
+      data: (cfg) =>
+        dataModelChain.init(() => ({ count: cfg.defaultCount, label: cfg.defaultLabel })),
+    }).build();
+
+    const plugin = factory.create({ defaultCount: 10, defaultLabel: "default" });
+    expect(plugin.dataModel.initialData()).toEqual({ count: 10, label: "default" });
+  });
+
+  it("does not modify original builder when chaining", () => {
+    const basePlugin = PluginModel.define<Data>({
+      name: "immutableTest" as PluginName,
+      data: () => dataModelChain.init(() => ({ count: 0, label: "" })),
+    });
+
+    const pluginWithOutput1 = basePlugin.output("first", (ctx) => ctx.data.count);
+    const pluginWithOutput2 = basePlugin.output("second", (ctx) => ctx.data.count * 2);
+
+    const factory1 = pluginWithOutput1.build();
+    const factory2 = pluginWithOutput2.build();
+
+    const plugin1 = factory1.create(undefined);
+    const plugin2 = factory2.create(undefined);
+
+    expect(Object.keys(plugin1.outputs)).toEqual(["first"]);
+    expect(Object.keys(plugin2.outputs)).toEqual(["second"]);
+  });
+});

package/src/plugin_model.ts

@@ -0,0 +1,242 @@
+/**
+ * PluginModel - Builder for creating plugin types with data model and outputs.
+ *
+ * Plugins are UI components with their own model logic and persistent state.
+ * Block developers register plugin instances via BlockModelV3.plugin() method.
+ *
+ * @module plugin_model
+ */
+
+import type { DataModel } from "./block_migrations";
+import type { PluginName } from "./block_storage";
+import type { ResultPool } from "./render";
+
+/** Symbol for internal builder creation method */
+const FROM_BUILDER = Symbol("fromBuilder");
+
+// =============================================================================
+// Plugin Render Context
+// =============================================================================
+
+/**
+ * Context passed to plugin output functions.
+ * Provides access to plugin's persistent data, params derived from block context,
+ * and the result pool for accessing workflow outputs.
+ */
+export interface PluginRenderCtx<Data, Params = undefined> {
+  /** Plugin's persistent data */
+  readonly data: Data;
+  /** Params derived from block's RenderCtx */
+  readonly params: Params;
+  /** Result pool for accessing workflow outputs */
+  readonly resultPool: ResultPool;
+}
+
+// =============================================================================
+// Plugin Type
+// =============================================================================
+
+/**
+ * Configured plugin instance returned by PluginModelFactory.create().
+ * Contains the plugin's name, data model, and output definitions.
+ */
+export class PluginModel<Data = unknown, Params = undefined, Outputs = {}> {
+  /** Globally unique plugin name */
+  readonly name: PluginName;
+  /** Data model instance for this plugin */
+  readonly dataModel: DataModel<Data>;
+  /** Output definitions - functions that compute outputs from plugin context */
+  readonly outputs: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };
+
+  private constructor(input: {
+    name: PluginName;
+    dataModel: DataModel<Data>;
+    outputs: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };
+  }) {
+    this.name = input.name;
+    this.dataModel = input.dataModel;
+    this.outputs = input.outputs;
+  }
+
+  /**
+   * Internal method for creating PluginModel from factory.
+   * Uses Symbol key to prevent external access.
+   * @internal
+   */
+  static [FROM_BUILDER]<D, P, O>(input: {
+    name: PluginName;
+    dataModel: DataModel<D>;
+    outputs: { [K in keyof O]: (ctx: PluginRenderCtx<D, P>) => O[K] };
+  }): PluginModel<D, P, O> {
+    return new this<D, P, O>(input);
+  }
+
+  /**
+   * Creates a new PluginModelBuilder for building plugin definitions.
+   *
+   * @param options.name - Globally unique plugin name
+   * @param options.data - Factory function that creates the data model from config
+   * @returns PluginModelBuilder for chaining output definitions
+   *
+   * @example
+   * const dataModelChain = new DataModelBuilder().from<MyData>(DATA_MODEL_DEFAULT_VERSION);
+   *
+   * const myPlugin = PluginModel.define<MyData, MyParams, MyConfig>({
+   *   name: 'myPlugin' as PluginName,
+   *   data: (cfg) => dataModelChain.init(() => ({ value: cfg.defaultValue })),
+   * })
+   *   .output('computed', (ctx) => ctx.data.value * ctx.params.multiplier)
+   *   .build();
+   */
+  static define<Data, Params = undefined, Config = undefined>(options: {
+    name: PluginName;
+    data: (config?: Config) => DataModel<Data>;
+  }): PluginModelBuilder<Data, Params, Config> {
+    return PluginModelBuilder[FROM_BUILDER]<Data, Params, Config>(options);
+  }
+}
+
+/**
+ * Plugin factory returned by PluginModelBuilder.build().
+ * Call create() with config to get a configured PluginModel instance.
+ */
+class PluginModelFactory<Data, Params, Config, Outputs> {
+  private readonly name: PluginName;
+  private readonly data: (config?: Config) => DataModel<Data>;
+  private readonly outputs: {
+    [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K];
+  };
+
+  constructor(input: {
+    name: PluginName;
+    data: (config?: Config) => DataModel<Data>;
+    outputs: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };
+  }) {
+    this.name = input.name;
+    this.data = input.data;
+    this.outputs = input.outputs;
+  }
+
+  /** Create a configured PluginModel instance */
+  create(config?: Config): PluginModel<Data, Params, Outputs> {
+    return PluginModel[FROM_BUILDER]<Data, Params, Outputs>({
+      name: this.name,
+      dataModel: this.data(config),
+      outputs: this.outputs,
+    });
+  }
+}
+
+// =============================================================================
+// Plugin Model Builder
+// =============================================================================
+
+/**
+ * Builder for creating PluginType with type-safe output definitions.
+ *
+ * Use `PluginModel.define()` to create a builder instance.
+ *
+ * @typeParam Data - Plugin's persistent data type
+ * @typeParam Params - Params derived from block's RenderCtx (optional)
+ * @typeParam Config - Static configuration passed to plugin factory (optional)
+ * @typeParam Outputs - Accumulated output types
+ *
+ * @example
+ * const dataModelChain = new DataModelBuilder().from<TableData>(DATA_MODEL_DEFAULT_VERSION);
+ *
+ * const dataTable = PluginModel.define<TableData, TableParams, TableConfig>({
+ *     name: 'dataTable' as PluginName,
+ *     data: (cfg) => {
+ *       return dataModelChain.init(() => ({ state: createInitialState(cfg.ops) }));
+ *     },
+ *   })
+ *   .output('model', (ctx) => createTableModel(ctx))
+ *   .build();
+ */
+class PluginModelBuilder<
+  Data,
+  Params = undefined,
+  Config = undefined,
+  Outputs extends Record<string, unknown> = {},
+> {
+  private readonly name: PluginName;
+  private readonly data: (config?: Config) => DataModel<Data>;
+  private readonly outputs: {
+    [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K];
+  };
+
+  private constructor(input: {
+    name: PluginName;
+    data: (config?: Config) => DataModel<Data>;
+    outputs?: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };
+  }) {
+    this.name = input.name;
+    this.data = input.data;
+    this.outputs =
+      input.outputs ??
+      ({} as { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] });
+  }
+
+  /**
+   * Internal method for creating PluginModelBuilder.
+   * Uses Symbol key to prevent external access.
+   * @internal
+   */
+  static [FROM_BUILDER]<D, P, C, O extends Record<string, unknown> = {}>(input: {
+    name: PluginName;
+    data: (config?: C) => DataModel<D>;
+    outputs?: { [K in keyof O]: (ctx: PluginRenderCtx<D, P>) => O[K] };
+  }): PluginModelBuilder<D, P, C, O> {
+    return new this<D, P, C, O>(input);
+  }
+
+  /**
+   * Adds an output to the plugin.
+   *
+   * @param key - Output name
+   * @param fn - Function that computes the output value from plugin context
+   * @returns PluginModel with the new output added
+   *
+   * @example
+   * .output('model', (ctx) => createModel(ctx.params.columns, ctx.data.state))
+   * .output('isReady', (ctx) => ctx.params.columns !== undefined)
+   */
+  output<const Key extends string, T>(
+    key: Key,
+    fn: (ctx: PluginRenderCtx<Data, Params>) => T,
+  ): PluginModelBuilder<Data, Params, Config, Outputs & { [K in Key]: T }> {
+    return new PluginModelBuilder<Data, Params, Config, Outputs & { [K in Key]: T }>({
+      name: this.name,
+      data: this.data,
+      outputs: {
+        ...this.outputs,
+        [key]: fn,
+      } as {
+        [K in keyof (Outputs & { [P in Key]: T })]: (
+          ctx: PluginRenderCtx<Data, Params>,
+        ) => (Outputs & { [P in Key]: T })[K];
+      },
+    });
+  }
+
+  /**
+   * Finalizes the plugin definition and returns a ConfigurablePluginModel.
+   *
+   * @returns Callable plugin factory that accepts config and returns PluginModel
+   *
+   * @example
+   * const myPlugin = new PluginModelBuilder('myPlugin', () => dataModel)
+   *   .output('value', (ctx) => ctx.data.value)
+   *   .build();
+   *
+   * // Later, call create() with config to get a configured instance:
+   * const configured = myPlugin.create({ defaultValue: 'test' });
+   */
+  build(): PluginModelFactory<Data, Params, Config, Outputs> {
+    return new PluginModelFactory<Data, Params, Config, Outputs>({
+      name: this.name,
+      data: this.data,
+      outputs: this.outputs,
+    });
+  }
+}

package/src/render/api.ts

@@ -533,40 +533,40 @@ export class ResultPool implements ColumnProvider, AxisLabelProvider {
 }
 
 /** Main entry point to the API available within model lambdas (like outputs, sections, etc..) */
-export abstract class RenderCtxBase<Args, Data> {
+export abstract class RenderCtxBase<Args = unknown, Data = unknown> {
   protected readonly ctx: GlobalCfgRenderCtx;
 
   constructor() {
     this.ctx = getCfgRenderCtx();
   }
 
-  private _dataCache?: { v: Data };
+  private dataCache?: { v: Data };
 
   public get data(): Data {
-    if (this._dataCache === undefined) {
+    if (this.dataCache === undefined) {
       const raw = this.ctx.data;
       const value = typeof raw === "function" ? raw() : raw;
-      this._dataCache = { v: value ? JSON.parse(value) : ({} as Data) };
+      this.dataCache = { v: value ? JSON.parse(value) : ({} as Data) };
     }
-    return this._dataCache.v;
+    return this.dataCache.v;
   }
 
   // lazy rendering because this feature is rarely used
-  private _activeArgsCache?: { v?: Args };
+  private activeArgsCache?: { v?: Args };
 
   /**
    * Returns args snapshot the block was executed for (i.e. when "Run" button was pressed).
    * Returns undefined, if block was never executed or stopped mid-way execution, so that the result was cleared.
    * */
   public get activeArgs(): Args | undefined {
-    if (this._activeArgsCache === undefined) {
+    if (this.activeArgsCache === undefined) {
       const raw = this.ctx.activeArgs;
       const value = typeof raw === "function" ? raw() : raw;
-      this._activeArgsCache = {
+      this.activeArgsCache = {
         v: value ? JSON.parse(value) : undefined,
       };
     }
-    return this._activeArgsCache.v;
+    return this.activeArgsCache.v;
   }
 
   // /** Can be used to determine features provided by the desktop instance. */
@@ -711,41 +711,43 @@ export abstract class RenderCtxBase<Args, Data> {
 }
 
 /** Main entry point to the API available within model lambdas (like outputs, sections, etc..) for v3+ blocks */
-export class RenderCtx<Args, Data> extends RenderCtxBase<Args, Data> {
-  private _argsCache?: { v: Args | undefined };
+export class RenderCtx<Args = unknown, Data = unknown> extends RenderCtxBase<Args, Data> {
+  private argsCache?: { v: Args | undefined };
   public get args(): Args | undefined {
-    if (this._argsCache === undefined) {
+    if (this.argsCache === undefined) {
       const raw = this.ctx.args;
       const value = typeof raw === "function" ? raw() : raw;
-      // args can be undefined when derivation fails (e.g., validation error in args())
-      this._argsCache = { v: value === undefined ? undefined : JSON.parse(value) };
+      this.argsCache = { v: value === undefined ? undefined : JSON.parse(value) };
     }
-    return this._argsCache.v;
+    return this.argsCache.v;
   }
 }
 
 /** Render context for legacy v1/v2 blocks - provides backward compatibility */
-export class RenderCtxLegacy<Args, UiState> extends RenderCtxBase<Args, UiState> {
-  private _argsCache?: { v: Args };
+export class RenderCtxLegacy<Args = unknown, UiState = unknown> extends RenderCtxBase<
+  Args,
+  UiState
+> {
+  private argsCache?: { v: Args };
 
   public get args(): Args {
-    if (this._argsCache === undefined) {
+    if (this.argsCache === undefined) {
       const raw = this.ctx.args;
       const value = typeof raw === "function" ? raw() : raw;
-      this._argsCache = { v: JSON.parse(value) };
+      this.argsCache = { v: JSON.parse(value) };
     }
-    return this._argsCache.v;
+    return this.argsCache.v;
   }
 
-  private _uiStateCache?: { v: UiState };
+  private uiStateCache?: { v: UiState };
 
   public get uiState(): UiState {
-    if (this._uiStateCache === undefined) {
+    if (this.uiStateCache === undefined) {
       const raw = this.ctx.uiState!;
       const value = typeof raw === "function" ? raw() : raw;
-      this._uiStateCache = { v: value ? JSON.parse(value) : ({} as UiState) };
+      this.uiStateCache = { v: value ? JSON.parse(value) : ({} as UiState) };
     }
-    return this._uiStateCache.v;
+    return this.uiStateCache.v;
   }
 }
 

package/src/render/internal.ts

@@ -1,5 +1,5 @@
 import type { Optional } from "utility-types";
-import type { Branded } from "../branding";
+import type { Branded, StringifiedJson } from "@milaboratories/pl-model-common";
 import type { CommonFieldTraverseOps, FieldTraversalStep, ResourceType } from "./traversal_ops";
 import type {
   ArchiveFormat,
@@ -198,6 +198,8 @@ export interface GlobalCfgRenderCtx extends GlobalCfgRenderCtxMethods {
   readonly data: string | (() => string);
   readonly activeArgs: undefined | string | (() => string | undefined);
 
+  readonly blockStorage: () => StringifiedJson;
+
   // Note: strings below are used because, anyway, using strings is the only way
   // to get data inside the QuickJS context, as it is implemented now. With this
   // approach deserialization can be lazily postponed until it is actually needed.

package/src/typing.test.ts

@@ -6,7 +6,7 @@ import {
 } from "@milaboratories/pl-model-common";
 import { expect, test } from "vitest";
 import { DeriveHref, StdCtx } from "./bconfig";
-import { BlockModel } from "./builder";
+import { BlockModel } from "./block_model_legacy";
 import {
   Args,
   ConfigResult,

package/src/version.ts

@@ -1,2 +1,10 @@
 import { version } from "../package.json";
 export const PlatformaSDKVersion = version;
+
+export type SdkInfo = {
+  readonly sdkVersion: string;
+};
+
+export const CurrentSdkInfo: SdkInfo = {
+  sdkVersion: PlatformaSDKVersion,
+};