@platforma-sdk/model 1.79.24 → 1.80.0

package/src/components/PlDataTable/columnResolver.ts

@@ -0,0 +1,57 @@
+import type {
+  AxisId,
+  ColumnUniversalId,
+  PObjectId,
+  PTableColumnId,
+  PTableColumnIdColumn,
+} from "@milaboratories/pl-model-common";
+import { extractPObjectId, getAxisId, matchAxisId } from "@milaboratories/pl-model-common";
+import type { ColumnRecipe } from "../../columns";
+
+/**
+ * Resolves a user-supplied PTableColumnId against the discovered set of
+ * columns and axes. For column refs, accepts either the full recipe id (rich
+ * {@link ColumnUniversalId}) or the bare {@link PObjectId} and returns a ref
+ * carrying the recipe's full id — the same id that appears as the leaf in the
+ * emitted SpecQuery, so engine-side dedup is consistent with the resolver's
+ * view. Axis refs are checked against the union of axes spanned by the
+ * columns and pass through unchanged on hit.
+ * Returns `undefined` when the reference cannot be matched.
+ */
+export type ColumnResolver = (ref: PTableColumnId) => PTableColumnId | undefined;
+
+export function createColumnResolver(
+  columns: ColumnRecipe[],
+  deps?: { warn?: (msg: string) => void },
+): ColumnResolver {
+  const axisIds: AxisId[] = [];
+  for (const c of columns) {
+    for (const ax of c.getSpec().axesSpec) {
+      axisIds.push(getAxisId(ax));
+    }
+  }
+
+  const byFullId = new Map<ColumnUniversalId, ColumnRecipe>();
+  const byPObjectId = new Map<PObjectId, ColumnRecipe>();
+  for (const c of columns) {
+    byFullId.set(c.id, c);
+    const pid = extractPObjectId(c.id);
+    const existing = byPObjectId.get(pid);
+    if (existing === undefined) {
+      byPObjectId.set(pid, c);
+    } else if (existing.id !== c.id) {
+      deps?.warn?.(
+        `Ambiguous PObjectId ${pid}: recipe ids ${existing.id} and ${c.id} both match — keeping first.`,
+      );
+    }
+  }
+
+  return (ref: PTableColumnId): PTableColumnId | undefined => {
+    if (ref.type === "axis") {
+      return axisIds.some((a) => matchAxisId(ref.id, a)) ? ref : undefined;
+    }
+    const hit = byFullId.get(ref.id) ?? byPObjectId.get(extractPObjectId(ref.id));
+    if (hit === undefined) return undefined;
+    return { type: "column", id: hit.id } satisfies PTableColumnIdColumn;
+  };
+}

package/src/components/PlDataTable/createPlDataTable/createPTableDefV2.ts

@@ -1,25 +1,25 @@
 import type {
+  ColumnUniversalId,
   PColumn,
   PColumnIdAndSpec,
   PTableSorting,
   PTableDefV2,
-  DataInfo,
-  PColumnValues,
 } from "@milaboratories/pl-model-common";
 import { getColumnIdAndSpec } from "@milaboratories/pl-model-common";
-import type { PColumnDataUniversal, TreeNodeAccessor } from "../../../render";
+import type { PColumnDataUniversal } from "../../../render";
 import { isFunction } from "es-toolkit";
-import type { PlDataTableFilters } from "../typesV7";
+import type { PlDataTableFilters } from "../typesV8";
 import { createPTableDefV3 } from "./createPTableDefV3";
