@milaboratories/pl-model-common 1.46.3 → 1.47.0

package/src/drivers/pframe/spec/spec.ts

@@ -174,7 +174,13 @@ export const Annotation = {
   },
 } as const;
 
-export type AnnotationDataStatus = "computing" | "ready" | "error" | "absent";
+export type AnnotationDataStatus =
+  | "missing"
+  | "resolving"
+  | "absent"
+  | "computing"
+  | "ready"
+  | "error";
 
 export type Annotation = Metadata &
   Partial<{
@@ -710,8 +716,6 @@ export interface PColumn<Data> extends PObject<Data> {
   readonly spec: PColumnSpec;
 }
 
-export type PColumnLazy<T> = PColumn<() => T>;
-
 /** Columns in a PFrame also have internal identifier, this object represents
  * combination of specs and such id */
 export interface PColumnIdAndSpec {

package/src/drivers/pframe/spec_driver.ts

@@ -1,6 +1,5 @@
 import type { Branded } from "@milaboratories/helpers";
 import type { PoolEntry } from "../../pool_entry";
-import type { PObjectId } from "../../pool";
 import type {
   AxisSpec,
   AxesSpec,
@@ -15,6 +14,7 @@ import type {
 import type { PTableColumnId, PTableColumnSpec } from "./table_common";
 import type { PTableRecordFilter } from "./table_calculate";
 import { DataQuery, DataQueryBooleanExpression, SpecQuery, SpecQueryJoinEntry } from "./query";
+import { PObjectId } from "../..";
 
 /** Matches a string value either exactly or by regex pattern */
 export type StringMatcher =
@@ -167,10 +167,10 @@ export interface DiscoverColumnsMappingVariant {
 export interface DiscoverColumnsResponseHit {
   /** The column that was found compatible */
   hit: PColumnIdAndSpec;
-  /** Possible ways to integrate this column with the existing set */
-  mappingVariants: DiscoverColumnsMappingVariant[];
   /** Linker steps traversed to reach this hit; empty for direct matches */
   path: DiscoverColumnsStepInfo[];
+  /** Possible ways to integrate this column with the existing set */
+  mappingVariants: DiscoverColumnsMappingVariant[];
 }
 
 /** Response from discover columns */

package/src/drivers/pframe/table_calculate.ts

@@ -4,7 +4,7 @@ import type { PObjectId } from "../../pool";
 import { assertNever } from "../../util";
 import { getAxisId, type PColumn } from "./spec/spec";
 import type { PColumnValues } from "./data_info";
-import type { SpecQuery } from "./query/query_spec";
+import type { SpecQuery, SpecQueryJoinEntry } from "./query/query_spec";
 import { canonicalizeJson } from "../../json";
 import { mapSpecQueryColumns } from "./query";
 
@@ -422,8 +422,18 @@ export function sortPTableDef(def: PTableDef<PObjectId>): PTableDef<PObjectId> {
   };
 }
 
-export function mapPTableDefV2<C1, C2>(def: PTableDefV2<C1>, cb: (c: C1) => C2): PTableDefV2<C2> {
-  return { query: mapSpecQueryColumns(def.query, cb) };
+export function mapPTableDefV2<C1, C2>(
+  def: PTableDefV2<C1>,
+  visitor: {
+    /** Transform column references in leaf nodes (column, sparseToDenseColumn). */
+    column: (c: C1) => C2;
+    /** Visit a node after its children have been traversed. */
+    node?: (node: SpecQuery<C2>) => SpecQuery<C2>;
+    /** Visit a join entry after its inner query has been traversed. */
+    joinEntry?: (entry: SpecQueryJoinEntry<C2>) => SpecQueryJoinEntry<C2>;
+  },
+): PTableDefV2<C2> {
+  return { query: mapSpecQueryColumns(def.query, visitor) };
 }
 
 export function mapJoinEntry<C1, C2>(entry: JoinEntry<C1>, cb: (c: C1) => C2): JoinEntry<C2> {

package/src/drivers/pframe/table_common.ts

@@ -1,5 +1,5 @@
-import type { PObjectId } from "../../pool";
 import type { AxisId, AxisSpec, PColumnSpec } from "./spec/spec";
+import type { ColumnUniversalId } from "./spec/ids";
 
 export type PTableColumnSpecAxis = {
   type: "axis";
@@ -9,7 +9,13 @@ export type PTableColumnSpecAxis = {
 
 export type PTableColumnSpecColumn = {
   type: "column";
-  id: PObjectId;
+  /**
+   * Leaf column id as it appears in the SpecQuery — may be a rich
+   * {@link ColumnUniversalId} (Discovered / Overridden / Filtered) or a bare
+   * {@link PObjectId}. The host resolver strips to bare via `extractPObjectId`
+   * before physical lookup.
+   */
+  id: ColumnUniversalId;
   spec: PColumnSpec;
 };
 
@@ -23,7 +29,8 @@ export type PTableColumnIdAxis = {
 
 export type PTableColumnIdColumn = {
   type: "column";
-  id: PObjectId;
+  /** @see PTableColumnSpecColumn.id */
+  id: ColumnUniversalId;
 };
 
 /** Unified PTable column identifier */

package/src/index.ts

@@ -22,3 +22,4 @@ export * from "./resource_types";
 export * from "./services";
 export * from "./pool_entry";
 export * from "./project_id";
+export * from "./columns";

package/src/pool/spec.ts

@@ -1,7 +1,8 @@
-import type { Branded } from "../branding";
-import type { JoinEntry, PColumn, PColumnLazy, PColumnSpec } from "../drivers";
+import type { JoinEntry, PColumn, PColumnSpec } from "../drivers";
 import { assertNever } from "../util";
-import type { ResultPoolEntry } from "./entry";
+import { PlRef } from "../ref";
+import { CanonicalizedJson, canonicalizeJson, parseJsonSafely } from "../json";
+import { Branded } from "@milaboratories/helpers";
 
 /** Any object exported into the result pool by the block always have spec attached to it */
 export type PObjectSpec = {
@@ -22,8 +23,65 @@ export type PObjectSpec = {
   readonly annotations?: Record<string, string>;
 };
 
+export type LocalPObjectKey = { resolvePath: string[]; name: string };
+export type LocalPObjectId = Branded<CanonicalizedJson<LocalPObjectKey>, "LocalPObjectId">;
+export type GlobalPObjectKey = PlRef;
+export type GlobalPObjectId = Branded<CanonicalizedJson<GlobalPObjectKey>, "GlobalPObjectId">;
 /** Stable PObject id */
-export type PObjectId = Branded<string, "PColumnId">;
+export type PObjectId = LocalPObjectId | GlobalPObjectId;
+
+export function isPObjectId(value: unknown): value is PObjectId {
+  if (typeof value !== "string") return false;
+  return isPObjectKey(parseJsonSafely(value));
+}
+
+export function isPObjectKey(value: unknown): value is LocalPObjectKey | GlobalPObjectKey {
+  return isLocalPObjectKey(value) || isGlobalPObjectKey(value);
+}
+
+export function createPObjectId(obj: LocalPObjectKey | GlobalPObjectKey): PObjectId {
+  if (isLocalPObjectKey(obj)) {
+    return createLocalPObjectId(obj.resolvePath, obj.name);
+  }
+  if (isGlobalPObjectKey(obj)) {
+    return createGlobalPObjectId(obj.blockId, obj.name);
+  }
+  throw new Error(`createPObjectId: unrecognized object key structure: ${JSON.stringify(obj)}`);
+}
+
+export function createLocalPObjectId(resolvePath: string[], name: string): PObjectId {
+  return canonicalizeJson({ resolvePath, name }) as PObjectId;
+}
+
+export function isLocalPObjectId(value: unknown): value is LocalPObjectId {
+  if (typeof value !== "string") return false;
+  return isLocalPObjectKey(parseJsonSafely<LocalPObjectKey>(value));
+}
+
+export function isLocalPObjectKey(value: unknown): value is LocalPObjectKey {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as LocalPObjectKey;
+  return Array.isArray(v.resolvePath) && typeof v.name === "string";
+}
+
+export function createGlobalPObjectId(blockId: string, exportName: string): PObjectId {
+  return canonicalizeJson({
+    __isRef: true,
+    blockId,
+    name: exportName,
+  } satisfies PlRef) as PObjectId;
+}
+
+export function isGlobalPObjectKey(value: unknown): value is GlobalPObjectKey {
+  if (typeof value !== "object" || value === null) return false;
+  return "__isRef" in value && "blockId" in value && "name" in value;
+}
+
+export function isGlobalPObjectId(value: unknown): value is GlobalPObjectId {
+  if (typeof value !== "string") return false;
+  const parsed = parseJsonSafely<GlobalPObjectKey>(value);
+  return isGlobalPObjectKey(parsed);
+}
 
 /**
  * Full PObject representation.
@@ -41,24 +99,16 @@ export interface PObject<Data> {
   readonly data: Data;
 }
 
-export function isPColumnSpec(spec: PObjectSpec): spec is PColumnSpec {
-  return spec.kind === "PColumn";
+export function isPObject<Data>(obj: unknown): obj is PObject<Data> {
+  return typeof obj === "object" && obj !== null && "id" in obj && "spec" in obj && "data" in obj;
 }
 
-export function isPColumn<T>(obj: PObject<T>): obj is PColumn<T> {
-  return isPColumnSpec(obj.spec);
+export function isPColumn<T>(obj: unknown): obj is PColumn<T> {
+  return isPObject(obj) && isPColumnSpec(obj.spec);
 }
 
-export function isPColumnSpecResult(
-  r: ResultPoolEntry<PObjectSpec>,
-): r is ResultPoolEntry<PColumnSpec> {
-  return isPColumnSpec(r.obj);
-}
-
-export function isPColumnResult<T>(
-  r: ResultPoolEntry<PObject<T>>,
-): r is ResultPoolEntry<PColumn<T>> {
-  return isPColumnSpec(r.obj.spec);
+export function isPColumnSpec(spec: PObjectSpec): spec is PColumnSpec {
+  return spec.kind === "PColumn";
 }
 
 export function ensurePColumn<T>(obj: PObject<T>): PColumn<T> {
@@ -66,10 +116,6 @@ export function ensurePColumn<T>(obj: PObject<T>): PColumn<T> {
   return obj;
 }
 
-export function mapPObjectData<D1, D2>(
-  pObj: PColumn<D1> | PColumnLazy<D1>,
-  cb: (d: D1) => D2,
-): PColumn<D2>;
 export function mapPObjectData<D1, D2>(pObj: PColumn<D1>, cb: (d: D1) => D2): PColumn<D2>;
 export function mapPObjectData<D1, D2>(
   pObj: PColumn<D1> | undefined,
@@ -88,7 +134,7 @@ export function mapPObjectData<D1, D2>(
     ? undefined
     : {
         ...pObj,
-        data: cb(typeof pObj.data === "function" ? pObj.data() : pObj.data),
+        data: cb(pObj.data),
       };
 }
 

package/src/services/service_declarations.ts

@@ -24,6 +24,10 @@
  */
 
 import type { DialogService } from "../dialog";
+import type {
+  ColumnsCollectionDriver,
+  ColumnsCollectionDriverModel,
+} from "../drivers/columns/columns_collection_driver";
 import type { PFrameDriver, PFrameModelDriver } from "../drivers/pframe/driver";
 import type { PFrameSpecDriver } from "../drivers/pframe/spec_driver";
 import { service } from "./service_types";
@@ -82,4 +86,31 @@ export const Services = {
     modelMethods: [] as const,
     uiMethods: ["showSaveDialog"] as const,
   }),
+  ColumnsCollection: service<
+    ColumnsCollectionDriverModel,
+    ColumnsCollectionDriverModel,
+    ColumnsCollectionDriver,
+    ColumnsCollectionDriver
+  >()({
+    type: "wasm",
+    name: "columnsCollection",
+    modelMethods: [
+      "create",
+      "isEmpty",
+      "isFinal",
+      "getColumns",
+      "addSource",
+      "discover",
+      "filter",
+    ] as const,
+    uiMethods: [
+      "create",
+      "isEmpty",
+      "isFinal",
+      "getColumns",
+      "addSource",
+      "discover",
+      "filter",
+    ] as const,
+  }),
 };

package/src/services/service_registry.ts

@@ -1,7 +1,7 @@
 import type {
   ServiceTypesLike,
-  InferServiceModel,
-  InferServiceUi,
+  InferServiceModelHost,
+  InferServiceUiHost,
   ServiceName,
   ModelServiceFactoryMap,
   UiServiceFactoryMap,
@@ -71,7 +71,9 @@ export class ModelServiceRegistry<
   get<S extends ServiceTypesLike>(
     id: ServiceName<S>,
   ):
-    | ([unknown] extends [InferServiceModel<S>] ? Record<string, Function> : InferServiceModel<S>)
+    | ([unknown] extends [InferServiceModelHost<S>]
+        ? Record<string, Function>
+        : InferServiceModelHost<S>)
     | null;
   get(id: ServiceName): Record<string, Function> | null {
     return this.getById(id);
@@ -87,7 +89,9 @@ export class UiServiceRegistry<
 
   get<S extends ServiceTypesLike>(
     id: ServiceName<S>,
-  ): ([unknown] extends [InferServiceUi<S>] ? Record<string, Function> : InferServiceUi<S>) | null;
+  ):
+    | ([unknown] extends [InferServiceUiHost<S>] ? Record<string, Function> : InferServiceUiHost<S>)
+    | null;
   get(id: ServiceName): Record<string, Function> | null {
     return this.getById(id);
   }

package/src/services/service_types.ts

@@ -7,18 +7,44 @@ export type ServiceTypesLike<
   Model = unknown,
   Ui = unknown,
   Kind extends ServiceType = ServiceType,
+  ModelHost = Model,
+  UiHost = Ui,
 > = {
-  readonly __types?: { model: Model; ui: Ui; kind: Kind };
+  readonly __types?: {
+    model: Model;
+    ui: Ui;
+    kind: Kind;
+    modelHost: ModelHost;
+    uiHost: UiHost;
+  };
 };
 
 export type InferServiceModel<S extends ServiceTypesLike> =
-  S extends ServiceTypesLike<infer M, unknown, ServiceType> ? M : unknown;
+  S extends ServiceTypesLike<infer M, unknown, ServiceType, unknown, unknown> ? M : unknown;
 
 export type InferServiceUi<S extends ServiceTypesLike> =
-  S extends ServiceTypesLike<unknown, infer U, ServiceType> ? U : unknown;
+  S extends ServiceTypesLike<unknown, infer U, ServiceType, unknown, unknown> ? U : unknown;
 
 export type InferServiceKind<S extends ServiceTypesLike> =
-  S extends ServiceTypesLike<unknown, unknown, infer K> ? K : ServiceType;
+  S extends ServiceTypesLike<unknown, unknown, infer K, unknown, unknown> ? K : ServiceType;
+
+/**
+ * Host-side shape stored in the model service registry. Differs from
+ * {@link InferServiceModel} only when the registered impl carries extra
+ * parameters (e.g. per-call `host` bindings) that the sandbox-view does
+ * not expose. Defaults to {@link InferServiceModel}.
+ */
+export type InferServiceModelHost<S extends ServiceTypesLike> =
+  S extends ServiceTypesLike<unknown, unknown, ServiceType, infer MH, unknown> ? MH : unknown;
+
+/**
+ * Host-side shape stored in the UI service registry. Differs from
+ * {@link InferServiceUi} only when the registered impl carries extra
+ * parameters that the UI-proxy view does not expose. Defaults to
+ * {@link InferServiceUi}.
+ */
+export type InferServiceUiHost<S extends ServiceTypesLike> =
+  S extends ServiceTypesLike<unknown, unknown, ServiceType, unknown, infer UH> ? UH : unknown;
 
 export type ServiceName<S extends ServiceTypesLike = ServiceTypesLike> = Branded<string, S>;
 
@@ -39,7 +65,7 @@ export const {
   const modelMethodsMap = new Map<string, readonly string[]>();
   const uiMethodsMap = new Map<string, readonly string[]>();
   return {
-    service<Model, Ui>() {
+    service<Model, Ui, ModelHost = Model, UiHost = Ui>() {
       return <
         K extends ServiceType,
         N extends string,
@@ -50,7 +76,7 @@ export const {
         readonly name: N;
         readonly modelMethods: MM;
         readonly uiMethods: UM;
-      }): Branded<N, ServiceTypesLike<Model, Ui, K>> => {
+      }): Branded<N, ServiceTypesLike<Model, Ui, K, ModelHost, UiHost>> => {
         const { name, type, modelMethods, uiMethods } = options;
         if (!SERVICE_ID_PATTERN.test(name)) {
           throw new ServiceInvalidIdError(
@@ -63,7 +89,7 @@ export const {
         typeMap.set(name, type);
         modelMethodsMap.set(name, modelMethods);
         uiMethodsMap.set(name, uiMethods);
-        return name as Branded<N, ServiceTypesLike<Model, Ui, K>>;
+        return name as Branded<N, ServiceTypesLike<Model, Ui, K, ModelHost, UiHost>>;
       };
     },
     isNodeService(id: ServiceName): boolean {
@@ -95,11 +121,11 @@ 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;
+  [K in keyof SMap]: (() => InferServiceModelHost<ServiceBrand<SMap[K]>>) | null;
 };
 
 export type UiServiceFactoryMap<SMap extends Record<string, ServiceName>> = {
-  [K in keyof SMap]: (() => InferServiceUi<ServiceBrand<SMap[K]>>) | null;
+  [K in keyof SMap]: (() => InferServiceUiHost<ServiceBrand<SMap[K]>>) | null;
 };
 
 /** Contract between any service provider and any service consumer. */