@milaboratories/pl-model-common 1.29.0 → 1.30.0

package/src/drivers/pframe/spec_driver.ts

@@ -1,4 +1,5 @@
 import type { Branded } from "@milaboratories/helpers";
+import type { PoolEntry } from "../../pool_entry";
 import type {
   AxisSpec,
   AxesSpec,
@@ -10,6 +11,7 @@ import type {
   ColumnValueType,
 } from "./spec";
 import type { PTableColumnId, PTableColumnSpec } from "./table_common";
+import { DataQuery, SpecQuery } from "./query";
 
 /** Matches a string value either exactly or by regex pattern */
 export type StringMatcher =
@@ -144,6 +146,33 @@ export interface DiscoverColumnsResponse {
   hits: DiscoverColumnsResponseHit[];
 }
 
+/** Request for deleting an entry from a given axes integration */
+export interface DeleteColumnRequest {
+  /** Already integrated axes with qualifications */
+  axes: ColumnAxesWithQualifications[];
+  /** Zero based index of the entry to be deleted */
+  delete: number;
+}
+
+/** Response from delete column */
+export interface DeleteColumnResponse {
+  axes: ColumnAxesWithQualifications[];
+}
+
+/** Response from evaluating a query against a PFrame. */
+export type EvaluateQueryResponse = {
+  /**
+   * The table specification describing the structure of the query result,
+   * including all axes and columns that will be present in the output.
+   */
+  tableSpec: PTableColumnSpec[];
+  /**
+   * The data layer query representation with numeric indices,
+   * suitable for execution by the data processing engine.
+   */
+  dataQuery: DataQuery;
+};
+
 /** Handle to a spec-only PFrame (no data, synchronous operations). */
 export type SpecFrameHandle = Branded<string, "SpecFrameHandle">;
 
@@ -155,17 +184,20 @@ export type SpecFrameHandle = Branded<string, "SpecFrameHandle">;
  * because the underlying WASM PFrame computes results immediately.
  */
 export interface PFrameSpecDriver {
-  /** Create a spec-only PFrame from column specs. Returns a handle. */
-  createSpecFrame(specs: Record<string, PColumnSpec>): SpecFrameHandle;
+  /** Create a spec-only PFrame from column specs. Returns a pool entry with handle and unref. */
+  createSpecFrame(specs: Record<string, PColumnSpec>): PoolEntry<SpecFrameHandle>;
 
   /** Discover columns compatible with given axes integration. */
-  specFrameDiscoverColumns(
+  discoverColumns(
     handle: SpecFrameHandle,
     request: DiscoverColumnsRequest,
   ): DiscoverColumnsResponse;
 
-  /** Dispose a spec frame, freeing WASM resources. */
-  disposeSpecFrame(handle: SpecFrameHandle): void;
+  /** Delete an entry from a given axes integration */
+  deleteColumn(handle: SpecFrameHandle, request: DeleteColumnRequest): DeleteColumnResponse;
+
+  /** Evaluates a query specification against this PFrame */
+  evaluateQuery(handle: SpecFrameHandle, request: SpecQuery): EvaluateQueryResponse;
 
   /** Expand index-based parentAxes in AxesSpec to resolved AxisId parents in AxesId. */
   expandAxes(spec: AxesSpec): AxesId;

package/src/errors.ts

@@ -28,6 +28,59 @@ export function isAggregateError(error: unknown): error is AggregateError {
   return error instanceof Error && error.name === "AggregateError";
 }
 
+export class ServiceError extends Error {
+  name = "ServiceError";
+}
+
+export function isServiceError(error: unknown): error is ServiceError {
+  return (
+    error instanceof Error &&
+    (error.name === "ServiceError" || error.name.startsWith("ServiceError."))
+  );
+}
+
+export class ServiceInvalidIdError extends ServiceError {
+  name = "ServiceError.InvalidId";
+}
+
+export function isServiceInvalidIdError(error: unknown): error is ServiceInvalidIdError {
+  return error instanceof Error && error.name === "ServiceError.InvalidId";
+}
+
+export class ServiceAlreadyRegisteredError extends ServiceError {
+  name = "ServiceError.AlreadyRegistered";
+}
+
+export function isServiceAlreadyRegisteredError(
+  error: unknown,
+): error is ServiceAlreadyRegisteredError {
+  return error instanceof Error && error.name === "ServiceError.AlreadyRegistered";
+}
+
+export class ServiceInjectionError extends ServiceError {
+  name = "ServiceError.Injection";
+}
+
+export function isServiceInjectionError(error: unknown): error is ServiceInjectionError {
+  return error instanceof Error && error.name === "ServiceError.Injection";
+}
+
+export class ServiceNotRegisteredError extends ServiceError {
+  name = "ServiceError.NotRegistered";
+}
+
+export function isServiceNotRegisteredError(error: unknown): error is ServiceNotRegisteredError {
+  return error instanceof Error && error.name === "ServiceError.NotRegistered";
+}
+
+export class ServiceMethodNotFoundError extends ServiceError {
+  name = "ServiceError.MethodNotFound";
+}
+
+export function isServiceMethodNotFoundError(error: unknown): error is ServiceMethodNotFoundError {
+  return error instanceof Error && error.name === "ServiceError.MethodNotFound";
+}
+
 export class PFrameError extends Error {
   name = "PFrameError";
 }

package/src/flags/block_flags.ts

@@ -1,3 +1,4 @@
+import type { ServiceRequireFlags } from "../services";
 import type { ArrayTypeUnion, Assert, Is, IsSubtypeOf } from "./type_utils";
 
 /**
@@ -20,7 +21,7 @@ export type BlockCodeKnownFeatureFlags = {
   readonly requiresModelAPIVersion?: number;
   readonly requiresUIAPIVersion?: number;
   readonly requiresCreatePTable?: number;
-};
+} & ServiceRequireFlags;
 
 export const AllSupportsFeatureFlags = ["supportsLazyState", "supportsPframeQueryRanking"] as const;
 
@@ -42,9 +43,11 @@ type _KnownFlagsAreValidFlags = Assert<
 
 // This check ensures that all keys in BlockConfigV3FeatureFlags are covered in the arrays above.
 // It will produce a compile-time error if there's a mismatch.
+// Adding a service to Services automatically satisfies this assertion via ServiceRequireFlags.
 type _AllFlagsAreCovered = Assert<
   Is<
     keyof BlockCodeKnownFeatureFlags,
-    ArrayTypeUnion<typeof AllRequiresFeatureFlags, typeof AllSupportsFeatureFlags>
+    | ArrayTypeUnion<typeof AllRequiresFeatureFlags, typeof AllSupportsFeatureFlags>
+    | keyof ServiceRequireFlags
   >
 >;

package/src/index.ts

@@ -18,3 +18,5 @@ export * from "./base64";
 export * from "./util";
 export * from "./httpAuth";
 export * from "./resource_types";
+export * from "./services";
+export * from "./pool_entry";

package/src/pool_entry.ts

@@ -0,0 +1,42 @@
+export interface PoolEntry<K extends string = string, R extends {} = {}> extends Disposable {
+  /** Resource key, calculated using provided `calculateParamsKey` function */
+  readonly key: K;
+
+  /** Resource itself created by `createNewResource` function */
+  readonly resource: R;
+
+  /**
+   * Release the reference. Idempotent.
+   * Same as `[Symbol.dispose]()` — provided as a named function
+   * for use in callbacks (e.g. `addOnDestroy(entry.unref)`).
+   */
+  readonly unref: () => void;
+}
+
+/**
+ * Wraps a PoolEntry for use with `using`. Auto-calls `unref()` at end of scope
+ * unless `keep()` is called to transfer ownership to the caller.
+ */
+export class PoolEntryGuard<K extends string = string, R extends {} = {}> implements Disposable {
+  private kept = false;
+
+  constructor(readonly entry: PoolEntry<K, R>) {}
+
+  get key(): K {
+    return this.entry.key;
+  }
+
+  get resource(): R {
+    return this.entry.resource;
+  }
+
+  /** Disarm the guard — caller takes ownership of the entry. */
+  keep(): PoolEntry<K, R> {
+    this.kept = true;
+    return this.entry;
+  }
+
+  [Symbol.dispose](): void {
+    if (!this.kept) this.entry.unref();
+  }
+}

package/src/services/index.ts

@@ -0,0 +1,5 @@
+export * from "./service_types";
+export * from "./service_registry";
+export * from "./service_declarations";
+export * from "./service_capabilities";
+export * from "./service_injectors";

package/src/services/service_capabilities.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  SERVICE_CAPABILITY_FLAGS,
+  registerServiceCapabilities,
+  resolveRequiredServices,
+  getMethodNames,
+  isKnownServiceName,
+} from "./service_capabilities";
+import { Services } from "./service_declarations";
+
+describe("SERVICE_CAPABILITY_FLAGS", () => {
+  it("should have one flag per service", () => {
+    expect(SERVICE_CAPABILITY_FLAGS).toHaveLength(Object.keys(Services).length);
+  });
+
+  it("should derive requires* flag names from Services keys", () => {
+    for (const key of Object.keys(Services)) {
+      expect(SERVICE_CAPABILITY_FLAGS).toContain(`requires${key}`);
+    }
+  });
+});
+
+describe("registerServiceCapabilities", () => {
+  it("should call register once per service with (flag, true)", () => {
+    const register = vi.fn();
+    registerServiceCapabilities(register);
+    expect(register).toHaveBeenCalledTimes(Object.keys(Services).length);
+    for (const call of register.mock.calls) {
+      expect(call[0]).toMatch(/^requires[A-Z]/);
+      expect(call[1]).toBe(true);
+    }
+  });
+});
+
+describe("resolveRequiredServices", () => {
+  it("should return empty array for undefined flags", () => {
+    expect(resolveRequiredServices(undefined)).toEqual([]);
+  });
+
+  it("should return empty array for flags without requires*", () => {
+    expect(resolveRequiredServices({ supportsLazyState: true })).toEqual([]);
+  });
+
+  it("should return empty array when requires* is false", () => {
+    expect(resolveRequiredServices({ requiresPFrameSpec: false })).toEqual([]);
+  });
+
+  it("should resolve a single required service", () => {
+    const result = resolveRequiredServices({ requiresPFrameSpec: true });
+    expect(result).toEqual([Services.PFrameSpec]);
+  });
+
+  it("should resolve multiple required services", () => {
+    const result = resolveRequiredServices({
+      requiresPFrameSpec: true,
+      requiresPFrame: true,
+    });
+    expect(result).toContain(Services.PFrameSpec);
+    expect(result).toContain(Services.PFrame);
+    expect(result).toHaveLength(2);
+  });
+
+  it("should ignore non-boolean requires* values", () => {
+    const result = resolveRequiredServices({
+      requiresPFrameSpec: true,
+      requiresModelAPIVersion: 2,
+    });
+    expect(result).toEqual([Services.PFrameSpec]);
+  });
+});
+
+describe("isKnownServiceName", () => {
+  it("should return true for registered service names", () => {
+    for (const id of Object.values(Services)) {
+      expect(isKnownServiceName(id as string)).toBe(true);
+    }
+  });
+
+  it("should return false for unknown names", () => {
+    expect(isKnownServiceName("nonexistent")).toBe(false);
+  });
+});
+
+describe("getMethodNames", () => {
+  it("should return own method names", () => {
+    const obj = {
+      foo() {},
+      bar() {},
+      baz: 42,
+    };
+    const names = getMethodNames(obj as any);
+    expect(names).toContain("foo");
+    expect(names).toContain("bar");
+    expect(names).not.toContain("baz");
+  });
+
+  it("should include prototype methods", () => {
+    class Base {
+      baseMethod() {}
+    }
+    class Child extends Base {
+      childMethod() {}
+    }
+    const names = getMethodNames(new Child() as any);
+    expect(names).toContain("baseMethod");
+    expect(names).toContain("childMethod");
+    expect(names).not.toContain("constructor");
+  });
+
+  it("should not include getters", () => {
+    const obj = Object.create(null, {
+      method: { value: () => {}, enumerable: true },
+      getter: { get: () => 42, enumerable: true },
+    });
+    const names = getMethodNames(obj);
+    expect(names).toContain("method");
+    expect(names).not.toContain("getter");
+  });
+});

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);
+  });
+});