@platforma-sdk/model 1.57.0 → 1.58.0

package/src/plugin_handle.ts

@@ -0,0 +1,85 @@
+/**
+ * PluginHandle — Opaque branded handle and output key utilities for plugin instances.
+ *
+ * Extracted into its own module to break circular dependencies:
+ * both block_storage.ts and plugin_model.ts can import from here
+ * without depending on each other.
+ *
+ * @module plugin_handle
+ */
+
+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
+ * under strictFunctionTypes. PluginFactoryLike exposes only the covariant `__types` phantom,
+ * avoiding the contravariance chain. Handles only need `__types` for type extraction.
+ *
+ * PluginFactory extends PluginFactoryLike, so every concrete factory satisfies this constraint.
+ */
+export interface PluginFactoryLike<
+  Data extends Record<string, unknown> = Record<string, unknown>,
+  Params extends undefined | Record<string, unknown> = undefined | Record<string, unknown>,
+  Outputs extends Record<string, unknown> = Record<string, unknown>,
+> {
+  readonly __types?: {
+    data: Data;
+    params: Params;
+    outputs: Outputs;
+  };
+}
+
+/** Extract the Data type from a PluginFactoryLike phantom. */
+export type InferFactoryData<F extends PluginFactoryLike> = NonNullable<
+  F extends PluginFactoryLike<infer D, any, any> ? D : Record<string, unknown>
+>;
+
+/** Extract the Params type from a PluginFactoryLike phantom. */
+export type InferFactoryParams<F extends PluginFactoryLike> = NonNullable<
+  F extends PluginFactoryLike<any, infer P, any> ? P : undefined
+>;
+
+/** Extract the Outputs type from a PluginFactoryLike phantom. */
+export type InferFactoryOutputs<F extends PluginFactoryLike> = NonNullable<
+  F extends PluginFactoryLike<any, any, infer O> ? O : Record<string, unknown>
+>;
+
+/**
+ * Derive a typed PluginHandle from a PluginFactory type.
+ * Normalizes the brand to only data/params/outputs (strips config) so handles
+ * from InferPluginHandles match handles from InferPluginHandle.
+ */
+export type InferPluginHandle<F extends PluginFactoryLike> = NonNullable<
+  F extends PluginFactoryLike<infer Data, infer Params, infer Outputs>
+    ? PluginHandle<PluginFactoryLike<Data, Params, Outputs>>
+    : PluginHandle
+>;
+
+/**
+ * Opaque handle for a plugin instance. Runtime value is the plugin instance ID string.
+ * Branded with factory phantom `F` for type-safe data/outputs extraction.
+ * Constrained with PluginFactoryLike (not PluginFactory) to avoid variance issues.
+ */
+export type PluginHandle<F extends PluginFactoryLike = PluginFactoryLike> = Branded<string, F>;
+
+const PLUGIN_OUTPUT_PREFIX = "plugin-output#";
+
+/** Construct the output key for a plugin output in the block outputs map. */
+export function pluginOutputKey<F extends PluginFactoryLike>(
+  handle: PluginHandle<F>,
+  outputKey: string,
+): string {
+  return `${PLUGIN_OUTPUT_PREFIX}${handle}#${outputKey}`;
+}
+
+/** Check whether an output key belongs to a plugin (vs block-level output). */
+export function isPluginOutputKey(key: string): boolean {
+  return key.startsWith(PLUGIN_OUTPUT_PREFIX);
+}
+
+/** Get the prefix used for all outputs of a specific plugin instance. */
+export function pluginOutputPrefix<F extends PluginFactoryLike>(handle: PluginHandle<F>): string {
+  return pluginOutputKey(handle, "");
+}

package/src/plugin_model.ts

@@ -7,37 +7,52 @@
  * @module plugin_model
  */
 
+import type { BlockCodeKnownFeatureFlags } from "@milaboratories/pl-model-common";
 import type { DataModel } from "./block_migrations";
 import type { PluginName } from "./block_storage";
