@milaboratories/pl-model-common 1.29.0 → 1.31.0

package/src/services/service_capabilities.ts

@@ -0,0 +1,64 @@
+import type { ServiceName, ServiceRequireFlags } from "./service_types";
+import { Services } from "./service_declarations";
+import type { SupportedRequirement } from "../flags/flag_utils";
+
+/**
+ * All service-related `requires*` capability flag names, auto-derived from Services.
+ * Single source of truth — use this everywhere runtime capabilities are registered.
+ */
+export const SERVICE_CAPABILITY_FLAGS: readonly SupportedRequirement[] = Object.keys(Services).map(
+  (key) => `requires${key}` as SupportedRequirement,
+);
+
+/**
+ * Register all service capability flags with the given callback.
+ * Works with both `RuntimeCapabilities.addSupportedRequirement`
+ * and `MiddleLayer.addRuntimeCapability`.
+ */
+export function registerServiceCapabilities(
+  register: (flag: SupportedRequirement, value: true) => void,
+): void {
+  for (const flag of SERVICE_CAPABILITY_FLAGS) {
+    register(flag, true);
+  }
+}
+
+/**
+ * Resolve which services are required by the given feature flags.
+ * Accepts Record<string, unknown> so it works with both BlockCodeKnownFeatureFlags
+ * (from middle layer) and Zod-parsed records (from preload).
+ */
+export function resolveRequiredServices(flags: Record<string, unknown> | undefined): ServiceName[] {
+  if (!flags) return [];
+  return (Object.keys(Services) as (keyof typeof Services)[])
+    .filter((key) => flags[`requires${key}`] === true)
+    .map((key) => Services[key]);
+}
+
+export type KnownServiceName = (typeof Services)[keyof typeof Services] & string;
+
+export function isKnownServiceName(name: string): name is KnownServiceName {
+  return Object.values(Services).some((v) => v === name);
+}
+
+/** All service require flags set to true, auto-generated from Services.
+ *  Used to distinguish service-related feature flags from non-service flags. */
+export const SERVICE_FEATURE_FLAGS: { readonly [K in keyof ServiceRequireFlags]-?: true } =
+  Object.fromEntries(Object.keys(Services).map((key) => [`requires${key}`, true])) as any;
+
+/** Introspect method names on an instance (including prototype chain).
+ *  Uses Object.getOwnPropertyDescriptor to avoid triggering getters. */
+export function getMethodNames<T extends object>(instance: T): string[] {
+  const methods = new Set<string>();
+  let proto: object | null = instance;
+  while (proto && proto !== Object.prototype) {
+    for (const key of Object.getOwnPropertyNames(proto)) {
+      const descriptor = Object.getOwnPropertyDescriptor(proto, key);
+      if (key !== "constructor" && typeof descriptor?.value === "function") {
+        methods.add(key);
+      }
+    }
+    proto = Object.getPrototypeOf(proto);
+  }
+  return [...methods];
+}

package/src/services/service_declarations.ts

@@ -0,0 +1,25 @@
+/**
+ * Service declarations — add new services here.
+ *
+ * After adding a service, fix type errors in these files:
+ *
+ * Model side:
+ * - lib/node/pl-middle-layer/src/js_render/service_injectors.ts — VM bridge for workflow scripts
+ * - lib/node/pl-middle-layer/src/middle_layer/middle_layer.ts — ModelServiceRegistry factory
+ *
+ * UI side:
+ * - lib/model/common/src/services/service_injector_factory.ts — driver method wrappers (node services only)
+ * - sdk/ui-vue/src/internal/createAppV3.ts — UiServiceRegistry factory
+ *
+ * Optional:
+ * - sdk/model/src/services/block_service_flags.ts — only if default-required by all blocks
+ */
+
+import type { PFrameDriver, PFrameModelDriver } from "../drivers/pframe/driver";
+import type { PFrameSpecDriver } from "../drivers/pframe/spec_driver";
+import { service } from "./service_types";
+
+export const Services = {
+  PFrameSpec: service<PFrameSpecDriver, PFrameSpecDriver>()({ type: "wasm", name: "pframeSpec" }),
+  PFrame: service<PFrameModelDriver, PFrameDriver>()({ type: "node", name: "pframe" }),
+};

