@platforma-sdk/model 1.61.1 → 1.63.0

package/src/render/api.ts

@@ -1,12 +1,8 @@
 import type {
   AnchoredPColumnSelector,
   AnyFunction,
-  AxesId,
-  AxesSpec,
   AxisId,
   DataInfo,
-  DiscoverColumnsRequest,
-  DiscoverColumnsResponse,
   Option,
   PColumn,
   PColumnLazy,
@@ -19,8 +15,6 @@ import type {
   PObjectId,
   PObjectSpec,
   PSpecPredicate,
-  PTableColumnId,
-  PTableColumnSpec,
   PTableDef,
   PTableDefV2,
   PTableHandle,
@@ -29,7 +23,7 @@ import type {
   PlRef,
   ResolveAnchorsOptions,
   ResultCollection,
-  SingleAxisSelector,
+  ServiceName,
   SUniversalPColumnId,
   ValueOrError,
 } from "@milaboratories/pl-model-common";
@@ -61,8 +55,11 @@ import type {
   PluginHandle,
   PluginFactoryLike,
   InferFactoryData,
+  InferFactoryModelServices,
   InferFactoryParams,
 } from "../plugin_handle";
+import type { BlockDefaultModelServices } from "../services/service_resolve";
+import type { ModelServices as AllModelServices } from "@milaboratories/pl-model-common";
 import { TreeNodeAccessor, ifDef } from "./accessor";
 import type { FutureRef } from "./future";
 import type { AccessorHandle, GlobalCfgRenderCtx } from "./internal";
@@ -557,11 +554,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 = unknown, Data = unknown> {
+export abstract class RenderCtxBase<
+  Args = unknown,
+  Data = unknown,
+  ModelServices = Partial<AllModelServices>,
+> {
   protected readonly ctx: GlobalCfgRenderCtx;
+  private readonly requiredServiceNames: ServiceName[];
+  private cachedServices?: ModelServices;
 
-  constructor() {
+  constructor(requiredServiceNames: ServiceName[] = []) {
     this.ctx = getCfgRenderCtx();
+    this.requiredServiceNames = requiredServiceNames;
+  }
+
+  get services(): ModelServices {
+    if (this.cachedServices) return this.cachedServices;
+    const ctx = this.ctx;
+    const services = Object.freeze(
+      Object.fromEntries(
+        this.requiredServiceNames.map((id) => [
+          id,
+          Object.freeze(
+            Object.fromEntries(
+              (ctx.getServiceMethods(id) as string[]).map((method) => [
+                method,
+                (...args: unknown[]) => ctx.callServiceMethod(id, method, ...args),
+              ]),
+            ),
+          ),
+        ]),
+      ),
+    ) as ModelServices;
+    this.cachedServices = services;
+    return services;
   }
 
   private dataCache?: { v: Data };
@@ -717,41 +743,6 @@ export abstract class RenderCtxBase<Args = unknown, Data = unknown> {
     return this.ctx.getBlockLabel(blockId);
   }
 
-  //
-  // Spec Frames
-  //
-
-  public createSpecFrame(specs: Record<string, PColumnSpec>): string {
-    return this.ctx.createSpecFrame(specs);
-  }
-
-  public specFrameDiscoverColumns(
-    handle: string,
-    request: DiscoverColumnsRequest,
-  ): DiscoverColumnsResponse {
-    return this.ctx.specFrameDiscoverColumns(handle, request);
-  }
-
-  public disposeSpecFrame(handle: string): void {
-    this.ctx.disposeSpecFrame(handle);
-  }
-
-  public expandAxes(spec: AxesSpec): AxesId {
-    return this.ctx.expandAxes(spec);
-  }
-
-  public collapseAxes(ids: AxesId): AxesSpec {
-    return this.ctx.collapseAxes(ids);
-  }
-
-  public findAxis(spec: AxesSpec, selector: SingleAxisSelector): number {
-    return this.ctx.findAxis(spec, selector);
-  }
-
-  public findTableColumn(tableSpec: PTableColumnSpec[], selector: PTableColumnId): number {
-    return this.ctx.findTableColumn(tableSpec, selector);
-  }
-
   public getCurrentUnstableMarker(): string | undefined {
     return this.ctx.getCurrentUnstableMarker();
   }
@@ -770,7 +761,11 @@ export abstract class RenderCtxBase<Args = unknown, Data = unknown> {
 }
 
 /** Main entry point to the API available within model lambdas (like outputs, sections, etc..) for v3+ blocks */
-export class BlockRenderCtx<Args = unknown, Data = unknown> extends RenderCtxBase<Args, Data> {
+export class BlockRenderCtx<
+  Args = unknown,
+  Data = unknown,
+  ModelServices = BlockDefaultModelServices,
+> extends RenderCtxBase<Args, Data, ModelServices> {
   private argsCache?: { v: Args | undefined };
   public get args(): Args | undefined {
     if (this.argsCache === undefined) {
@@ -819,15 +814,19 @@ export class RenderCtxLegacy<Args = unknown, UiState = unknown> extends RenderCt
  *
  * @typeParam F - PluginFactoryLike phantom carrying data/params/outputs types
  */
-export class PluginRenderCtx<F extends PluginFactoryLike = PluginFactoryLike> extends RenderCtxBase<
-  unknown,
-  InferFactoryData<F>
-> {
+export class PluginRenderCtx<
+  F extends PluginFactoryLike = PluginFactoryLike,
+  ModelServices = InferFactoryModelServices<F>,
+> extends RenderCtxBase<unknown, InferFactoryData<F>, ModelServices> {
   private readonly handle: PluginHandle<F>;
   private readonly wrappedInputs: Record<string, () => unknown>;
 
-  constructor(handle: PluginHandle<F>, wrappedInputs: Record<string, () => unknown>) {
-    super();
+  constructor(
+    handle: PluginHandle<F>,
+    wrappedInputs: Record<string, () => unknown>,
+    requiredServiceNames: ServiceName[] = [],
+  ) {
+    super(requiredServiceNames);
     this.handle = handle;
     this.wrappedInputs = wrappedInputs;
   }

package/src/render/internal.ts

@@ -1,15 +1,5 @@
 import type { Optional } from "utility-types";
-import type {
-  AxesId,
-  AxesSpec,
-  Branded,
-  DiscoverColumnsRequest,
-  DiscoverColumnsResponse,
-  PTableColumnId,
-  PTableColumnSpec,
-  SingleAxisSelector,
-  StringifiedJson,
-} from "@milaboratories/pl-model-common";
+import type { Branded, StringifiedJson } from "@milaboratories/pl-model-common";
 import type { CommonFieldTraverseOps, FieldTraversalStep, ResourceType } from "./traversal_ops";
 import type {
   ArchiveFormat,
@@ -29,9 +19,9 @@ import type {
   ValueOrError,
   DataInfo,
   RangeBytes,
-  PColumnSpec,
 } from "@milaboratories/pl-model-common";
 import type { TreeNodeAccessor } from "./accessor";
+import type { ServiceDispatch } from "@milaboratories/pl-model-common";
 
 export const StagingAccessorName = "staging";
 export const MainAccessorName = "main";
@@ -168,31 +158,6 @@ export interface GlobalCfgRenderCtxMethods<AHandle = AccessorHandle, FHandle = F
     def: PTableDefV2<PColumn<AHandle | PColumnValues | DataInfo<AHandle>>>,
   ): PTableHandle;
 
-  //
-  // Spec Frames (synchronous WASM-based PFrame for spec-level operations)
-  //
-
-  createSpecFrame(specs: Record<string, PColumnSpec>): string;
-
-  specFrameDiscoverColumns(
-    handle: string,
-    request: DiscoverColumnsRequest,
-  ): DiscoverColumnsResponse;
-
-  disposeSpecFrame(handle: string): void;
-
-  /** Expand index-based parentAxes in AxesSpec to resolved AxisId parents in AxesId. */
-  expandAxes(spec: AxesSpec): AxesId;
-
-  /** Collapse resolved AxisId parents back to index-based parentAxes in AxesSpec. */
-  collapseAxes(ids: AxesId): AxesSpec;
-
-  /** Find the index of an axis matching the given selector. Returns -1 if not found. */
-  findAxis(spec: AxesSpec, selector: SingleAxisSelector): number;
-
-  /** Find the flat index of a table column matching the given selector. Returns -1 if not found. */
-  findTableColumn(tableSpec: PTableColumnSpec[], selector: PTableColumnId): number;
-
   //
   // Computable
   //
@@ -218,7 +183,7 @@ export const GlobalCfgRenderCtxFeatureFlags = {
   pFrameInSetFilterSupport: true as const,
 };
 
-export interface GlobalCfgRenderCtx extends GlobalCfgRenderCtxMethods {
+export interface GlobalCfgRenderCtx extends GlobalCfgRenderCtxMethods, ServiceDispatch {
   //
   // State: Args, UI State, Active Args
   //

package/src/services/block_services.ts

@@ -0,0 +1,17 @@
+import type { ServiceRequireFlags } from "@milaboratories/pl-model-common";
+import { resolveRequiredServices } from "@milaboratories/pl-model-common";
+
+/**
+ * Services required by all V3 blocks by default.
+ * Edit this when a new service should be available to all blocks.
+ *
+ * Standalone module to avoid circular dependencies between block_model.ts
+ * and service type resolution.
+ */
+export const BLOCK_SERVICE_FLAGS = {
+  requiresPFrameSpec: true,
+} as const satisfies Partial<ServiceRequireFlags>;
+
+export type BlockServiceFlags = typeof BLOCK_SERVICE_FLAGS;
+
+export const blockServiceNames = resolveRequiredServices(BLOCK_SERVICE_FLAGS);

package/src/services/index.ts

@@ -0,0 +1,3 @@
+export * from "./block_services";
+export * from "./service_resolve";
+export * from "./service_bridge";

package/src/services/service_bridge.ts

@@ -0,0 +1,71 @@
+/**
+ * Runtime service bridge — builds lazy service objects from dispatch + registry.
+ * Used by the UI layer to provide typed service access.
+ */
+
+import type {
+  ServiceTypesLike,
+  InferServiceUi,
+  ServiceName,
+  ServiceDispatch,
+  UiServices as AllUiServices,
+} from "@milaboratories/pl-model-common";
+import { UiServiceRegistry } from "@milaboratories/pl-model-common";
+
+// Makes a remote node service appear local.
+// Given a service ID, returns an object implementing the service's UI interface.
+// Provided by the desktop app (e.g. backed by Electron IPC).
+export type NodeServiceProxy = <S extends ServiceTypesLike>(
+  serviceId: ServiceName<S>,
+) => InferServiceUi<S>;
+
+/**
+ * Builds a lazy services object from ServiceDispatch and UiServiceRegistry.
+ * Each service is instantiated on first access. Errors are cached to prevent
+ * repeated factory calls on failure.
+ */
+export function buildServices<S extends Partial<AllUiServices> = Partial<AllUiServices>>(
+  dispatch: ServiceDispatch,
+  registry: UiServiceRegistry,
+): S {
+  return Object.create(
+    null,
+    Object.fromEntries(
+      dispatch.getServiceNames().map((id) => {
+        let fetched = false;
+        let cached: unknown;
+        return [
+          id,
+          {
+            enumerable: true,
+            get() {
+              if (!fetched) {
+                fetched = true;
+                cached = registry.get(id);
+              }
+              return cached;
+            },
+          },
+        ];
+      }),
+    ),
+  );
+}
+
+/**
+ * Builds a NodeServiceProxy from a ServiceDispatch.
+ * Each service method call is forwarded to dispatch.callServiceMethod.
+ */
+export function createNodeServiceProxy(dispatch: ServiceDispatch): NodeServiceProxy {
+  return ((serviceId: ServiceName) =>
+    Object.freeze(
+      Object.fromEntries(
+        dispatch
+          .getServiceMethods(serviceId)
+          .map((method) => [
+            method,
+            async (...args: unknown[]) => dispatch.callServiceMethod(serviceId, method, ...args),
+          ]),
+      ),
+    )) as NodeServiceProxy;
+}

package/src/services/service_resolve.ts

@@ -0,0 +1,71 @@
+/**
+ * Type-level service resolution — auto-derives typed service maps from feature flags.
+ * No runtime code. No edits needed when adding a service.
+ */
+
+import type {
+  ServiceNameLiterals,
+  ModelServices,
+  UiServices,
+} from "@milaboratories/pl-model-common";
+import type { BlockServiceFlags } from "./block_services";
+
+export type { ModelServices, UiServices };
+
+// Flag name → service name literal: "requiresPFrameSpec" → "pframeSpec"
+type FlagToName<Flag extends string> = Flag extends `requires${infer K}`
+  ? K extends keyof ServiceNameLiterals
+    ? ServiceNameLiterals[K]
+    : never
+  : never;
+
+// Extract all required service name literals from feature flags
+type RequiredServiceNames<Flags> = {
+  [K in keyof Flags & `requires${string}`]: Flags[K] extends true ? FlagToName<K & string> : never;
+}[keyof Flags & `requires${string}`];
+
+// Resolve typed services from feature flags
+// { requiresPFrameSpec: true } -> { pframeSpec: PFrameSpecDriver }
+export type ResolveModelServices<Flags> = Pick<
+  ModelServices,
+  RequiredServiceNames<Flags> & keyof ModelServices
+>;
+
+export type ResolveUiServices<Flags> = Pick<
+  UiServices,
+  RequiredServiceNames<Flags> & keyof UiServices
+>;
+
+// Auto-derived from BLOCK_SERVICE_FLAGS.
+export type BlockDefaultModelServices = ResolveModelServices<BlockServiceFlags>;
+export type BlockDefaultUiServices = ResolveUiServices<BlockServiceFlags>;
+
+// Compile-time type assertions — verified by tsc, not executed at runtime.
+// Each @ts-expect-error proves the line below would be a type error.
+
+// Block default services include pframeSpec
+const _modelSpec: BlockDefaultModelServices["pframeSpec"] = undefined!;
+const _uiSpec: BlockDefaultUiServices["pframeSpec"] = undefined!;
+void _modelSpec;
+void _uiSpec;
+
+// Block default services do NOT include pframe (only plugins can request it)
+// @ts-expect-error pframe is not in default block model services
+const _modelPframe: BlockDefaultModelServices["pframe"] = undefined!;
+// @ts-expect-error pframe is not in default block UI services
+const _uiPframe: BlockDefaultUiServices["pframe"] = undefined!;
+void _modelPframe;
+void _uiPframe;
+
+// ResolveModelServices with false flag resolves to empty
+type _NoServices = ResolveModelServices<{ requiresPFrameSpec: false }>;
+// @ts-expect-error pframeSpec is not resolved when flag is false
+const _noSpec: _NoServices["pframeSpec"] = undefined!;
+void _noSpec;
+
+// ResolveModelServices with multiple flags resolves all
+type _Both = ResolveModelServices<{ requiresPFrameSpec: true; requiresPFrame: true }>;
+const _bothSpec: _Both["pframeSpec"] = undefined!;
+const _bothPframe: _Both["pframe"] = undefined!;
+void _bothSpec;
+void _bothPframe;