@platforma-sdk/model 1.57.2 → 1.58.0

package/src/block_model.ts

@@ -6,12 +6,14 @@ import type {
   BlockCodeKnownFeatureFlags,
   BlockConfigContainer,
 } from "@milaboratories/pl-model-common";
+import { mergeFeatureFlags } from "@milaboratories/pl-model-common";
 import { getPlatformaInstance, isInUI, createAndRegisterRenderLambda } from "./internal";
 import type { DataModel } from "./block_migrations";
 import type { PlatformaV3 } from "./platforma";
 import type { InferRenderFunctionReturn, RenderFunction } from "./render";
 import { BlockRenderCtx, PluginRenderCtx } from "./render";
-import type { PluginModel } from "./plugin_model";
+import type { PluginData, PluginModel, PluginOutputs, PluginParams } from "./plugin_model";
+import { type PluginHandle, pluginOutputKey } from "./plugin_handle";
 import type { RenderCtxBase } from "./render";
 import { PlatformaSDKVersion } from "./version";
 import {
@@ -59,7 +61,11 @@ type ParamsInputErased = Record<string, (ctx: RenderCtxBase) => unknown>;
  * Registered plugin: model + param derivation lambdas.
  * Type parameters are carried by PluginModel generic.
  */
-export type PluginInstance<Data = unknown, Params = unknown, Outputs = unknown> = {
+export type PluginInstance<
+  Data extends PluginData = PluginData,
+  Params extends PluginParams = undefined,
+  Outputs extends PluginOutputs = PluginOutputs,
+> = {
   readonly model: PluginModel<Data, Params, Outputs>;
   readonly inputs: ParamsInputErased;
 };
@@ -125,7 +131,6 @@ export class BlockModelV3<
       renderingMode: "Heavy",
       dataModel,
       outputs: {},
-      // Register default sections callback (returns empty array)
       sections: createAndRegisterRenderLambda({ handle: "sections", lambda: () => [] }, true),
       title: undefined,
       subtitle: undefined,
@@ -372,23 +377,28 @@ export class BlockModelV3<
    *   sourceId: (ctx) => ctx.data.selectedSource,
    * })
    */
-  public plugin<const PluginId extends string, PluginData, PluginParams, PluginOutputs>(
+  public plugin<
+    const PluginId extends string,
+    PData extends PluginData,
+    PParams extends PluginParams,
+    POutputs extends PluginOutputs,
+  >(
     pluginId: PluginId,
-    plugin: PluginModel<PluginData, PluginParams, PluginOutputs>,
-    params?: ParamsInput<PluginParams, Args, Data>,
+    plugin: PluginModel<PData, PParams, POutputs>,
+    params?: ParamsInput<PParams, Args, Data>,
   ): BlockModelV3<
     Args,
     OutputsCfg,
     Data,
     Href,
-    Plugins & { [K in PluginId]: PluginInstance<PluginData, PluginParams, PluginOutputs> }
+    Plugins & { [K in PluginId]: PluginInstance<PData, PParams, POutputs> }
   > {
     // Validate pluginId uniqueness
     if (pluginId in this.config.plugins) {
       throw new Error(`Plugin '${pluginId}' already registered`);
     }
 
-    const instance: PluginInstance<PluginData, PluginParams, PluginOutputs> = {
+    const instance: PluginInstance<PData, PParams, POutputs> = {
       model: plugin,
       inputs: (params ?? {}) as ParamsInputErased,
     };
@@ -399,6 +409,7 @@ export class BlockModelV3<
         ...this.config.plugins,
         [pluginId]: instance,
       },
+      featureFlags: mergeFeatureFlags(this.config.featureFlags, plugin.featureFlags ?? {}),
     });
   }
 
@@ -423,15 +434,16 @@ export class BlockModelV3<
     // Build plugin registry
     const { plugins } = this.config;
     const pluginRegistry: Record<string, PluginName> = {};