package/src/services/service_injector_factory.ts

@@ -0,0 +1,27 @@
+/**
+ * UI service injector factory.
+ *
+ * When adding a new node service, add its method wrappers here.
+ * Everything else (SERVICE_METHOD_MAP, buildServiceInfo, UiServiceInjectorMap)
+ * auto-derives from this factory + Services in service_declarations.ts.
+ */
+
+import type { DriverKit } from "../driver_kit";
+import type { UiServiceInjectorMap } from "./service_injectors";
+
+export function createUiServiceInjectors(driverKit: DriverKit): UiServiceInjectorMap {
+  const { pFrameDriver } = driverKit;
+  return {
+    PFrame: {
+      findColumns: (handle, request) => pFrameDriver.findColumns(handle, request),
+      getColumnSpec: (handle, columnId) => pFrameDriver.getColumnSpec(handle, columnId),
+      listColumns: (handle) => pFrameDriver.listColumns(handle),
+      calculateTableData: (handle, request, range) =>
+        pFrameDriver.calculateTableData(handle, request, range),
+      getUniqueValues: (handle, request) => pFrameDriver.getUniqueValues(handle, request),
+      getShape: (handle) => pFrameDriver.getShape(handle),
+      getSpec: (handle) => pFrameDriver.getSpec(handle),
+      getData: (handle, columnIndices, range) => pFrameDriver.getData(handle, columnIndices, range),
+    },
+  };
+}

package/src/services/service_injectors.ts

@@ -0,0 +1,79 @@
+/**
+ * UI service injectors — auto-derived types, method map, and service info builder.
+ *
+ * The factory (createUiServiceInjectors) lives in service_injector_factory.ts —
+ * that's the only file to edit when adding a new node service.
+ */
+
+import type { InferServiceKind, InferServiceUi, ServiceBrand, ServiceName } from "./service_types";
+import type { DriverKit } from "../driver_kit";
+import { Services } from "./service_declarations";
+import { getMethodNames, resolveRequiredServices } from "./service_capabilities";
+import { createUiServiceInjectors } from "./service_injector_factory";
+
+export { createUiServiceInjectors } from "./service_injector_factory";
+
+type NodeServiceKeys = {
+  [K in keyof typeof Services]: InferServiceKind<ServiceBrand<(typeof Services)[K]>> extends "node"
+    ? K
+    : never;
+}[keyof typeof Services];
+
+/** Auto-derived map of node service keys to their UI-side driver interfaces. */
+export type UiServiceInjectorMap = {
+  [K in NodeServiceKeys]: InferServiceUi<ServiceBrand<(typeof Services)[K]>>;
+};
+
+let cachedKit: DriverKit | undefined;
+let cachedInjectors: UiServiceInjectorMap | undefined;
+
+function getOrCreateInjectors(driverKit: DriverKit): UiServiceInjectorMap {
+  if (!cachedInjectors || cachedKit !== driverKit) {
+    cachedKit = driverKit;
+    cachedInjectors = createUiServiceInjectors(driverKit);
+  }
+  return cachedInjectors;
+}
+
+/** Resolve the injector for a given service ID. Caches injectors per DriverKit reference. */
+export function resolveUiInjector(
+  driverKit: DriverKit,
+  serviceId: ServiceName,
+): UiServiceInjectorMap[keyof UiServiceInjectorMap] | null {
+  const injectors = getOrCreateInjectors(driverKit);
+  const key = Object.keys(Services).find(
+    (k) => Services[k as keyof typeof Services] === serviceId,
+  ) as NodeServiceKeys | undefined;
+  if (!key) return null;
+  return injectors[key];
+}
+
+/**
+ * Static map of ServiceName → method names, auto-derived from the injector shape.
+ * Computed once at module load. The stub DriverKit is never called — it only
+ * provides a target so the closures in createUiServiceInjectors have own-property
+ * keys that getMethodNames can introspect.
+ */
+export const SERVICE_METHOD_MAP: Readonly<Record<string, string[]>> = (() => {
+  const stubKit = new Proxy({} as DriverKit, {
+    get: () => new Proxy({}, { get: () => () => {} }),
+  });
+  const injectors = createUiServiceInjectors(stubKit);
+  const result: Record<string, string[]> = {};
+  for (const key of Object.keys(Services) as (keyof typeof Services)[]) {
+    const serviceId = Services[key];
+    const injector = injectors[key as NodeServiceKeys];
+    result[serviceId] = injector ? getMethodNames(injector) : [];
+  }
+  return result;
+})();
+
+/** Build service info for a block from its feature flags. */
+export function buildServiceInfo(
+  featureFlags: Record<string, unknown>,
+): Record<ServiceName, string[]> {
+  const serviceIds = resolveRequiredServices(featureFlags);
+  return Object.fromEntries(
+    serviceIds.map((id) => [id, SERVICE_METHOD_MAP[id as string] ?? []]),
+  ) as Record<ServiceName, string[]>;
+}