+import { ColumnLazyImpl } from "../../../columns";
 
 export function createPTableDefV2(params: {
-  columns: PColumn<PColumnDataUniversal>[];
-  labelColumns: PColumn<PColumnDataUniversal>[];
+  columns: PColumn<undefined | PColumnDataUniversal>[];
+  labelColumns: PColumn<undefined | PColumnDataUniversal>[];
   coreJoinType: "inner" | "full";
   filters: null | PlDataTableFilters;
   sorting: PTableSorting[];
   coreColumnPredicate?: (spec: PColumnIdAndSpec) => boolean;
-}): PTableDefV2<PColumn<TreeNodeAccessor | PColumnValues | DataInfo<TreeNodeAccessor>>> {
+}): PTableDefV2<ColumnUniversalId> {
   let coreColumns = params.columns;
   const secondaryColumns: typeof params.columns = [];
 
@@ -33,8 +33,8 @@ export function createPTableDefV2(params: {
   secondaryColumns.push(...params.labelColumns);
 
   return createPTableDefV3({
-    primary: coreColumns.map((column) => ({ column })),
-    secondary: secondaryColumns.map((column) => ({ entries: [{ column }] })),
+    primary: coreColumns.map((column) => ColumnLazyImpl.fromColumn(column)),
+    secondary: secondaryColumns.map((column) => ColumnLazyImpl.fromColumn(column)),
     primaryJoinType: params.coreJoinType,
     filters: params.filters,
     sorting: params.sorting,

package/src/components/PlDataTable/createPlDataTable/createPTableDefV3.ts

@@ -1,6 +1,7 @@
 import type {
   AxisQualification,
-  PColumn,
+  ColumnUniversalId,
+  PObjectId,
   PTableColumnId,
   PTableSorting,
   PTableDefV2,
@@ -8,53 +9,33 @@ import type {
   SpecQuery,
   SpecQueryExpression,
   SpecQueryJoinEntry,
-  PObjectId,
 } from "@milaboratories/pl-model-common";
 import { isBooleanExpression } from "@milaboratories/pl-model-common";
-import type { PColumnDataUniversal } from "../../../render";
 import { isNil } from "es-toolkit";
-import type { PlDataTableFilters } from "../typesV7";
+import type { PlDataTableFilters } from "../typesV8";
 import { distillFilterSpec, filterSpecToSpecQueryExpr } from "../../../filters";
 import type { Nil } from "@milaboratories/helpers";
+import type { ColumnRecipe } from "../../..";
+import { hitQualifications, queriesQualifications } from "../../../columns";
 
-/** Primary side — base row grid. */
-export type PrimaryEntry<Data> = {
-  column: PColumn<Data>;
-};
-
-/** Secondary side leaf — the hit column or a label column, optionally reached via a linker chain. */
-export type SecondaryEntry<Data> = {
-  column: PColumn<Data>;
-  /** For hit: `forHit`. For label/direct: omit. Applied to the outermost emitted join entry. */
-  qualifications?: AxisQualification[];
-  /**
-   * Linker chain leading to `column`, ordered from outermost to innermost.
-   * When present, the entry is emitted as nested `linkerJoin` operators —
-   * one per linker — wrapping the hit column. Binds this hit to this exact
-   * chain so the engine cannot reuse a sibling chain that happens to share
-   * axis name + domain.
-   */
-  linkers?: PColumn<Data>[];
-};
-
-/** Secondary group — one join subtree outer-joined onto primary. */
-export type SecondaryGroup<Data> = {
-  entries: SecondaryEntry<Data>[];
-  /** Per-variant qualifications applied to the cloned primary anchors on this group's side.
-   *  Keyed by `PrimaryEntry.column.id`. Omit → base primary used unqualified (labels, non-variant columns). */
-  primaryQualifications?: Record<PObjectId, AxisQualification[]>;
-};
-
-export function createPTableDefV3<Data = PColumnDataUniversal>(params: {
+/**
+ * Assemble a ptable def directly from recipes. Each secondary recipe is its own
+ * outer-joined subtree: `getQuery()` encodes its linker chain, and its
+ * hit-/queries-qualifications are derived on the spot via {@link hitQualifications}
+ * / {@link queriesQualifications} — no pre-extracted DTO. Bare leaves yield empty
+ * qualifications, so plain {@link ColumnRecipe} arrays (e.g. label columns) work
+ * unchanged.
+ */
+export function createPTableDefV3(params: {
   primaryJoinType: "inner" | "full";
-  primary: PrimaryEntry<Data>[];
-  secondary: SecondaryGroup<Data>[];
+  primary: ColumnRecipe[];
+  secondary: ColumnRecipe[];
   filters?: Nil | PlDataTableFilters;
   sorting?: Nil | PTableSorting[];
-}): PTableDefV2<PColumn<Data>> {
-  let query: SpecQuery<PColumn<Data>> = {
+}): PTableDefV2<ColumnUniversalId> {
+  let query: SpecQuery = {
     type: params.primaryJoinType === "inner" ? "innerJoin" : "fullJoin",
-    entries: params.primary.map((a) => toLeaf(a.column, [])),
+    entries: params.primary.map((c) => columnToJoinEntry(c, [])),
   };
 
   if (params.secondary.length > 0) {
@@ -62,11 +43,12 @@ export function createPTableDefV3<Data = PColumnDataUniversal>(params: {
       type: "outerJoin",
       primary: {
         entry: query,
-        qualifications: params.secondary.flatMap((g) =>
-          params.primary.flatMap((p) => g.primaryQualifications?.[p.column.id] ?? []),
-        ),
+        qualifications: params.secondary.flatMap((s) => {
+          const quals = queriesQualifications(s);
+          return params.primary.flatMap((p) => quals[p.id as PObjectId] ?? []);
+        }),
       },
-      secondary: params.secondary.flatMap((g) => g.entries.map((e) => toJoinEntry(e))),
+      secondary: params.secondary.map((c) => columnToJoinEntry(c, hitQualifications(c))),
     };
   }
 
@@ -95,7 +77,7 @@ export function createPTableDefV3<Data = PColumnDataUniversal>(params: {
       sortBy: params.sorting.map((s) => ({
         expression: columnIdToExpr(s.column),
         ascending: s.ascending,
-        nullsFirst: !s.naAndAbsentAreLeastValues,
+        nullsFirst: s.naAndAbsentAreLeastValues,
       })),
     };
   }
@@ -109,26 +91,12 @@ function columnIdToExpr(col: PTableColumnId): SpecQueryExpression {
     : { type: "columnRef", value: col.id };
 }
 
-function toLeaf<Data>(
-  col: PColumn<Data>,
-  qs: AxisQualification[],
-): SpecQueryJoinEntry<PColumn<Data>> {
+function columnToJoinEntry(
+  col: ColumnRecipe,
+  qualifications: readonly AxisQualification[],
+): SpecQueryJoinEntry {
   return {
-    entry: { type: "column", column: col },
-    qualifications: qs,
+    entry: col.getQuery(),
+    qualifications,
   };
 }
-
-function toJoinEntry<Data>(e: SecondaryEntry<Data>): SpecQueryJoinEntry<PColumn<Data>> {
-  const qs = e.qualifications ?? [];
-  if (isNil(e.linkers) || e.linkers.length === 0) return toLeaf(e.column, qs);
-
-  const folded = e.linkers.reduceRight<SpecQueryJoinEntry<PColumn<Data>>>(
-    (inner, linker) => ({
-      entry: { type: "linkerJoin", linker: { column: linker }, secondary: [inner] },
-      qualifications: [],
-    }),
-    toLeaf(e.column, []),
-  );
-  return { ...folded, qualifications: qs };
-}

package/src/components/PlDataTable/createPlDataTable/createPlDataTableV2.ts

@@ -1,20 +1,14 @@
 import type {
-  AxisId,
+  ColumnUniversalId,
+  FilterSpecNode,
   PColumn,
-  PObjectId,
-  PTableColumnId,
-  PTableColumnIdAxis,
   PTableColumnIdColumn,
-  CanonicalizedJson,
+  PTableSorting,
 } from "@milaboratories/pl-model-common";
 import {
   Annotation,
-  canonicalizeJson,
-  getAxisId,
   getColumnIdAndSpec,
   isLinkerColumn,
-  uniqueBy,
-  parseJson,
   PColumnName,
 } from "@milaboratories/pl-model-common";
 import type {
@@ -25,14 +19,21 @@ import type {
 } from "../../../render";
 import { allPColumnsReady, deriveLabels, PColumnCollection } from "../../../render";
 import { identity } from "es-toolkit";
-import type { CreatePlDataTableOps, PlDataTableModel } from "../typesV7";
+import type {
+  CreatePlDataTableOps,
+  PlDataTableFilters,
+  PlDataTableFilterSpecLeaf,
+  PlDataTableModel,
+} from "../typesV8";
 import { upgradePlDataTableStateV2 } from "../state-migration";
 import type { PlDataTableStateV2 } from "../state-migration";
 import { getMatchingLabelColumns } from "../labels";
-import { collectFilterSpecColumns } from "../../../filters/traverse";
-import { isEmpty } from "es-toolkit/compat";
+import { collectFilterSpecColumns, traverseFilterSpec } from "../../../filters/traverse";
 import { createPTableDefV2 } from "./createPTableDefV2";
 import { isColumnOptional } from "./utils";
+import { ColumnLazyImpl } from "../../../columns";
+import { createColumnResolver, type ColumnResolver } from "../columnResolver";
+import { isNil, type Nil } from "@milaboratories/helpers";
 
 /**
  * @deprecated This function is deprecated and will be removed in future. Please migrate to createPlDataTable with v3 options for improved column discovery and display configuration. See createPlDataTableOptionsV3 for details on the new options format and migration guidance.
@@ -81,52 +82,32 @@ export function createPlDataTableV2<A, U>(
 
   const fullColumns = [...columns, ...fullLabelColumns];
 
-  const fullColumnsAxes = uniqueBy(
-    fullColumns.flatMap((c) => c.spec.axesSpec.map((a) => getAxisId(a))),
-    (a) => canonicalizeJson<AxisId>(a),
+  const resolver = createColumnResolver(
+    fullColumns.map((c) => ColumnLazyImpl.fromColumn(c)),
+    { warn: ctx.logWarn.bind(ctx) },
   );
-  const fullColumnsIds: PTableColumnId[] = [
-    ...fullColumnsAxes.map((a) => ({ type: "axis", id: a }) satisfies PTableColumnIdAxis),
-    ...fullColumns.map((c) => ({ type: "column", id: c.id }) satisfies PTableColumnIdColumn),
-  ];
-  const fullColumnsIdsSet = new Set(fullColumnsIds.map((c) => canonicalizeJson<PTableColumnId>(c)));
-  const isValidColumnId = (id: string): boolean =>
-    fullColumnsIdsSet.has(id as CanonicalizedJson<PTableColumnId>);
-
-  // -- Filtering validation --
-  const filters = tableStateNormalized.pTableParams.filters;
-  const defaultFilters = options?.filters ?? undefined;
-  const filterColumns = filters !== null ? collectFilterSpecColumns(filters) : [];
-  const firstInvalidFilterColumn = filterColumns.find((col) => !isValidColumnId(col));
-  if (firstInvalidFilterColumn)
-    throw new Error(
-      `Invalid filter column ${firstInvalidFilterColumn}: column reference does not match the table columns`,
-    );
-  const defaultFilterColumns =
-    defaultFilters !== undefined ? collectFilterSpecColumns(defaultFilters) : [];
-  const firstInvalidDefaultFilterColumn = defaultFilterColumns.find((col) => !isValidColumnId(col));
-  if (firstInvalidDefaultFilterColumn)
-    throw new Error(
-      `Invalid default filter column ${firstInvalidDefaultFilterColumn}: column reference does not match the table columns`,
-    );
 
-  // -- Sorting validation --
-  const userSorting = tableStateNormalized.pTableParams.sorting;
-  const sorting = (isEmpty(userSorting) ? options?.sorting : userSorting) ?? [];
-  const firstInvalidSortingColumn = sorting.find(
-    (s) => !isValidColumnId(canonicalizeJson<PTableColumnId>(s.column)),
+  // -- Filtering: rewrite via resolver, throw if any reference is unresolved --
+  const rawFilters = tableStateNormalized.pTableParams.filters;
+  const rawDefaultFilters = options?.filters ?? undefined;
+  const filters = remapFiltersThrowing(rawFilters, resolver, "filter");
+  const defaultFilters = remapFiltersThrowing(
+    rawDefaultFilters ?? null,
+    resolver,
+    "default filter",
   );
-  if (firstInvalidSortingColumn)
-    throw new Error(
-      `Invalid sorting column ${JSON.stringify(firstInvalidSortingColumn.column)}: column reference does not match the table columns`,
-    );
+
+  // -- Sorting: rewrite via resolver, throw if any reference is unresolved --
+  const userSorting = tableStateNormalized.pTableParams.sorting;
+  const rawSorting = (isNil(userSorting) ? options?.sorting : userSorting) ?? [];
+  const sorting = remapSortingThrowing(rawSorting, resolver);
 
   const coreJoinType = options?.coreJoinType ?? "full";
   const fullDef = createPTableDefV2({
     columns,
     labelColumns: fullLabelColumns,
     coreJoinType,
-    filters,
+    filters: filters ?? null,
     sorting,
     coreColumnPredicate: options?.coreColumnPredicate,
   });
@@ -135,8 +116,8 @@ export function createPlDataTableV2<A, U>(
   const pframeHandle = ctx.createPFrame(fullColumns);
   if (!fullHandle || !pframeHandle) return undefined;
 
-  const hiddenColumns = new Set<PObjectId>(
-    ((): PObjectId[] => {
+  const hiddenColumns = new Set<ColumnUniversalId>(
+    ((): ColumnUniversalId[] => {
       // Inner join works as a filter - all columns must be present
       if (coreJoinType === "inner") return [];
 
@@ -172,10 +153,7 @@ export function createPlDataTableV2<A, U>(
   // Preserve filter columns from being hidden
   if (filters) {
     collectFilterSpecColumns(filters)
-      .flatMap((c) => {
-        const obj = parseJson(c);
-        return obj.type === "column" ? [obj.id] : [];
-      })
+      .flatMap((c) => (c.type === "column" ? [c.id] : []))
       .forEach((c) => hiddenColumns.delete(c));
   }
 
@@ -192,7 +170,7 @@ export function createPlDataTableV2<A, U>(
     columns: visibleColumns,
     labelColumns: visibleLabelColumns,
     coreJoinType,
-    filters,
+    filters: filters ?? null,
     sorting,
     coreColumnPredicate,
   });
@@ -205,13 +183,62 @@ export function createPlDataTableV2<A, U>(
     fullTableHandle: fullHandle,
     fullPframeHandle: pframeHandle,
     visibleTableHandle: visibleHandle,
-    defaultFilters,
+    defaultFilters: defaultFilters ?? undefined,
   } satisfies PlDataTableModel;
 }
 
+/** Rewrite filter column refs through the resolver; throw on any unresolved ref. */
+function remapFiltersThrowing(
+  filters: Nil | PlDataTableFilters,
+  resolver: ColumnResolver,
+  label: string,
+): Nil | PlDataTableFilters {
+  if (isNil(filters)) return filters;
+
+  type Node = FilterSpecNode<PlDataTableFilterSpecLeaf>;
+  return traverseFilterSpec(filters, {
+    leaf: (leaf): Node => {
+      if (leaf.type === undefined) return leaf;
+      const result = { ...leaf };
+      if ("column" in result) {
+        const c = resolver(result.column);
+        if (isNil(c))
+          throw new Error(
+            `Invalid ${label} column ${JSON.stringify(result.column)}: column reference does not match the table columns`,
+          );
+        result.column = c;
+      }
+      if ("rhs" in result) {
+        const c = resolver(result.rhs);
+        if (isNil(c))
+          throw new Error(
+            `Invalid ${label} column ${JSON.stringify(result.rhs)}: column reference does not match the table columns`,
+          );
+        result.rhs = c;
+      }
+      return result;
+    },
+    and: (results): Node => ({ type: "and", filters: results }),
+    or: (results): Node => ({ type: "or", filters: results }),
+    not: (result): Node => ({ type: "not", filter: result }),
+  }) as PlDataTableFilters;
+}
+
+/** Rewrite sorting column refs through the resolver; throw on any unresolved ref. */
+function remapSortingThrowing(sorting: PTableSorting[], resolver: ColumnResolver): PTableSorting[] {
+  return sorting.map((s) => {
+    const c = resolver(s.column);
+    if (isNil(c))
+      throw new Error(
+        `Invalid sorting column ${JSON.stringify(s.column)}: column reference does not match the table columns`,
+      );
+    return { ...s, column: c };
+  });
+}
+
 function getAllLabelColumns(
   resultPool: AxisLabelProvider & ColumnProvider,
-): PColumn<PColumnDataUniversal>[] | undefined {
+): undefined | PColumn<undefined | PColumnDataUniversal>[] {
   return new PColumnCollection()
     .addAxisLabelProvider(resultPool)
     .addColumnProvider(resultPool)