@platforma-sdk/model 1.63.12 → 1.65.0

package/src/columns/column_snapshot_provider.ts

@@ -1,3 +1,4 @@
+import type { PObjectId } from "@milaboratories/pl-model-common";
 import { PColumn } from "@milaboratories/pl-model-common";
 import { TreeNodeAccessor } from "../render/accessor";
 import type { PColumnDataUniversal } from "../render/internal";
@@ -13,7 +14,7 @@ import type { ColumnDataStatus, ColumnSnapshot } from "./column_snapshot";
  */
 export interface ColumnSnapshotProvider {
   /** Returns all currently known columns. */
-  getAllColumns(): ColumnSnapshot[];
+  getAllColumns(): ColumnSnapshot<PObjectId>[];
 
   /** Whether the provider has finished enumerating all its columns.
    *  Calling this may mark the render context unstable — it touches
@@ -29,7 +30,7 @@ export interface ColumnSnapshotProvider {
  */
 export type ColumnSource =
   | ColumnSnapshotProvider
-  | ColumnSnapshot[]
+  | ColumnSnapshot<PObjectId>[]
   | PColumn<PColumnDataUniversal | undefined>[];
 
 // --- ArrayColumnProvider ---
@@ -39,7 +40,7 @@ export type ColumnSource =
  * Always complete, data status always 'ready'.
  */
 export class ArrayColumnProvider implements ColumnSnapshotProvider {
-  private readonly columns: ColumnSnapshot[];
+  private readonly columns: ColumnSnapshot<PObjectId>[];
 
   constructor(columns: PColumn<PColumnDataUniversal | undefined>[]) {
     this.columns = columns.map((col) => ({
@@ -50,7 +51,7 @@ export class ArrayColumnProvider implements ColumnSnapshotProvider {
     }));
   }
 
-  getAllColumns(): ColumnSnapshot[] {
+  getAllColumns(): ColumnSnapshot<PObjectId>[] {
     return this.columns;
   }
 
@@ -66,9 +67,9 @@ export class ArrayColumnProvider implements ColumnSnapshotProvider {
  * Always complete. Data status taken from each snapshot.
  */
 export class SnapshotColumnProvider implements ColumnSnapshotProvider {
-  constructor(private readonly snapshots: ColumnSnapshot[]) {}
+  constructor(private readonly snapshots: ColumnSnapshot<PObjectId>[]) {}
 
-  getAllColumns(): ColumnSnapshot[] {
+  getAllColumns(): ColumnSnapshot<PObjectId>[] {
     return this.snapshots;
   }
 
@@ -94,7 +95,7 @@ export class OutputColumnProvider implements ColumnSnapshotProvider {
     private readonly opts?: OutputColumnProviderOpts,
   ) {}
 
-  getAllColumns(): ColumnSnapshot[] {
+  getAllColumns(): ColumnSnapshot<PObjectId>[] {
     return this.getColumns();
   }
 
@@ -102,7 +103,7 @@ export class OutputColumnProvider implements ColumnSnapshotProvider {
     return this.accessor.getInputsLocked();
   }
 
-  private getColumns(): ColumnSnapshot[] {
+  private getColumns(): ColumnSnapshot<PObjectId>[] {
     const pColumns = this.accessor.getPColumns();
     if (pColumns === undefined) return [];
 
@@ -155,7 +156,7 @@ function isPColumnArray(source: unknown): source is PColumn<PColumnDataUniversal
 }
 
 /** Checks if a value looks like a ColumnSnapshot array. */
-function isColumnSnapshotArray(source: unknown): source is ColumnSnapshot[] {
+function isColumnSnapshotArray(source: unknown): source is ColumnSnapshot<PObjectId>[] {
   if (!Array.isArray(source)) return false;
   if (source.length === 0) return true; // empty array — treat as snapshots
   const first = source[0];
@@ -165,7 +166,7 @@ function isColumnSnapshotArray(source: unknown): source is ColumnSnapshot[] {
 /**
  * Normalize any ColumnSource into a ColumnSnapshotProvider.
  * - ColumnSnapshotProvider → returned as-is
- * - ColumnSnapshot[] → wrapped in SnapshotColumnProvider
+ * - ColumnSnapshot<PObjectId>[] → wrapped in SnapshotColumnProvider
  * - PColumn[] → wrapped in ArrayColumnProvider
  */
 export function toColumnSnapshotProvider(source: ColumnSource): ColumnSnapshotProvider {

package/src/columns/ctx_column_sources.ts

@@ -51,7 +51,7 @@ export function collectCtxColumnSnapshotProviders<A, U, S>(
 export class ResultPoolColumnSnapshotProvider implements ColumnSnapshotProvider {
   constructor(private readonly pool: ResultPool) {}
 
-  getAllColumns(): ColumnSnapshot[] {
+  getAllColumns(): ColumnSnapshot<PObjectId>[] {
     const pColumns = this.pool.selectColumns(() => true);
     return pColumns.map((col) => toSnapshot(col.id, col.spec, col.data));
   }
@@ -65,7 +65,7 @@ function toSnapshot(
   id: PObjectId,
   spec: PColumnSpec,
   accessor: TreeNodeAccessor | undefined,
-): ColumnSnapshot {
+): ColumnSnapshot<PObjectId> {
   if (accessor === undefined) {
     return { id, spec, dataStatus: "absent" as ColumnDataStatus, data: undefined };
   }

package/src/columns/expand_by_partition.test.ts

@@ -32,7 +32,7 @@ function createReadySnapshot(
   columnSpec: PColumnSpec,
   partitionKeyLength: number,
   parts: { key: (string | number)[]; value: unknown }[],
-): ColumnSnapshot {
+): ColumnSnapshot<PObjectId> {
   const dataEntries: JsonPartitionedDataInfoEntries<unknown> = {
     type: "JsonPartitioned",
     partitionKeyLength,
@@ -48,7 +48,7 @@ function createReadySnapshot(
   };
 }
 
-function createComputingSnapshot(id: string, columnSpec: PColumnSpec): ColumnSnapshot {
+function createComputingSnapshot(id: string, columnSpec: PColumnSpec): ColumnSnapshot<PObjectId> {
   return {
     id: id as PObjectId,
     spec: columnSpec,
@@ -59,7 +59,7 @@ function createComputingSnapshot(id: string, columnSpec: PColumnSpec): ColumnSna
   };
 }
 
-function createAbsentSnapshot(id: string, columnSpec: PColumnSpec): ColumnSnapshot {
+function createAbsentSnapshot(id: string, columnSpec: PColumnSpec): ColumnSnapshot<PObjectId> {
   return {
     id: id as PObjectId,
     spec: columnSpec,
@@ -74,7 +74,7 @@ interface Trace {
   importance: number;
 }
 
-function extractTrace(snapshot: ColumnSnapshot): Trace[] {
+function extractTrace(snapshot: ColumnSnapshot<PObjectId>): Trace[] {
   const raw = snapshot.spec.annotations?.["pl7.app/trace"];
   return raw ? (JSON.parse(raw) as Trace[]) : [];
 }

package/src/columns/expand_by_partition.ts

@@ -3,6 +3,7 @@ import type {
   AxisFilterValue,
   AxisId,
   PartitionedDataInfoEntries,
+  PObjectId,
 } from "@milaboratories/pl-model-common";
 import {
   canonicalizeAxisId,
@@ -30,7 +31,7 @@ export interface ExpandByPartitionOpts {
 
 export interface ExpandByPartitionResult {
   /** Expanded snapshots (one per key combination per original snapshot). */
-  readonly items: ColumnSnapshot[];
+  readonly items: ColumnSnapshot<PObjectId>[];
   /** False if any column's data was not ready for splitting. */
   readonly complete: boolean;
 }
@@ -49,7 +50,7 @@ export interface ExpandByPartitionResult {
  * is not ready (status !== 'ready' or partition data unavailable).
  */
 export function expandByPartition(
-  snapshots: ColumnSnapshot[],
+  snapshots: ColumnSnapshot<PObjectId>[],
   splitAxes: SplitAxis[],
   opts?: ExpandByPartitionOpts,
 ): ExpandByPartitionResult {
@@ -58,7 +59,7 @@ export function expandByPartition(
   }
 
   const splitAxisIdxs = splitAxes.map((a) => a.idx).sort((a, b) => a - b);
-  const result: ColumnSnapshot[] = [];
+  const result: ColumnSnapshot<PObjectId>[] = [];
 
   for (const snapshot of snapshots) {
     if (snapshot.dataStatus !== "ready" || snapshot.data === undefined) {

package/src/columns/index.ts

@@ -3,3 +3,4 @@ export * from "./column_snapshot_provider";
 export * from "./column_selector";
 export * from "./column_collection_builder";
 export * from "./ctx_column_sources";
+export * from "./expand_by_partition";

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

@@ -0,0 +1,42 @@
+import type {
+  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 { isFunction } from "es-toolkit";
+import type { PlDataTableFilters } from "../typesV5";
+import { createPTableDefV3 } from "./createPTableDefV3";
+
+export function createPTableDefV2(params: {
+  columns: PColumn<PColumnDataUniversal>[];
+  labelColumns: PColumn<PColumnDataUniversal>[];
+  coreJoinType: "inner" | "full";
+  filters: null | PlDataTableFilters;
+  sorting: PTableSorting[];
+  coreColumnPredicate?: (spec: PColumnIdAndSpec) => boolean;
+}): PTableDefV2<PColumn<TreeNodeAccessor | PColumnValues | DataInfo<TreeNodeAccessor>>> {
+  let coreColumns = params.columns;
+  const secondaryColumns: typeof params.columns = [];
+
+  if (isFunction(params.coreColumnPredicate)) {
+    coreColumns = [];
+    for (const c of params.columns)
+      if (params.coreColumnPredicate(getColumnIdAndSpec(c))) coreColumns.push(c);
+      else secondaryColumns.push(c);
+  }
+
+  secondaryColumns.push(...params.labelColumns);
+
+  return createPTableDefV3({
+    primaryColumns: coreColumns,
+    secondaryGroups: secondaryColumns.map((c) => [c]),
+    primaryJoinType: params.coreJoinType,
+    filters: params.filters,
+    sorting: params.sorting,
+  });
+}

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

@@ -0,0 +1,89 @@
+import type {
+  PColumn,
+  PTableColumnId,
+  PTableSorting,
+  PTableDefV2,
+  SingleAxisSelector,
+  SpecQuery,
+  SpecQueryExpression,
+  SpecQueryJoinEntry,
+} 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 "../typesV5";
+import { distillFilterSpec, filterSpecToSpecQueryExpr } from "../../../filters";
+import type { Nil } from "@milaboratories/helpers";
+
+export function createPTableDefV3<Data = PColumnDataUniversal>(params: {
+  primaryJoinType: "inner" | "full";
+  primaryColumns: PColumn<Data>[];
+  secondaryGroups: PColumn<Data>[][];
+  filters?: Nil | PlDataTableFilters;
+  sorting?: Nil | PTableSorting[];
+}): PTableDefV2<PColumn<Data>> {
+  // Build SpecQuery directly from columns
+  const coreJoinQuery: SpecQuery<PColumn<Data>> = {
+    type: params.primaryJoinType === "inner" ? "innerJoin" : "fullJoin",
+    entries: params.primaryColumns.map((c) => toJoinEntry({ type: "column", column: c })),
+  };
+
+  let query: SpecQuery<PColumn<Data>> = {
+    type: "outerJoin",
+    primary: toJoinEntry(coreJoinQuery),
+    secondary: params.secondaryGroups.map((group) =>
+      toJoinEntry({
+        type: "innerJoin" as const,
+        entries: group.map((c) => toJoinEntry({ type: "column" as const, column: c })),
+      }),
+    ),
+  };
+
+  // Apply filters
+  if (!isNil(params.filters)) {
+    const nonEmpty = distillFilterSpec(params.filters);
+
+    if (!isNil(nonEmpty)) {
+      const pridicate = filterSpecToSpecQueryExpr(nonEmpty);
+      if (!isBooleanExpression(pridicate)) {
+        throw new Error(
+          `Filter conversion produced a non-boolean expression (got type "${pridicate.type}"), expected a boolean predicate for query filtering`,
+        );
+      }
+      query = {
+        type: "filter",
+        input: query,
+        predicate: pridicate,
+      };
+    }
+  }
+
+  // Apply sorting
+  if (!isNil(params.sorting) && params.sorting.length > 0) {
+    query = {
+      type: "sort",
+      input: query,
+      sortBy: params.sorting.map((s) => ({
+        expression: columnIdToExpr(s.column),
+        ascending: s.ascending,
+        nullsFirst: !s.naAndAbsentAreLeastValues,
+      })),
+    };
+  }
+
+  return { query };
+}
+
+/** Convert a PTableColumnId to a SpecQueryExpression reference. */
+function columnIdToExpr(col: PTableColumnId): SpecQueryExpression {
+  return col.type === "axis"
+    ? { type: "axisRef", value: col.id as SingleAxisSelector }
+    : { type: "columnRef", value: col.id };
+}
+
+function toJoinEntry<C>(input: SpecQuery<C>): SpecQueryJoinEntry<C> {
+  return {
+    entry: input,
+    qualifications: [],
+  };
+}

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

@@ -15,18 +15,28 @@ import {
   isLinkerColumn,
   uniqueBy,
   parseJson,
+  PColumnName,
 } from "@milaboratories/pl-model-common";
-import type { PColumnDataUniversal, RenderCtxBase } from "../../../render";
-import { allPColumnsReady, deriveLabels } from "../../../render";
+import type {
+  AxisLabelProvider,
+  ColumnProvider,
+  PColumnDataUniversal,
+  RenderCtxBase,
+} from "../../../render";
+import { allPColumnsReady, deriveLabels, PColumnCollection } from "../../../render";
 import { identity } from "es-toolkit";
-import type { CreatePlDataTableOps, PlDataTableFilters, PlDataTableModel } from "../typesV5";
+import type { CreatePlDataTableOps, PlDataTableModel } from "../typesV5";
 import { upgradePlDataTableStateV2 } from "../state-migration";
 import type { PlDataTableStateV2 } from "../state-migration";
-import { getAllLabelColumns, getMatchingLabelColumns } from "../labels";
+import { getMatchingLabelColumns } from "../labels";
 import { collectFilterSpecColumns } from "../../../filters/traverse";
 import { isEmpty } from "es-toolkit/compat";
-import { createPTableDef, isColumnOptional } from "./createPlDataTableV3";
+import { createPTableDefV2 } from "./createPTableDefV2";
+import { isColumnOptional } from "./utils";
 
+/**
+ * @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.
+ */
 export type createPlDataTableOptionsV2 = {
   columns: PColumn<PColumnDataUniversal>[];
   tableState?: PlDataTableStateV2;
@@ -36,6 +46,7 @@ export type createPlDataTableOptionsV2 = {
 /**
  * Create p-table spec and handle given ui table state
  *
+ * @deprecated This version of createPlDataTable is deprecated and will be removed in future. Please migrate to v3 by switching to the new options format and providing necessary information for column discovery and display configuration. See createPlDataTableOptionsV3 for details.
  * @param ctx context
  * @param columns column list
  * @param tableState table ui state
@@ -50,11 +61,9 @@ export function createPlDataTableV2<A, U>(
   if (columns.length === 0) return undefined;
 
   const tableStateNormalized = upgradePlDataTableStateV2(tableState);
+  const allLabelColumns = getAllLabelColumns(ctx.resultPool) ?? [];
 
-  const allLabelColumns = getAllLabelColumns(ctx.resultPool);
-  if (!allLabelColumns) return undefined;
-
-  let fullLabelColumns = getMatchingLabelColumns(columns.map(getColumnIdAndSpec), allLabelColumns);
+  let fullLabelColumns = getMatchingLabelColumns(columns, allLabelColumns);
   fullLabelColumns = deriveLabels(fullLabelColumns, identity, { includeNativeLabel: true }).map(
     (v) => {
       return {
@@ -85,18 +94,21 @@ export function createPlDataTableV2<A, U>(
     fullColumnsIdsSet.has(id as CanonicalizedJson<PTableColumnId>);
 
   // -- Filtering validation --
-  const stateFilters = tableStateNormalized.pTableParams.filters;
-  const opsFilters = options?.filters ?? null;
-  const filters: null | PlDataTableFilters =
-    stateFilters != null && opsFilters != null
-      ? { type: "and", filters: [stateFilters, opsFilters] }
-      : (stateFilters ?? opsFilters);
-  const filterColumns = filters ? collectFilterSpecColumns(filters) : [];
+  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;
@@ -110,7 +122,7 @@ export function createPlDataTableV2<A, U>(
     );
 
   const coreJoinType = options?.coreJoinType ?? "full";
-  const fullDef = createPTableDef({
+  const fullDef = createPTableDefV2({
     columns,
     labelColumns: fullLabelColumns,
     coreJoinType,
@@ -129,7 +141,11 @@ export function createPlDataTableV2<A, U>(
       if (coreJoinType === "inner") return [];
 
       const hiddenColIds = tableStateNormalized.pTableParams.hiddenColIds;
-      if (hiddenColIds) return hiddenColIds;
+      if (hiddenColIds !== null) {
+        return hiddenColIds
+          .filter((s): s is PTableColumnIdColumn => s.type === "column")
+          .map((s) => s.id);
+      }
 
       return columns.filter((c) => isColumnOptional(c.spec)).map((c) => c.id);
     })(),
@@ -172,7 +188,7 @@ export function createPlDataTableV2<A, U>(
   // if at least one column is not yet computed, we can't show the table
   if (!allPColumnsReady([...visibleColumns, ...visibleLabelColumns])) return undefined;
 
-  const visibleDef = createPTableDef({
+  const visibleDef = createPTableDefV2({
     columns: visibleColumns,
     labelColumns: visibleLabelColumns,
     coreJoinType,
@@ -189,5 +205,21 @@ export function createPlDataTableV2<A, U>(
     fullTableHandle: fullHandle,
     fullPframeHandle: pframeHandle,
     visibleTableHandle: visibleHandle,
+    defaultFilters,
   } satisfies PlDataTableModel;
 }
+
+function getAllLabelColumns(
+  resultPool: AxisLabelProvider & ColumnProvider,
+): PColumn<PColumnDataUniversal>[] | undefined {
+  return new PColumnCollection()
+    .addAxisLabelProvider(resultPool)
+    .addColumnProvider(resultPool)
+    .getColumns(
+      {
+        name: PColumnName.Label,
+        axes: [{}], // exactly one axis
+      },
+      { dontWaitAllData: true, overrideLabelAnnotation: false },
+    );
+}