package/src/services/service_registry.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect, vi } from "vitest";
+import { ModelServiceRegistry, UiServiceRegistry } from "./service_registry";
+import { service } from "./service_types";
+
+// Create test services with distinct types
+const TestServices = {
+  Alpha: service<{ alphaModel: () => void }, { alphaUi: () => void }>()({
+    type: "wasm",
+    name: "alpha",
+  }),
+  Beta: service<{ betaModel: () => void }, { betaUi: () => void }>()({
+    type: "node",
+    name: "beta",
+  }),
+};
+
+describe("ModelServiceRegistry", () => {
+  it("should lazily instantiate service on first get()", () => {
+    const factory = vi.fn(() => ({ alphaModel: () => {} }));
+    const registry = new ModelServiceRegistry(TestServices, {
+      Alpha: factory,
+      Beta: null,
+    });
+    expect(factory).not.toHaveBeenCalled();
+    registry.get(TestServices.Alpha);
+    expect(factory).toHaveBeenCalledTimes(1);
+  });
+
+  it("should cache instance on subsequent get() calls", () => {
+    const factory = vi.fn(() => ({ alphaModel: () => {} }));
+    const registry = new ModelServiceRegistry(TestServices, {
+      Alpha: factory,
+      Beta: null,
+    });
+    const first = registry.get(TestServices.Alpha);
+    const second = registry.get(TestServices.Alpha);
+    expect(first).toBe(second);
+    expect(factory).toHaveBeenCalledTimes(1);
+  });
+
+  it("should return null for services with null factory", () => {
+    const registry = new ModelServiceRegistry(TestServices, {
+      Alpha: () => ({ alphaModel: () => {} }),
+      Beta: null,
+    });
+    expect(registry.get(TestServices.Beta)).toBeNull();
+  });
+
+  it("should throw for unknown service IDs", () => {
+    const registry = new ModelServiceRegistry(TestServices, {
+      Alpha: () => ({ alphaModel: () => {} }),
+      Beta: null,
+    });
+    expect(() => registry.get("unknown" as any)).toThrow(/not registered/);
+  });
+});
+
+describe("UiServiceRegistry", () => {
+  it("should lazily instantiate UI service", () => {
+    const factory = vi.fn(() => ({ alphaUi: () => {} }));
+    const registry = new UiServiceRegistry(TestServices, {
+      Alpha: factory,
+      Beta: null,
+    });
+    expect(factory).not.toHaveBeenCalled();
+    registry.get(TestServices.Alpha);
+    expect(factory).toHaveBeenCalledTimes(1);
+  });
+});

package/src/services/service_registry.ts

