@platforma-sdk/model 1.59.0 → 1.60.0

package/src/columns/expand_by_partition.ts

@@ -0,0 +1,187 @@
+import type {
+  AxisFilterByIdx,
+  AxisFilterValue,
+  AxisId,
+  PartitionedDataInfoEntries,
+} from "@milaboratories/pl-model-common";
+import {
+  canonicalizeAxisId,
+  entriesToDataInfo,
+  getAxisId,
+  isPartitionedDataInfoEntries,
+} from "@milaboratories/pl-model-common";
+import type { TreeNodeAccessor } from "../render/accessor";
+import { filterDataInfoEntries } from "../render/util/axis_filtering";
+import { convertOrParsePColumnData, getUniquePartitionKeys } from "../render/util/pcolumn_data";
+import type { ColumnSnapshot } from "./column_snapshot";
+import { createReadyColumnData } from "./column_snapshot";
+
+// --- Types ---
+
+export interface SplitAxis {
+  /** Index of the axis in the column's axesSpec to split by. */
+  readonly idx: number;
+}
+
+export interface ExpandByPartitionOpts {
+  /** Resolve axis values to human-readable labels. */
+  axisLabels?: (axisId: AxisId) => undefined | Record<string | number, string>;
+}
+
+export interface ExpandByPartitionResult {
+  /** Expanded snapshots (one per key combination per original snapshot). */
+  readonly items: ColumnSnapshot[];
+  /** False if any column's data was not ready for splitting. */
+  readonly complete: boolean;
+}
+
+// --- Implementation ---
+
+/**
+ * Expand snapshots by splitting along partition axes.
+ *
+ * For each snapshot, reads partition data, enumerates unique keys on the
+ * split axes, and produces one output snapshot per key combination —
+ * with the split axes removed from `axesSpec` and a `pl7.app/trace`
+ * annotation recording the split origin.
+ *
+ * Returns `{ items: [], complete: false }` when any snapshot's data
+ * is not ready (status !== 'ready' or partition data unavailable).
+ */
+export function expandByPartition(
+  snapshots: ColumnSnapshot[],
+  splitAxes: SplitAxis[],
+  opts?: ExpandByPartitionOpts,
+): ExpandByPartitionResult {
+  if (splitAxes.length === 0) {
+    return { items: snapshots, complete: true };
+  }
+
+  const splitAxisIdxs = splitAxes.map((a) => a.idx).sort((a, b) => a - b);
+  const result: ColumnSnapshot[] = [];
+
+  for (const snapshot of snapshots) {
+    if (snapshot.dataStatus !== "ready" || snapshot.data === undefined) {
+      return { items: [], complete: false };
+    }
+
+    const rawData = snapshot.data.get();
+    const dataEntries = convertOrParsePColumnData(rawData as TreeNodeAccessor | undefined);
+
+    if (dataEntries === undefined) {
+      return { items: [], complete: false };
+    }
+
+    if (!isPartitionedDataInfoEntries(dataEntries)) {
+      throw new Error(
+        `Splitting requires Partitioned DataInfoEntries, but got ${dataEntries.type} for column ${String(snapshot.id)}`,
+      );
+    }
+
+    const uniqueKeys = getUniquePartitionKeys(dataEntries);
+
+    const maxSplitIdx = splitAxisIdxs[splitAxisIdxs.length - 1];
+    if (maxSplitIdx >= dataEntries.partitionKeyLength) {
+      throw new Error(
+        `Not enough partition keys (${dataEntries.partitionKeyLength}) for requested split axes (max index ${maxSplitIdx}) in column ${snapshot.spec.name}`,
+      );
+    }
+
+    // Resolve labels for each split axis
+    const axesLabels: (undefined | Record<string | number, string>)[] = splitAxisIdxs.map((idx) =>
+      opts?.axisLabels?.(getAxisId(snapshot.spec.axesSpec[idx])),
+    );
+
+    // Generate all key combinations across split axes
+    const keyCombinations = generateKeyCombinations(uniqueKeys, splitAxisIdxs);
+    if (keyCombinations.length === 0) continue;
+
+    // Build adjusted axesSpec (remove split axes in reverse order)
+    const newAxesSpec = [...snapshot.spec.axesSpec];
+    for (let i = splitAxisIdxs.length - 1; i >= 0; i--) {
+      newAxesSpec.splice(splitAxisIdxs[i], 1);
+    }
+
+    for (const keyCombo of keyCombinations) {
+      const axisFilters: AxisFilterByIdx[] = keyCombo.map(
+        (value, sAxisIdx): AxisFilterByIdx => [splitAxisIdxs[sAxisIdx], value as AxisFilterValue],
+      );
+
+      const traceEntries = keyCombo.map((value, sAxisIdx) => {
+        const axisIdx = splitAxisIdxs[sAxisIdx];
+        const axisId = getAxisId(snapshot.spec.axesSpec[axisIdx]);
+        const labelMap = axesLabels[sAxisIdx];
+        const label = labelMap?.[value] ?? String(value);
+        return {
+          type: `split:${canonicalizeAxisId(axisId)}`,
+          label,
+          importance: 1_000_000,
+        };
+      });
+
+      const filteredData = filterDataInfoEntries(
+        dataEntries as PartitionedDataInfoEntries<TreeNodeAccessor>,
+        axisFilters,
+      );
+
+      const adjustedSpec = {
+        ...snapshot.spec,
+        axesSpec: newAxesSpec,
+        annotations: {
+          ...snapshot.spec.annotations,
+          "pl7.app/trace": JSON.stringify(traceEntries),
+        },
+      };
+
+      result.push({
+        id: snapshot.id,
+        spec: adjustedSpec,
+        dataStatus: "ready",
+        data: createReadyColumnData(() => entriesToDataInfo(filteredData)),
+      });
+    }
+  }
+
+  return { items: result, complete: true };
+}
+
+const MAX_KEY_COMBINATIONS = 10_000;
+
+function generateKeyCombinations(
+  uniqueKeys: (string | number)[][],
+  splitAxisIdxs: number[],
+): (string | number)[][] {
+  const combinations: (string | number)[][] = [];
+
+  function generate(currentCombo: (string | number)[], sAxisIdx: number): void {
+    if (sAxisIdx >= splitAxisIdxs.length) {
+      combinations.push([...currentCombo]);
+      if (combinations.length > MAX_KEY_COMBINATIONS) {
+        throw new Error("Too many key combinations, aborting.");
+      }
+      return;
+    }
+
+    const axisIdx = splitAxisIdxs[sAxisIdx];
+    if (axisIdx >= uniqueKeys.length) {
+      throw new Error(
+        `Axis index ${axisIdx} out of bounds for unique keys array (length ${uniqueKeys.length})`,
+      );
+    }
+
+    const axisValues = uniqueKeys[axisIdx];
+    if (!axisValues || axisValues.length === 0) {
+      combinations.length = 0;
+      return;
+    }
+
+    for (const val of axisValues) {
+      currentCombo.push(val);
+      generate(currentCombo, sAxisIdx + 1);
+      currentCombo.pop();
+    }
+  }
+
+  generate([], 0);
+  return combinations;
+}