+import type { PluginFactoryLike } from "./plugin_handle";
 import type { PluginRenderCtx } from "./render";
 
 /** Symbol for internal builder creation method */
 const FROM_BUILDER = Symbol("fromBuilder");
 
-// =============================================================================
-// Plugin Type
-// =============================================================================
+export type PluginData = Record<string, unknown>;
+export type PluginParams = undefined | Record<string, unknown>;
+export type PluginOutputs = Record<string, unknown>;
+export type PluginConfig = undefined | Record<string, unknown>;
 
 /**
  * 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 = {}> {
+export class PluginModel<
+  Data extends PluginData = PluginData,
+  Params extends PluginParams = undefined,
+  Outputs extends PluginOutputs = PluginOutputs,
+> {
   /** 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] };
+  readonly outputs: {
+    [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];
+  };
+  /** Feature flags declared by this plugin */
+  readonly featureFlags?: BlockCodeKnownFeatureFlags;
 
-  private constructor(input: {
+  private constructor(options: {
     name: PluginName;
     dataModel: DataModel<Data>;
-    outputs: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };
+    outputs: {
+      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];
+    };
+    featureFlags?: BlockCodeKnownFeatureFlags;
   }) {
-    this.name = input.name;
-    this.dataModel = input.dataModel;
-    this.outputs = input.outputs;
+    this.name = options.name;
+    this.dataModel = options.dataModel;
+    this.outputs = options.outputs;
+    this.featureFlags = options.featureFlags;
   }
 
   /**
@@ -45,12 +60,19 @@ export class PluginModel<Data = unknown, Params = undefined, Outputs = {}> {
    * Uses Symbol key to prevent external access.
    * @internal
    */
-  static [FROM_BUILDER]<D, P, O>(input: {
+  static [FROM_BUILDER]<
+    Data extends PluginData,
+    Params extends PluginParams,
+    Outputs extends PluginOutputs,
+  >(options: {
     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);
+    dataModel: DataModel<Data>;
+    outputs: {
+      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];
+    };
+    featureFlags?: BlockCodeKnownFeatureFlags;
+  }): PluginModel<Data, Params, Outputs> {
+    return new PluginModel<Data, Params, Outputs>(options);
   }
 
   /**
@@ -63,40 +85,66 @@ export class PluginModel<Data = unknown, Params = undefined, Outputs = {}> {
    * @example
    * const dataModelChain = new DataModelBuilder().from<MyData>(DATA_MODEL_DEFAULT_VERSION);
    *
-   * const myPlugin = PluginModel.define<MyData, MyParams, MyConfig>({
+   * const myPlugin = PluginModel.define({
    *   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: {
+  static define<
+    Data extends PluginData,
+    Params extends PluginParams,
+    Config extends PluginConfig,
+  >(options: {
     name: PluginName;
     data: (config?: Config) => DataModel<Data>;
-  }): PluginModelBuilder<Data, Params, Config> {
-    return PluginModelBuilder[FROM_BUILDER]<Data, Params, Config>(options);
+    featureFlags?: BlockCodeKnownFeatureFlags;
+  }): PluginModelBuilder<Data, Params, {}, Config> {
+    return PluginModelBuilder[FROM_BUILDER](options);
   }
 }
 
-/**
- * Plugin factory returned by PluginModelBuilder.build().
- * Call create() with config to get a configured PluginModel instance.
- */
-class PluginModelFactory<Data, Params, Config, Outputs> {
+/** Plugin factory returned by PluginModelBuilder.build(). */
+export interface PluginFactory<
+  Data extends PluginData = PluginData,
+  Params extends PluginParams = undefined,
+  Outputs extends PluginOutputs = PluginOutputs,
+  Config extends PluginConfig = undefined,
+> extends PluginFactoryLike {
+  create(config?: Config): PluginModel<Data, Params, Outputs>;
+  /**
+   * @internal Phantom field for structural type extraction.
+   * Enables InferFactoryData/InferFactoryOutputs to work via PluginFactoryLike.
+   */
+  readonly __types?: { data: Data; params: Params; outputs: Outputs; config: Config };
+}
+
+class PluginModelFactory<
+  Data extends PluginData = PluginData,
+  Params extends PluginParams = undefined,
+  Outputs extends PluginOutputs = PluginOutputs,
+  Config extends PluginConfig = undefined,
+> implements PluginFactory<Data, Params, Outputs, Config> {
   private readonly name: PluginName;
   private readonly data: (config?: Config) => DataModel<Data>;
   private readonly outputs: {
-    [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K];
+    [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];
   };
+  private readonly featureFlags?: BlockCodeKnownFeatureFlags;
 
-  constructor(input: {
+  constructor(options: {
     name: PluginName;
     data: (config?: Config) => DataModel<Data>;
-    outputs: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };
+    outputs: {
+      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];
+    };
+    featureFlags?: BlockCodeKnownFeatureFlags;
   }) {
-    this.name = input.name;
-    this.data = input.data;
-    this.outputs = input.outputs;
+    this.name = options.name;
+    this.data = options.data;
+    this.outputs = options.outputs;
+    this.featureFlags = options.featureFlags;
   }
 
   /** Create a configured PluginModel instance */
@@ -105,14 +153,11 @@ class PluginModelFactory<Data, Params, Config, Outputs> {
       name: this.name,
       dataModel: this.data(config),
       outputs: this.outputs,
+      featureFlags: this.featureFlags,
     });
   }
 }
 