@@ -0,0 +1,94 @@
+import type {
+  ServiceTypesLike,
+  InferServiceModel,
+  InferServiceUi,
+  ServiceName,
+  ModelServiceFactoryMap,
+  UiServiceFactoryMap,
+} from "./service_types";
+import { ServiceNotRegisteredError } from "../errors";
+import type { Services } from "./service_declarations";
+
+type RegistryName = "ModelServiceRegistry" | "UiServiceRegistry";
+type ServiceFactory = () => Record<string, Function>;
+
+class ServiceRegistryBase {
+  private readonly registryName: RegistryName;
+  private readonly knownServices = new Set<ServiceName>();
+  private readonly factories = new Map<ServiceName, ServiceFactory>();
+  private readonly instances = new Map<ServiceName, Record<string, Function>>();
+
+  protected constructor(
+    registryName: RegistryName,
+    serviceMap: Record<string, ServiceName>,
+    factories: Record<string, (() => unknown) | null>,
+  ) {
+    this.registryName = registryName;
+    for (const [key, factory] of Object.entries(factories)) {
+      const serviceId = serviceMap[key];
+      this.knownServices.add(serviceId);
+      if (factory !== null) {
+        this.factories.set(serviceId, factory as ServiceFactory);
+      }
+    }
+  }
+
+  async dispose(): Promise<void> {
+    for (const instance of this.instances.values()) {
+      if (Symbol.asyncDispose in instance) {
+        await (instance as AsyncDisposable)[Symbol.asyncDispose]();
+      } else if (Symbol.dispose in instance) {
+        (instance as Disposable)[Symbol.dispose]();
+      }
+    }
+    this.instances.clear();
+  }
+
+  protected getById(serviceId: ServiceName): Record<string, Function> | null {
+    if (!this.knownServices.has(serviceId)) {
+      throw new ServiceNotRegisteredError(
+        `Service "${serviceId}" is not registered in ${this.registryName}. Add it to the factory map.`,
+      );
+    }
+    if (this.instances.has(serviceId)) return this.instances.get(serviceId)!;
+
+    const factory = this.factories.get(serviceId);
+    if (!factory) return null;
+
+    const instance = factory();
+    this.instances.set(serviceId, instance);
+    return instance;
+  }
+}
+
+export class ModelServiceRegistry<
+  SMap extends Record<string, ServiceName> = typeof Services,
+> extends ServiceRegistryBase {
+  constructor(serviceMap: SMap, factories: ModelServiceFactoryMap<SMap>) {
+    super("ModelServiceRegistry", serviceMap, factories);
+  }
+
+  get<S extends ServiceTypesLike>(
+    id: ServiceName<S>,
+  ):
+    | ([unknown] extends [InferServiceModel<S>] ? Record<string, Function> : InferServiceModel<S>)
+    | null;
+  get(id: ServiceName): Record<string, Function> | null {
+    return this.getById(id);
+  }
+}
+
+export class UiServiceRegistry<
+  SMap extends Record<string, ServiceName> = typeof Services,
+> extends ServiceRegistryBase {
+  constructor(serviceMap: SMap, factories: UiServiceFactoryMap<SMap>) {
+    super("UiServiceRegistry", serviceMap, factories);
+  }
+
+  get<S extends ServiceTypesLike>(
+    id: ServiceName<S>,
+  ): ([unknown] extends [InferServiceUi<S>] ? Record<string, Function> : InferServiceUi<S>) | null;
+  get(id: ServiceName): Record<string, Function> | null {
+    return this.getById(id);
+  }
+}

package/src/services/service_types.ts

