@platforma-sdk/model 1.8.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platforma-sdk/model",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Platforma.bio SDK / Block Model",
   "types": "./dist/index.d.ts",
   "main": "./dist/index.js",
@@ -20,11 +20,11 @@
   "dependencies": {
     "utility-types": "^3.11.0",
     "zod": "^3.23.8",
-    "@milaboratories/pl-model-common": "^1.6.1"
+    "@milaboratories/pl-model-common": "^1.6.2"
   },
   "devDependencies": {
     "typescript": "~5.5.4",
-    "vite": "^5.4.10",
+    "vite": "^5.4.11",
     "@types/jest": "^29.5.14",
     "jest": "^29.7.0",
     "@jest/globals": "^29.7.0",

package/src/bconfig/container.ts

@@ -0,0 +1,58 @@
+import { BlockRenderingMode } from '@milaboratories/pl-model-common';
+import { Code, TypedConfigOrString } from './types';
+import { BlockConfigV3 } from './v3';
+
+/** Container simplifying maintenance of forward and backward compatibility */
+export type BlockConfigContainer = {
+  /** Actual config */
+  readonly v3: Omit<BlockConfigV3, 'code'>;
+
+  /** Config code bundle */
+  readonly code?: Code;
+
+  //
+  // Fields below are used to read previous config versions
+  //
+
+  /**
+   * For backward compatibility
+   * @deprecated
+   */
+  readonly sdkVersion?: string;
+
+  /**
+   * For backward compatibility
+   * @deprecated
+   */
+  readonly renderingMode?: BlockRenderingMode;
+
+  /**
+   * For backward compatibility
+   * @deprecated
+   */
+  readonly initialArgs?: unknown;
+
+  /**
+   * For backward compatibility
+   * @deprecated
+   */
+  readonly canRun?: TypedConfigOrString;
+
+  /**
+   * For backward compatibility
+   * @deprecated
+   */
+  readonly inputsValid?: TypedConfigOrString;
+
+  /**
+   * For backward compatibility
+   * @deprecated
+   */
+  readonly sections?: TypedConfigOrString;
+
+  /**
+   * For backward compatibility
+   * @deprecated
+   */
+  readonly outputs?: Record<string, TypedConfigOrString>;
+};

package/src/bconfig/index.ts

@@ -0,0 +1,6 @@
+export * from './container';
+export * from './lambdas';
+export * from './normalization';
+export * from './types';
+export * from './utils';
+export * from './v3';

package/src/bconfig/lambdas.ts

@@ -0,0 +1,44 @@
+import { ConfigResult, PlResourceEntry, TypedConfig } from '../config';
+
+export type StdCtxArgsOnly<Args, UiState = undefined> = {
+  readonly $blockId: string;
+  readonly $args: Args;
+  readonly $ui: UiState;
+};
+
+export type StdCtx<Args, UiState = undefined> = StdCtxArgsOnly<Args, UiState> & {
+  readonly $prod: PlResourceEntry;
+  readonly $staging: PlResourceEntry;
+};
+
+export type ResolveCfgType<Cfg extends TypedConfig, Args, UiState = undefined> = ConfigResult<
+  Cfg,
+  StdCtx<Args, UiState>
+>;
+
+/** Additional information that may alter lambda rendering procedure. */
+export type ConfigRenderLambdaFlags = {
+  /**
+   * Tells the system that corresponding computable should be created with StableOnlyRetentive rendering mode.
+   * This flag can be overriden by the system.
+   * */
+  retentive?: boolean;
+
+  /**
+   * Tells the system that resulting computable has important side-effects, thus it's rendering is required even
+   * nobody is actively monitoring rendered values. Like file upload progress, that triggers upload itself.
+   * */
+  isActive?: boolean;
+};
+
+/** Creates branded Cfg type */
+export interface ConfigRenderLambda<Return = unknown> extends ConfigRenderLambdaFlags {
+  /** Type marker */
+  __renderLambda: true;
+
+  /** Reference to a callback registered inside the model code. */
+  handle: string;
+}
+
+export type ExtractFunctionHandleReturn<Func extends ConfigRenderLambda> =
+  Func extends ConfigRenderLambda<infer Return> ? Return : never;

package/src/bconfig/normalization.ts

@@ -0,0 +1,120 @@
+import { BlockConfigContainer } from './container';
+import { isConfigLambda, TypedConfigOrConfigLambda, TypedConfigOrString } from './types';
+import { BlockConfig } from './v3';
+
+export function downgradeCfgOrLambda(data: TypedConfigOrConfigLambda): TypedConfigOrString;
+export function downgradeCfgOrLambda(
+  data: TypedConfigOrConfigLambda | undefined
+): TypedConfigOrString | undefined;
+export function downgradeCfgOrLambda(
+  data: TypedConfigOrConfigLambda | undefined
+): TypedConfigOrString | undefined {
+  if (data === undefined) return undefined;
+  if (isConfigLambda(data)) return data.handle;
+  return data;
+}
+
+function upgradeCfgOrLambda(data: TypedConfigOrString): TypedConfigOrConfigLambda;
+function upgradeCfgOrLambda(
+  data: TypedConfigOrString | undefined
+): TypedConfigOrConfigLambda | undefined;
+function upgradeCfgOrLambda(
+  data: TypedConfigOrString | undefined
+): TypedConfigOrConfigLambda | undefined {
+  if (data === undefined) return undefined;
+  if (typeof data === 'string') return { __renderLambda: true, handle: data, retentive: false };
+  return data;
+}
+
+/**
+ * Takes universal config, and converts it into latest config structure.
+ *
+ * **Important**: This operation is not meant to be executed recusively.
+ *                In no circumstance result of this function should be persisted!
+ * */
+export function extractConfig(cfg: BlockConfigContainer): BlockConfig {
+  if (cfg.v3 !== undefined) {
+    // version 3
+    const {
+      initialArgs,
+      initialUiState,
+      inputsValid,
+      outputs,
+      renderingMode,
+      sdkVersion,
+      sections,
+      title
+    } = cfg.v3;
+    const { code } = cfg;
+    return {
+      initialArgs,
+      initialUiState,
+      inputsValid,
+      outputs,
+      renderingMode,
+      sdkVersion,
+      sections,
+      title,
+      code
+    };
+  } else if (cfg.inputsValid !== undefined) {
+    // version 2
+    const { sdkVersion, renderingMode, outputs, inputsValid, sections, initialArgs, code } = cfg;
+    const fields = Object.keys(cfg);
+    if (
+      sdkVersion === undefined ||
+      renderingMode === undefined ||
+      outputs === undefined ||
+      inputsValid === undefined ||
+      sections === undefined ||
+      initialArgs === undefined
+    )
+      throw new Error(
+        `Malformed config v2. SDK version ${sdkVersion}; Fields = ${fields.join(', ')}`
+      );
+    return {
+      sdkVersion,
+      renderingMode,
+      initialArgs,
+      outputs: Object.fromEntries(
+        Object.entries(outputs).map(([key, value]) => [key, upgradeCfgOrLambda(value)])
+      ),
+      inputsValid: upgradeCfgOrLambda(inputsValid),
+      sections: upgradeCfgOrLambda(sections),
+      initialUiState: undefined,
+      code
+    };
+  } else if (cfg.renderingMode !== undefined) {
+    // version 1
+    const { sdkVersion, canRun, renderingMode, outputs, sections, initialArgs, code } = cfg;
+    const fields = Object.keys(cfg);
+    if (
+      renderingMode === undefined ||
+      outputs === undefined ||
+      canRun === undefined ||
+      sections === undefined ||
+      initialArgs === undefined
+    )
+      throw new Error(
+        `Malformed config v1. SDK version ${sdkVersion}; Fields = ${fields.join(', ')}`
+      );
+    return {
+      sdkVersion: sdkVersion ?? 'unknown',
+      renderingMode,
+      initialArgs,
+      outputs: Object.fromEntries(
+        Object.entries(outputs).map(([key, value]) => [key, upgradeCfgOrLambda(value)])
+      ),
+      inputsValid: upgradeCfgOrLambda(canRun),
+      sections: upgradeCfgOrLambda(sections),
+      initialUiState: undefined,
+      code
+    };
+  } else {
+    const { sdkVersion } = cfg;
+    const fields = Object.keys(cfg);
+    throw new Error(
+      `Config format not supported: SDK = ${sdkVersion}; Fields = ${fields.join(', ')}`
+    );
+  }
+}

package/src/bconfig/types.ts

@@ -0,0 +1,18 @@
+import { TypedConfig } from '../config';
+import { ConfigRenderLambda } from './lambdas';
+
+export type Code = {
+  type: 'plain';
+  content: string;
+};
+
+export function isConfigLambda(
+  cfgOrFh: TypedConfigOrConfigLambda
+): cfgOrFh is ConfigRenderLambda {
+  return (cfgOrFh as any).__renderLambda === true;
+}
+
+export type TypedConfigOrConfigLambda = TypedConfig | ConfigRenderLambda;
+
+/** @deprecated */
+export type TypedConfigOrString = TypedConfig | string;

package/src/bconfig/utils.ts

@@ -0,0 +1,8 @@
+import { BlockSection } from "@milaboratories/pl-model-common";
+
+type OnlyString<S> = S extends string ? S : '';
+
+// prettier-ignore
+export type DeriveHref<S> = S extends readonly BlockSection[]
+  ? OnlyString<Extract<S[number], { type: 'link' }>['href']>
+  : never;

package/src/bconfig/v3.ts

@@ -0,0 +1,46 @@
+import { BlockRenderingMode } from '@milaboratories/pl-model-common';
+import { Code, TypedConfigOrConfigLambda } from './types';
+import { ConfigRenderLambda } from './lambdas';
+
+export type BlockConfigV3<
+  Args = unknown,
+  UiState = unknown,
+  Outputs extends Record<string, TypedConfigOrConfigLambda> = Record<
+    string,
+    TypedConfigOrConfigLambda
+  >
+> = {
+  /** SDK version used by the block */
+  readonly sdkVersion: string;
+
+  /** Main rendering mode for the block */
+  readonly renderingMode: BlockRenderingMode;
+
+  /** Initial value for the args when block is added to the project */
+  readonly initialArgs: Args;
+
+  /** Initial value for the args when block is added to the project */
+  readonly initialUiState: UiState;
+
+  /**
+   * Config to determine whether the block can be executed with current
+   * arguments.
+   *
+   * Optional to support earlier SDK version configs.
+   * */
+  readonly inputsValid: TypedConfigOrConfigLambda;
+
+  /** Configuration to derive list of section for the left overview panel */
+  readonly sections: TypedConfigOrConfigLambda;
+
+  /** Lambda to derive block title */
+  readonly title?: ConfigRenderLambda;
+
+  /** Configuration for the output cells */
+  readonly outputs: Outputs;
+
+  /** Config code bundle */
+  readonly code?: Code;
+};
+
+export type BlockConfig = BlockConfigV3;