-// =============================================================================
-// Plugin Model Builder
-// =============================================================================
-
 /**
  * Builder for creating PluginType with type-safe output definitions.
  *
@@ -136,27 +181,34 @@ class PluginModelFactory<Data, Params, Config, Outputs> {
  *   .build();
  */
 class PluginModelBuilder<
-  Data,
-  Params = undefined,
-  Config = undefined,
-  Outputs extends Record<string, unknown> = {},
+  Data extends PluginData = PluginData,
+  Params extends PluginParams = undefined,
+  Outputs extends PluginOutputs = PluginOutputs,
+  Config extends PluginConfig = undefined,
 > {
   private readonly name: PluginName;
   private readonly data: (config?: Config) => DataModel<Data>;
   private readonly outputs: {
-    [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K];
+    [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];
   };
+  private readonly featureFlags?: BlockCodeKnownFeatureFlags;
 
-  private constructor(input: {
+  private constructor(options: {
     name: PluginName;
     data: (config?: Config) => DataModel<Data>;
-    outputs?: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };
+    outputs?: {
+      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];
+    };
+    featureFlags?: BlockCodeKnownFeatureFlags;
   }) {
-    this.name = input.name;
-    this.data = input.data;
+    this.name = options.name;
+    this.data = options.data;
     this.outputs =
-      input.outputs ??
-      ({} as { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] });
+      options.outputs ??
+      ({} as {
+        [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];
+      });
+    this.featureFlags = options.featureFlags;
   }
 
   /**
@@ -164,12 +216,20 @@ class PluginModelBuilder<
    * Uses Symbol key to prevent external access.
    * @internal
    */