@@ -0,0 +1,114 @@
+import type { Branded } from "../branding";
+import { ServiceAlreadyRegisteredError, ServiceInvalidIdError } from "../errors";
+import type { Services } from "./service_declarations";
+
+export type ServiceTypesLike<
+  Model = unknown,
+  Ui = unknown,
+  Kind extends ServiceType = ServiceType,
+> = {
+  readonly __types?: { model: Model; ui: Ui; kind: Kind };
+};
+
+export type InferServiceModel<S extends ServiceTypesLike> =
+  S extends ServiceTypesLike<infer M, unknown, ServiceType> ? M : unknown;
+
+export type InferServiceUi<S extends ServiceTypesLike> =
+  S extends ServiceTypesLike<unknown, infer U, ServiceType> ? U : unknown;
+
+export type InferServiceKind<S extends ServiceTypesLike> =
+  S extends ServiceTypesLike<unknown, unknown, infer K> ? K : ServiceType;
+
+export type ServiceName<S extends ServiceTypesLike = ServiceTypesLike> = Branded<string, S>;
+
+export type ServiceType = "node" | "wasm";
+
+const SERVICE_ID_PATTERN = /^[a-zA-Z][a-zA-Z0-9]*$/;
+
+export const { service, isNodeService } = (() => {
+  const typeMap = new Map<string, ServiceType>();
+  return {
+    service<Model, Ui>() {
+      return <K extends ServiceType, N extends string>(options: {
+        readonly type: K;
+        readonly name: N;
+      }): Branded<N, ServiceTypesLike<Model, Ui, K>> => {
+        const { name, type } = options;
+        if (!SERVICE_ID_PATTERN.test(name)) {
+          throw new ServiceInvalidIdError(
+            `Invalid service ID "${name}": must match ${SERVICE_ID_PATTERN}`,
+          );
+        }
+        if (typeMap.has(name)) {
+          throw new ServiceAlreadyRegisteredError(`Service "${name}" already registered`);
+        }
+        typeMap.set(name, type);
+        return name as Branded<N, ServiceTypesLike<Model, Ui, K>>;
+      };
+    },
+    isNodeService(id: ServiceName): boolean {
+      return typeMap.get(id) === "node";
+    },
+  };
+})();
+
+export function serviceFnKey(serviceId: string, method = ""): string {
+  return `service:${serviceId}:${method}`;
+}
+
+export type ServiceBrand<T> =
+  T extends Branded<string, infer S extends ServiceTypesLike> ? S : never;
+
+export type ModelServiceFactoryMap<SMap extends Record<string, ServiceName>> = {
+  [K in keyof SMap]: (() => InferServiceModel<ServiceBrand<SMap[K]>>) | null;
+};
+
+export type UiServiceFactoryMap<SMap extends Record<string, ServiceName>> = {
+  [K in keyof SMap]: (() => InferServiceUi<ServiceBrand<SMap[K]>>) | null;
+};
+
+/** Contract between any service provider and any service consumer. */
+export interface ServiceDispatch {
+  getServiceNames(): ServiceName[];
+  getServiceMethods(serviceId: ServiceName): string[];
+  callServiceMethod(serviceId: ServiceName, method: string, ...args: unknown[]): unknown;
+}
+
+// Auto-derived types from the Services const in service_declarations.ts.
+// Adding a service to Services automatically updates all of these.
+
+type SMap = typeof Services;
+
+type ExtractServiceName<T> = T extends Branded<infer N extends string, any> ? N : never;
+
+/** Model-side service interfaces keyed by service name literal. */
+export type ModelServices = {
+  [K in keyof SMap as ExtractServiceName<SMap[K]>]: InferServiceModel<ServiceBrand<SMap[K]>>;
+};
+
+/** UI-side service interfaces keyed by service name literal. */
+export type UiServices = {
+  [K in keyof SMap as ExtractServiceName<SMap[K]>]: InferServiceUi<ServiceBrand<SMap[K]>>;
+};
+
+/** Map from Services keys to their unbranded string name literals. */
+export type ServiceNameLiterals = {
+  [K in keyof SMap]: ExtractServiceName<SMap[K]>;
+};
+
+/** Auto-derived requires* feature flags from Services keys. */
+export type ServiceRequireFlags = {
+  [K in keyof SMap as `requires${K & string}`]?: boolean;
+};
+
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (
+  k: infer I,
+) => void
+  ? I
+  : never;
+
+export type RequireServices<T extends ServiceName> = UnionToIntersection<
+  T extends Branded<infer N extends string, infer S extends ServiceTypesLike>
+    ? Record<N, InferServiceModel<S>>
+    : never
+>;