package/src/columns/index.ts

@@ -0,0 +1,5 @@
+export * from "./column_snapshot";
+export * from "./column_snapshot_provider";
+export * from "./column_selector";
+export * from "./column_collection_builder";
+export * from "./ctx_column_sources";

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

@@ -0,0 +1,193 @@
+import type {
+  AxisId,
+  PColumn,
+  PObjectId,
+  PTableColumnId,
+  PTableColumnIdAxis,
+  PTableColumnIdColumn,
+  CanonicalizedJson,
+} from "@milaboratories/pl-model-common";
+import {
+  Annotation,
+  canonicalizeJson,
+  getAxisId,
+  getColumnIdAndSpec,
+  isLinkerColumn,
+  uniqueBy,
+  parseJson,
+} from "@milaboratories/pl-model-common";
+import type { PColumnDataUniversal, RenderCtxBase } from "../../../render";
+import { allPColumnsReady, deriveLabels } from "../../../render";
+import { identity } from "es-toolkit";
+import type { CreatePlDataTableOps, PlDataTableFilters, PlDataTableModel } from "../typesV5";
+import { upgradePlDataTableStateV2 } from "../state-migration";
+import type { PlDataTableStateV2 } from "../state-migration";
+import { getAllLabelColumns, getMatchingLabelColumns } from "../labels";
+import { collectFilterSpecColumns } from "../../../filters/traverse";
+import { isEmpty } from "es-toolkit/compat";
+import { createPTableDef, isColumnOptional } from "./createPlDataTableV3";
+
+export type createPlDataTableOptionsV2 = {
+  columns: PColumn<PColumnDataUniversal>[];
+  tableState?: PlDataTableStateV2;
+  options?: CreatePlDataTableOps;
+};
+
+/**
+ * Create p-table spec and handle given ui table state
+ *
+ * @param ctx context
+ * @param columns column list
+ * @param tableState table ui state
+ * @returns PlAgDataTableV2 table source
+ */
+export function createPlDataTableV2<A, U>(
+  ctx: RenderCtxBase<A, U>,
+  columns: createPlDataTableOptionsV2["columns"],
+  tableState?: createPlDataTableOptionsV2["tableState"],
+  options?: createPlDataTableOptionsV2["options"],
+): PlDataTableModel | undefined {
+  if (columns.length === 0) return undefined;
+
+  const tableStateNormalized = upgradePlDataTableStateV2(tableState);
+
+  const allLabelColumns = getAllLabelColumns(ctx.resultPool);
+  if (!allLabelColumns) return undefined;
+
+  let fullLabelColumns = getMatchingLabelColumns(columns.map(getColumnIdAndSpec), allLabelColumns);
+  fullLabelColumns = deriveLabels(fullLabelColumns, identity, { includeNativeLabel: true }).map(
+    (v) => {
+      return {
+        ...v.value,
+        spec: {
+          ...v.value.spec,
+          annotations: {
+            ...v.value.spec.annotations,
+            [Annotation.Label]: v.label,
+          },
+        },
+      };
+    },
+  );
+
+  const fullColumns = [...columns, ...fullLabelColumns];
+
+  const fullColumnsAxes = uniqueBy(
+    fullColumns.flatMap((c) => c.spec.axesSpec.map((a) => getAxisId(a))),
+    (a) => canonicalizeJson<AxisId>(a),
+  );
+  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 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 firstInvalidFilterColumn = filterColumns.find((col) => !isValidColumnId(col));
+  if (firstInvalidFilterColumn)
+    throw new Error(
+      `Invalid filter column ${firstInvalidFilterColumn}: 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)),
+  );
+  if (firstInvalidSortingColumn)
+    throw new Error(
+      `Invalid sorting column ${JSON.stringify(firstInvalidSortingColumn.column)}: column reference does not match the table columns`,
+    );
+
+  const coreJoinType = options?.coreJoinType ?? "full";
+  const fullDef = createPTableDef({
+    columns,
+    labelColumns: fullLabelColumns,
+    coreJoinType,
+    filters,
+    sorting,
+    coreColumnPredicate: options?.coreColumnPredicate,
+  });
+
+  const fullHandle = ctx.createPTableV2(fullDef);
+  const pframeHandle = ctx.createPFrame(fullColumns);
+  if (!fullHandle || !pframeHandle) return undefined;
+
+  const hiddenColumns = new Set<PObjectId>(
+    ((): PObjectId[] => {
+      // Inner join works as a filter - all columns must be present
+      if (coreJoinType === "inner") return [];
+
+      const hiddenColIds = tableStateNormalized.pTableParams.hiddenColIds;
+      if (hiddenColIds) return hiddenColIds;
+
+      return columns.filter((c) => isColumnOptional(c.spec)).map((c) => c.id);
+    })(),
+  );
+
+  // Preserve linker columns
+  columns.filter((c) => isLinkerColumn(c.spec)).forEach((c) => hiddenColumns.delete(c.id));
+
+  // Preserve core columns as they change the shape of join.
+  const coreColumnPredicate = options?.coreColumnPredicate;
+  if (coreColumnPredicate) {
+    const coreColumns = columns.flatMap((c) =>
+      coreColumnPredicate(getColumnIdAndSpec(c)) ? [c.id] : [],
+    );
+    coreColumns.forEach((c) => hiddenColumns.delete(c));
+  }
+
+  // Preserve sorted columns from being hidden
+  sorting
+    .map((s) => s.column)
+    .filter((c): c is PTableColumnIdColumn => c.type === "column")
+    .forEach((c) => hiddenColumns.delete(c.id));
+
+  // Preserve filter columns from being hidden
+  if (filters) {
+    collectFilterSpecColumns(filters)
+      .flatMap((c) => {
+        const obj = parseJson(c);
+        return obj.type === "column" ? [obj.id] : [];
+      })
+      .forEach((c) => hiddenColumns.delete(c));
+  }
+
+  const visibleColumns = columns.filter((c) => !hiddenColumns.has(c.id));
+  const visibleLabelColumns = getMatchingLabelColumns(
+    visibleColumns.map(getColumnIdAndSpec),
+    allLabelColumns,
+  );
+
+  // if at least one column is not yet computed, we can't show the table
+  if (!allPColumnsReady([...visibleColumns, ...visibleLabelColumns])) return undefined;
+
+  const visibleDef = createPTableDef({
+    columns: visibleColumns,
+    labelColumns: visibleLabelColumns,
+    coreJoinType,
+    filters,
+    sorting,
+    coreColumnPredicate,
+  });
+  const visibleHandle = ctx.createPTableV2(visibleDef);
+
+  if (!visibleHandle) return undefined;
+
+  return {
+    sourceId: tableStateNormalized.pTableParams.sourceId,
+    fullTableHandle: fullHandle,
+    fullPframeHandle: pframeHandle,
+    visibleTableHandle: visibleHandle,
+  } satisfies PlDataTableModel;
+}