-  static [FROM_BUILDER]<D, P, C, O extends Record<string, unknown> = {}>(input: {
+  static [FROM_BUILDER]<
+    Data extends PluginData,
+    Params extends PluginParams,
+    Outputs extends PluginOutputs,
+    Config extends PluginConfig,
+  >(options: {
     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);
+    data: (config?: Config) => DataModel<Data>;
+    outputs?: {
+      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];
+    };
+    featureFlags?: BlockCodeKnownFeatureFlags;
+  }): PluginModelBuilder<Data, Params, Outputs, Config> {
+    return new PluginModelBuilder(options);
   }
 
   /**
@@ -185,17 +245,18 @@ class PluginModelBuilder<
    */
   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 }>({
+    fn: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => T,
+  ): PluginModelBuilder<Data, Params, Outputs & { [K in Key]: T }, Config> {
+    return new PluginModelBuilder<Data, Params, Outputs & { [K in Key]: T }, Config>({
       name: this.name,
       data: this.data,
+      featureFlags: this.featureFlags,
       outputs: {
         ...this.outputs,
         [key]: fn,
       } as {
         [K in keyof (Outputs & { [P in Key]: T })]: (
-          ctx: PluginRenderCtx<Data, Params>,
+          ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>,
         ) => (Outputs & { [P in Key]: T })[K];
       },
     });
@@ -214,11 +275,12 @@ class PluginModelBuilder<
    * // 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>({
+  build(): PluginFactory<Data, Params, Outputs, Config> {
+    return new PluginModelFactory<Data, Params, Outputs, Config>({
       name: this.name,
       data: this.data,
       outputs: this.outputs,
+      featureFlags: this.featureFlags,
     });
   }
 }

package/src/render/api.ts

@@ -50,6 +50,12 @@ import canonicalize from "canonicalize";
 import type { Optional } from "utility-types";
 import { getCfgRenderCtx } from "../internal";
 import { getPluginData } from "../block_storage";
+import type {
+  PluginHandle,
+  PluginFactoryLike,
+  InferFactoryData,
+  InferFactoryParams,
+} from "../plugin_handle";
 import { TreeNodeAccessor, ifDef } from "./accessor";
 import type { FutureRef } from "./future";
 import type { AccessorHandle, GlobalCfgRenderCtx } from "./internal";
@@ -756,40 +762,44 @@ export class RenderCtxLegacy<Args = unknown, UiState = unknown> extends RenderCt
 /**
  * Render context for plugin output functions.
  * Reads plugin data from blockStorage and derives params from pre-wrapped input callbacks.
+ *
+ * Parameterized on the factory-like phantom F so that getPluginData returns
+ * InferFactoryData<F> directly — no casts needed for the data getter.
+ *
+ * @typeParam F - PluginFactoryLike phantom carrying data/params/outputs types
  */
-export class PluginRenderCtx<Data = unknown, Params = unknown> {
+export class PluginRenderCtx<F extends PluginFactoryLike = PluginFactoryLike> {
   private readonly ctx: GlobalCfgRenderCtx;
-  private readonly pluginId: string;
+  private readonly handle: PluginHandle<F>;
   private readonly wrappedInputs: Record<string, () => unknown>;
 
-  constructor(pluginId: string, wrappedInputs: Record<string, () => unknown>) {
+  constructor(handle: PluginHandle<F>, wrappedInputs: Record<string, () => unknown>) {
     this.ctx = getCfgRenderCtx();
-    this.pluginId = pluginId;
+    this.handle = handle;
     this.wrappedInputs = wrappedInputs;
   }
 
-  private dataCache?: { v: Data };
+  private dataCache?: { v: InferFactoryData<F> };
 
   /** Plugin's persistent data from blockStorage.__plugins.{pluginId}.__data */
-  public get data(): Data {
+  public get data(): InferFactoryData<F> {
     if (this.dataCache === undefined) {
       const raw = this.ctx.blockStorage();
-      const pluginData = getPluginData<Data>(parseJson(raw), this.pluginId);
-      this.dataCache = { v: pluginData };
+      this.dataCache = { v: getPluginData(parseJson(raw), this.handle) };
     }
     return this.dataCache.v;
   }
 
-  private paramsCache?: { v: Params };
+  private paramsCache?: { v: InferFactoryParams<F> };
 
   /** Params derived from block context via pre-wrapped input callbacks */
-  public get params(): Params {
+  public get params(): InferFactoryParams<F> {
     if (this.paramsCache === undefined) {
       const result: Record<string, unknown> = {};
       for (const [key, fn] of Object.entries(this.wrappedInputs)) {
         result[key] = fn();
       }
-      this.paramsCache = { v: result as Params };
+      this.paramsCache = { v: result as InferFactoryParams<F> };
     }
     return this.paramsCache.v;
   }