-    for (const [pluginId, { model }] of Object.entries(plugins)) {
-      pluginRegistry[pluginId] = model.name;
+    const pluginHandles = Object.keys(plugins) as PluginHandle[];
+    for (const handle of pluginHandles) {
+      pluginRegistry[handle] = plugins[handle].model.name;
     }
 
     const { dataModel, argsFunction, prerunArgsFunction } = this.config;
 
-    function getPlugin(pluginId: string): PluginInstance {
-      const plugin = plugins[pluginId];
-      if (!plugin) throw new Error(`Plugin model not found for '${pluginId}'`);
+    function getPlugin(handle: PluginHandle): PluginInstance {
+      const plugin = plugins[handle];
+      if (!plugin) throw new Error(`Plugin model not found for '${handle}'`);
       return plugin;
     }
 
@@ -443,14 +455,14 @@ export class BlockModelV3<
         migrateStorage(currentStorageJson, {
           migrateBlockData: (v) => dataModel.migrate(v),
           getPluginRegistry: () => pluginRegistry,
-          migratePluginData: (pluginId, v) => getPlugin(pluginId).model.dataModel.migrate(v),
-          createPluginData: (pluginId) => getPlugin(pluginId).model.dataModel.getDefaultData(),
+          migratePluginData: (handle, v) => getPlugin(handle).model.dataModel.migrate(v),
+          createPluginData: (handle) => getPlugin(handle).model.dataModel.getDefaultData(),
         }),
       [BlockStorageFacadeCallbacks.StorageInitial]: () =>
         createInitialStorage({
           getDefaultBlockData: () => dataModel.getDefaultData(),
           getPluginRegistry: () => pluginRegistry,
-          createPluginData: (pluginId) => getPlugin(pluginId).model.dataModel.getDefaultData(),
+          createPluginData: (handle) => getPlugin(handle).model.dataModel.getDefaultData(),
         }),
       [BlockStorageFacadeCallbacks.ArgsDerive]: (storageJson) =>
         deriveArgsFromStorage(storageJson, argsFunction),
@@ -460,7 +472,8 @@ export class BlockModelV3<
 
     // Register plugin input and output lambdas
     const pluginOutputs: Record<string, ConfigRenderLambda> = {};
-    for (const [pluginId, { model, inputs }] of Object.entries(plugins)) {
+    for (const handle of pluginHandles) {
+      const { model, inputs } = plugins[handle];
       // Wrap plugin param lambdas: close over BlockRenderCtx creation
       const wrappedInputs: Record<string, () => unknown> = {};
       for (const [paramKey, paramFn] of Object.entries(inputs)) {
@@ -470,10 +483,10 @@ export class BlockModelV3<
       // Register plugin outputs (in config pack, evaluated by middle layer)
       const outputs = model.outputs as Record<string, (ctx: PluginRenderCtx) => unknown>;
       for (const [outputKey, outputFn] of Object.entries(outputs)) {
-        const key = `plugin-output#${pluginId}#${outputKey}`;
+        const key = pluginOutputKey(handle, outputKey);
         pluginOutputs[key] = createAndRegisterRenderLambda({
           handle: key,
-          lambda: () => outputFn(new PluginRenderCtx(pluginId, wrappedInputs)),
+          lambda: () => outputFn(new PluginRenderCtx(handle, wrappedInputs)),
         });
       }
     }
@@ -528,6 +541,7 @@ export class BlockModelV3<
               },
             ]),
           ),
+          pluginIds: pluginHandles,
         },
       } as any;
   }

package/src/block_model_legacy.ts

@@ -452,6 +452,7 @@ export class BlockModel<
               },
             ]),
           ),
+          pluginIds: [],
         },
       };
   }

package/src/block_storage.test.ts

@@ -14,6 +14,7 @@ import {
   type PluginName,
   type PluginRegistry,
 } from "./block_storage";
+import type { PluginHandle } from "./plugin_handle";
 
 describe("BlockStorage", () => {
   describe("BLOCK_STORAGE_KEY and BLOCK_STORAGE_SCHEMA_VERSION", () => {
@@ -215,11 +216,11 @@ describe("BlockStorage", () => {
         pluginId: "chart1",
         value: { type: "bar" },
       });
-      expect(getPluginData(storage, "chart1")).toEqual({ type: "bar" });
+      expect(getPluginData(storage, "chart1" as PluginHandle)).toEqual({ type: "bar" });
     });
 
     it("getPluginData should throw for missing plugin", () => {
-      expect(() => getPluginData(baseStorage, "nonexistent")).toThrow(
+      expect(() => getPluginData(baseStorage, "nonexistent" as PluginHandle)).toThrow(
         "Plugin 'nonexistent' not found in block storage",
       );
     });

package/src/block_storage.ts

@@ -11,6 +11,7 @@
 
 import type { Branded } from "@milaboratories/pl-model-common";
 import type { DataMigrationResult, DataVersioned } from "./block_migrations";
+import type { PluginHandle, PluginFactoryLike, InferFactoryData } from "./plugin_handle";
 
 // =============================================================================
 // Core Types
@@ -50,7 +51,7 @@ export type PluginName = Branded<string, "PluginName">;
  * Plugin registry - maps pluginId (unique within a block) to pluginName (globally unique plugin type).
  * Using a Record highlights that pluginIds must be unique within a block.
  */
-export type PluginRegistry = Record<string, PluginName>;
+export type PluginRegistry = Record<PluginHandle, PluginName>;
 
 /**
  * Versioned data - used for both block data and plugin data
@@ -75,8 +76,8 @@ export type BlockStorage<TState = unknown> = {
   readonly [BLOCK_STORAGE_KEY]: BlockStorageSchemaVersion;
   /** Registry of plugins: pluginId -> pluginName */
   __pluginRegistry?: PluginRegistry;
-  /** Plugin-specific data, keyed by pluginId */
-  __plugins?: Record<string, VersionedData<unknown>>;
+  /** Plugin-specific data, keyed by plugin handle */
+  __plugins?: Record<PluginHandle, VersionedData<unknown>>;
 } & VersionedData<TState>;
 
 /**
@@ -176,7 +177,7 @@ export function deriveDataFromStorage<TData = unknown>(rawStorage: unknown): TDa
 /** Payload for storage mutation operations. SDK defines specific operations. */
 export type MutateStoragePayload<T = unknown> =
   | { operation: "update-block-data"; value: T }
-  | { operation: "update-plugin-data"; pluginId: string; value: unknown };
+  | { operation: "update-plugin-data"; pluginId: PluginHandle; value: unknown };
 
 /**
  * Updates the data in BlockStorage (immutable)
@@ -261,13 +262,13 @@ export interface MigrateBlockStorageConfig {
   migrateBlockData: (versioned: DataVersioned<unknown>) => DataMigrationResult<unknown>;
   /** Migrate each plugin's data. Return undefined to remove the plugin. */
   migratePluginData: (
-    pluginId: string,
+    handle: PluginHandle,
     versioned: DataVersioned<unknown>,
   ) => DataMigrationResult<unknown> | undefined;
   /** The new plugin registry after migration (pluginId -> pluginName) */
   newPluginRegistry: PluginRegistry;
   /** Factory to create initial data for new plugins */
-  createPluginData: (pluginId: string) => DataVersioned<unknown>;
+  createPluginData: (handle: PluginHandle) => DataVersioned<unknown>;
 }
 
 /**
@@ -334,33 +335,34 @@ export function migrateBlockStorage(
   // Step 2: Migrate plugins
   const oldPlugins = storage.__plugins ?? {};
   const oldRegistry = storage.__pluginRegistry ?? {};
-  const newPlugins: Record<string, VersionedData<unknown>> = {};
+  const newPlugins: Record<PluginHandle, VersionedData<unknown>> = {};
 
-  for (const [pluginId, pluginName] of Object.entries(newPluginRegistry)) {
-    const existingEntry = oldPlugins[pluginId];
-    const existingName = oldRegistry[pluginId];
+  for (const [key, pluginName] of Object.entries(newPluginRegistry)) {
+    const handle = key as PluginHandle;
+    const existingEntry = oldPlugins[handle];
+    const existingName = oldRegistry[handle];
 
     try {
       if (existingEntry && existingName === pluginName) {
         // Plugin exists with same type - migrate its data
-        const migrated = migratePluginData(pluginId, {
+        const migrated = migratePluginData(handle, {
           version: existingEntry.__dataVersion,
           data: existingEntry.__data,
         });
         if (migrated) {
-          newPlugins[pluginId] = { __dataVersion: migrated.version, __data: migrated.data };
+          newPlugins[handle] = { __dataVersion: migrated.version, __data: migrated.data };
         }
         // If undefined returned, plugin is intentionally removed
       } else {
         // New plugin or type changed - create with initial data
-        const initial = createPluginData(pluginId);
-        newPlugins[pluginId] = { __dataVersion: initial.version, __data: initial.data };
+        const initial = createPluginData(handle);
+        newPlugins[handle] = { __dataVersion: initial.version, __data: initial.data };
       }
     } catch (error) {
       return {
         success: false,
         error: error instanceof Error ? error.message : String(error),
-        failedAt: pluginId,
+        failedAt: handle,
       };
     }
   }
@@ -384,14 +386,20 @@ export function migrateBlockStorage(
  * Gets plugin-specific data from block storage.
  * Accepts raw storage (any format) and normalizes internally.
  *
+ * When called with a typed PluginHandle<F>, the return type is automatically
+ * inferred from the factory's phantom `__types.data` field.
+ *
  * @param rawStorage - Raw block storage (may be legacy format or BlockStorage)
- * @param pluginId - The plugin instance id
- * @returns The plugin data
- * @throws If pluginId is not found in storage
+ * @param handle - The plugin handle (branded plugin instance id)
+ * @returns The plugin data, typed via factory inference
+ * @throws If plugin is not found in storage
  */
-export function getPluginData<TData = unknown>(rawStorage: unknown, pluginId: string): TData {
+export function getPluginData<F extends PluginFactoryLike>(
+  rawStorage: unknown,
+  handle: PluginHandle<F>,
+): InferFactoryData<F> {
   const storage = normalizeBlockStorage(rawStorage);
-  const pluginEntry = storage.__plugins?.[pluginId];
-  if (!pluginEntry) throw new Error(`Plugin '${pluginId}' not found in block storage`);
-  return pluginEntry.__data as TData;
+  const pluginEntry = storage.__plugins?.[handle];
+  if (!pluginEntry) throw new Error(`Plugin '${handle}' not found in block storage`);
+  return pluginEntry.__data as InferFactoryData<F>;
 }

package/src/block_storage_callbacks.ts

@@ -24,6 +24,7 @@ import {
   normalizeBlockStorage,
   updateStorageData,
 } from "./block_storage";
+import type { PluginHandle } from "./plugin_handle";
 
 import { stringifyJson, type StringifiedJson } from "@milaboratories/pl-model-common";
 import type { DataMigrationResult, DataVersioned } from "./block_migrations";
@@ -37,17 +38,17 @@ export interface MigrationHooks {
   migrateBlockData: (versioned: DataVersioned<unknown>) => DataMigrationResult<unknown>;
   getPluginRegistry: () => PluginRegistry;
   migratePluginData: (
-    pluginId: string,
+    handle: PluginHandle,
     versioned: DataVersioned<unknown>,
   ) => DataMigrationResult<unknown> | undefined;
-  createPluginData: (pluginId: string) => DataVersioned<unknown>;
+  createPluginData: (handle: PluginHandle) => DataVersioned<unknown>;
 }
 
 /** Dependencies for initial storage creation */
 export interface InitialStorageHooks {
   getDefaultBlockData: () => DataVersioned<unknown>;
   getPluginRegistry: () => PluginRegistry;
-  createPluginData: (pluginId: string) => DataVersioned<unknown>;
+  createPluginData: (handle: PluginHandle) => DataVersioned<unknown>;
 }
 
 /**
@@ -233,10 +234,10 @@ export function createInitialStorage(hooks: InitialStorageHooks): StringifiedJso
   const blockDefault = hooks.getDefaultBlockData();
   const pluginRegistry = hooks.getPluginRegistry();
 
-  const plugins: Record<string, VersionedData<unknown>> = {};
-  for (const pluginId of Object.keys(pluginRegistry)) {
-    const initial = hooks.createPluginData(pluginId);
-    plugins[pluginId] = { __dataVersion: initial.version, __data: initial.data };
+  const plugins: Record<PluginHandle, VersionedData<unknown>> = {};
+  for (const handle of Object.keys(pluginRegistry) as PluginHandle[]) {
+    const initial = hooks.createPluginData(handle);
+    plugins[handle] = { __dataVersion: initial.version, __data: initial.data };
   }
 
   const storage: BlockStorage = {

package/src/components/PFrameForGraphs.ts

@@ -1,55 +1,9 @@
-import type {
-  AxisId,
-  AxisSpecNormalized,
-  CanonicalizedJson,
-  PColumn,
-  PColumnSpec,
-  PFrameHandle,
-  PObjectId,
-} from "@milaboratories/pl-model-common";
-import {
-  Annotation,
-  canonicalizeJson,
-  getAxisId,
-  getColumnIdAndSpec,
-  LinkerMap,
-  matchAxisId,
-  readAnnotation,
-  readAnnotationJson,
-  stringifyJson,
-} from "@milaboratories/pl-model-common";
+import type { PColumn, PColumnSpec, PFrameHandle } from "@milaboratories/pl-model-common";
+import { Annotation, readAnnotationJson } from "@milaboratories/pl-model-common";
 import type { PColumnDataUniversal, RenderCtxBase } from "../render";
 import { getAllRelatedColumns, getRelatedColumns } from "../pframe_utils/columns";
-
-/** Create id for column copy with added keys in axes domains */
-const colId = (id: PObjectId, domains: (Record<string, string> | undefined)[]) => {
-  let wid = id.toString();
-  domains?.forEach((domain) => {
-    if (domain) {
-      for (const [k, v] of Object.entries(domain)) {
-        wid += k;
-        wid += v;
-      }
-    }
-  });
-  return wid;
-};
-
-/** All combinations with 1 key from each list */
-function getKeysCombinations(idsLists: AxisId[][]) {
-  if (!idsLists.length) {
-    return [];
-  }
-  let result: AxisId[][] = [[]];
-  idsLists.forEach((list) => {
-    const nextResult: AxisId[][] = [];
-    list.forEach((key) => {
-      nextResult.push(...result.map((resultItem) => [...resultItem, key]));
-    });
-    result = nextResult;
-  });
-  return result;
-}
+export type { AxesVault } from "../pframe_utils/axes";
+export { enrichCompatible, getAvailableWithLinkersAxes } from "../pframe_utils/axes";
 
 export function isHiddenFromGraphColumn(column: PColumnSpec): boolean {
   return !!readAnnotationJson(column, Annotation.HideDataFromGraphs);
@@ -59,123 +13,6 @@ export function isHiddenFromUIColumn(column: PColumnSpec): boolean {
   return !!readAnnotationJson(column, Annotation.HideDataFromUi);
 }
 
-export type AxesVault = Map<CanonicalizedJson<AxisId>, AxisSpecNormalized>;
-
-export function getAvailableWithLinkersAxes(
-  linkerColumns: PColumn<PColumnDataUniversal>[],
-  blockAxes: AxesVault,
-): AxesVault {
-  const linkerMap = LinkerMap.fromColumns(linkerColumns.map(getColumnIdAndSpec));
-  const availableAxes = linkerMap.getReachableByLinkersAxesFromAxesNormalized(
-    [...blockAxes.values()],
-    (linkerKeyId, sourceAxisId) => matchAxisId(sourceAxisId, linkerKeyId),
-  );
-
-  return new Map(
-    availableAxes.map((axisSpec) => {
-      const id = getAxisId(axisSpec);
-      return [canonicalizeJson(id), axisSpec];
-    }),
-  );
-}
-/** Add columns with fully compatible axes created from partial compatible ones */
-export function enrichCompatible<T extends Omit<PColumn<PColumnDataUniversal>, "data">>(
-  blockAxes: AxesVault,
-  columns: T[],
-): T[] {
-  return columns.flatMap((column) => getAdditionalColumnsForColumn(blockAxes, column));
-}
-
-function getAdditionalColumnsForColumn<T extends Omit<PColumn<PColumnDataUniversal>, "data">>(
-  blockAxes: AxesVault,
-  column: T,
-): T[] {
-  const columnAxesIds = column.spec.axesSpec.map(getAxisId);
-
-  if (columnAxesIds.every((id) => blockAxes.has(canonicalizeJson(id)))) {
-    return [column]; // the column is compatible with its own domains without modifications
-  }
-
-  // options with different possible domains for every axis of secondary column
-  const secondaryIdsOptions = columnAxesIds.map((id) => {
-    const result = [];
-    for (const [_, mainId] of blockAxes) {
-      if (matchAxisId(mainId, id) && !matchAxisId(id, mainId)) {
-        result.push(mainId);
-      }
-    }
-    return result;
-  });
-  // all possible combinations of axes with added domains
-  const secondaryIdsVariants = getKeysCombinations(secondaryIdsOptions);
-
-  // sets of added to column domain fields
-  const allAddedDomainValues = new Set<string>();
-  const addedNotToAllVariantsDomainValues = new Set<string>();
-  const addedByVariantsDomainValues = secondaryIdsVariants.map((idsList) => {
-    const addedSet = new Set<string>();
-    idsList.map((axisId, idx) => {
-      const d1 = column.spec.axesSpec[idx].domain;
-      const d2 = axisId.domain;
-      Object.entries(d2 ?? {}).forEach(([key, value]) => {
-        if (d1?.[key] === undefined) {
-          const item = JSON.stringify([key, value]);
-          addedSet.add(item);
-          allAddedDomainValues.add(item);
-        }
-      });
-      return {
-        ...axisId,
-        annotations: column.spec.axesSpec[idx].annotations,
-      };
-    });
-    return addedSet;
-  });
-  [...allAddedDomainValues].forEach((addedPart) => {
-    if (addedByVariantsDomainValues.some((s) => !s.has(addedPart))) {
-      addedNotToAllVariantsDomainValues.add(addedPart);
-    }
-  });
-
-  const additionalColumns = secondaryIdsVariants.map((idsList, idx) => {
-    const id = colId(
-      column.id,
-      idsList.map((id) => id.domain),
-    );
-
-    const label = readAnnotation(column.spec, Annotation.Label) ?? "";
-    const labelDomainPart = [...addedByVariantsDomainValues[idx]]
-      .filter((str) => addedNotToAllVariantsDomainValues.has(str))
-      .sort()
-      .map((v) => JSON.parse(v)?.[1]) // use in labels only domain values, but sort them by key to save the same order in all column variants
-      .join(" / ");
-
-    const annotations: Annotation = {
-      ...column.spec.annotations,
-      [Annotation.Graph.IsVirtual]: stringifyJson(true),
-    };
-    if (label || labelDomainPart) {
-      annotations[Annotation.Label] =
-        label && labelDomainPart ? label + " / " + labelDomainPart : label + labelDomainPart;
-    }
-
-    return {
-      ...column,
-      id: id as PObjectId,
-      spec: {
-        ...column.spec,
-        axesSpec: idsList.map((axisId, idx) => ({
-          ...axisId,
-          annotations: column.spec.axesSpec[idx].annotations,
-        })),
-        annotations,
-      },
-    };
-  });
-
-  return [column, ...additionalColumns];
-}
-
 /**
  The aim of createPFrameForGraphs: to create pframe with block’s columns and all compatible columns from result pool
  (including linker columns and all label columns).

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from "./block_state_patch";
 export * from "./block_state_util";
+export * from "./plugin_handle";
 export * from "./block_storage";
 export * from "./block_storage_facade";
 export * from "./block_model_legacy";
@@ -14,7 +15,7 @@ export {
   makeDataVersioned,
 } from "./block_migrations";
 export type { LegacyV1State } from "./block_migrations";
-export { PluginModel } from "./plugin_model";
+export * from "./plugin_model";
 export * from "./bconfig";
 export * from "./components";
 export * from "./config";