@platforma-sdk/model 1.53.15 → 1.54.8

package/src/filters/distill.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, it } from "vitest";
+import type { FilterSpec, FilterSpecLeaf } from "@milaboratories/pl-model-common";
+import { distillFilterSpec } from "./distill";
+
+type F = FilterSpec<FilterSpecLeaf<string>>;
+
+const leaf: F = { type: "equal", column: "c1", x: 1 };
+const emptyLeaf: F = { type: undefined };
+const incompleteLeaf: F = { type: "equal", column: "c1", x: undefined as unknown as number };
+
+describe("distillFilterSpec", () => {
+  it("returns null for null input", () => {
+    expect(distillFilterSpec(null)).toBeNull();
+  });
+
+  it("returns null for undefined input", () => {
+    expect(distillFilterSpec(undefined)).toBeNull();
+  });
+
+  it("returns valid leaf as-is", () => {
+    expect(distillFilterSpec(leaf)).toEqual(leaf);
+  });
+
+  it("returns null for empty leaf", () => {
+    expect(distillFilterSpec(emptyLeaf)).toBeNull();
+  });
+
+  it("returns null for incomplete leaf", () => {
+    expect(distillFilterSpec(incompleteLeaf)).toBeNull();
+  });
+
+  // --- distill (strips extra metadata) ---
+
+  it("strips non-FilterSpec metadata from leaf", () => {
+    const leafWithMeta = { type: "equal" as const, column: "c1", x: 1, _extra: true, label: "hi" };
+    expect(distillFilterSpec(leafWithMeta)).toEqual({ type: "equal", column: "c1", x: 1 });
+  });
+
+  it("strips non-FilterSpec metadata from nested nodes", () => {
+    const filter = {
+      type: "and" as const,
+      filters: [{ type: "equal" as const, column: "c1", x: 1, _meta: "remove" }],
+      _rootMeta: 42,
+    };
+    expect(distillFilterSpec(filter)).toEqual({
+      type: "and",
+      filters: [{ type: "equal", column: "c1", x: 1 }],
+    });
+  });
+
+  // --- and ---
+
+  it("filters out empty children from and", () => {
+    const filter: F = { type: "and", filters: [emptyLeaf, leaf, emptyLeaf] };
+    expect(distillFilterSpec(filter)).toEqual({ type: "and", filters: [leaf] });
+  });
+
+  it("returns null when all and children are empty", () => {
+    const filter: F = { type: "and", filters: [emptyLeaf, emptyLeaf] };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
+
+  it("returns null for and with no children", () => {
+    const filter: F = { type: "and", filters: [] };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
+
+  // --- or ---
+
+  it("filters out empty children from or", () => {
+    const leaf2: F = { type: "equal", column: "c2", x: 2 };
+    const filter: F = { type: "or", filters: [leaf, emptyLeaf, leaf2] };
+    expect(distillFilterSpec(filter)).toEqual({ type: "or", filters: [leaf, leaf2] });
+  });
+
+  it("returns null when all or children are empty", () => {
+    const filter: F = { type: "or", filters: [emptyLeaf] };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
+
+  // --- not ---
+
+  it("preserves not with valid inner filter", () => {
+    const filter: F = { type: "not", filter: leaf };
+    expect(distillFilterSpec(filter)).toEqual({ type: "not", filter: leaf });
+  });
+
+  it("returns null for not wrapping an empty filter", () => {
+    const filter: F = { type: "not", filter: emptyLeaf };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
+
+  // --- nested collapse ---
+
+  it("returns null when nested and collapses", () => {
+    const filter: F = {
+      type: "not",
+      filter: { type: "and", filters: [emptyLeaf] },
+    };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
+
+  it("returns null when parent and has only a collapsing child", () => {
+    const filter: F = {
+      type: "and",
+      filters: [{ type: "or", filters: [emptyLeaf] }],
+    };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
+
+  it("keeps valid siblings when one child collapses", () => {
+    const filter: F = {
+      type: "and",
+      filters: [{ type: "or", filters: [emptyLeaf] }, leaf],
+    };
+    expect(distillFilterSpec(filter)).toEqual({ type: "and", filters: [leaf] });
+  });
+
+  // --- unfilled fields (at least one undefined field drops the leaf) ---
+
+  it("returns null for leaf with undefined column", () => {
+    const filter: F = { type: "equal", column: undefined as unknown as string, x: 1 };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
+
+  it("returns null for leaf with undefined value (string filter)", () => {
+    const filter: F = {
+      type: "patternEquals",
+      column: "c1",
+      value: undefined as unknown as string,
+    };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
+
+  it("returns null for greaterThan with undefined x", () => {
+    const filter: F = {
+      type: "greaterThan",
+      column: "c1",
+      x: undefined as unknown as number,
+    };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
+
+  it("returns null for topN with undefined n", () => {
+    const filter: F = {
+      type: "topN",
+      column: "c1",
+      n: undefined as unknown as number,
+    };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
+
+  it("returns null for inSet with undefined value", () => {
+    const filter: F = {
+      type: "inSet",
+      column: "c1",
+      value: undefined as unknown as string[],
+    };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
+
+  it("drops incomplete leaf from and, keeps filled siblings", () => {
+    const incomplete: F = { type: "greaterThan", column: "c1", x: undefined as unknown as number };
+    const filter: F = { type: "and", filters: [leaf, incomplete] };
+    expect(distillFilterSpec(filter)).toEqual({ type: "and", filters: [leaf] });
+  });
+
+  it("drops incomplete leaf from or, keeps filled siblings", () => {
+    const incomplete: F = {
+      type: "patternEquals",
+      column: "c1",
+      value: undefined as unknown as string,
+    };
+    const leaf2: F = { type: "equal", column: "c2", x: 2 };
+    const filter: F = { type: "or", filters: [incomplete, leaf2] };
+    expect(distillFilterSpec(filter)).toEqual({ type: "or", filters: [leaf2] });
+  });
+
+  it("returns null for not wrapping an incomplete leaf", () => {
+    const incomplete: F = { type: "equal", column: undefined as unknown as string, x: 1 };
+    const filter: F = { type: "not", filter: incomplete };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
+
+  it("returns null when and contains only incomplete leaves", () => {
+    const a: F = { type: "equal", column: "c1", x: undefined as unknown as number };
+    const b: F = { type: "greaterThan", column: undefined as unknown as string, x: 5 };
+    const filter: F = { type: "and", filters: [a, b] };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
+});

package/src/filters/distill.ts

@@ -0,0 +1,67 @@
+import { DistributiveKeys, UnionToTuples } from "@milaboratories/helpers";
+import { type FilterSpec, type FilterSpecLeaf } from "@milaboratories/pl-model-common";
+
+/** All possible field names that can appear in any FilterSpecLeaf variant. */
+type FilterSpecLeafKey = DistributiveKeys<FilterSpecLeaf<string>>;
+
+/** Compile-time check: every key in the tuple is a valid leaf key (via satisfies). */
+const KNOWN_LEAF_KEYS_TUPLE: UnionToTuples<FilterSpecLeafKey> = [
+  "n",
+  "x",
+  "rhs",
+  "type",
+  "value",
+  "column",
+  "minDiff",
+  "maxEdits",
+  "wildcard",
+  "replacement",
+  "substitutionsOnly",
+];
+const KNOWN_LEAF_KEYS: Set<FilterSpecLeafKey> = new Set(KNOWN_LEAF_KEYS_TUPLE);
+
+/** Returns true if the leaf is filled — type is defined and no required fields are undefined. */
+function isFilledLeaf(node: Record<string, unknown>): boolean {
+  if (node.type == null) return false;
+  return !Object.values(node).some((v) => v === undefined);
+}
+
+function distillLeaf(node: Record<string, unknown>): FilterSpecLeaf<string> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(node)) {
+    if (KNOWN_LEAF_KEYS.has(key as FilterSpecLeafKey)) {
+      result[key] = value;
+    }
+  }
+  return result as FilterSpecLeaf<string>;
+}
+
+function distillNode<T extends FilterSpecLeaf<unknown>>(
+  node: FilterSpec<T, unknown, unknown>,
+): FilterSpec<T> | null {
+  switch (node.type) {
+    case "and":
+    case "or": {
+      const filtered = node.filters.map(distillNode).filter((f): f is FilterSpec<T> => f !== null);
+      return filtered.length === 0 ? null : { type: node.type, filters: filtered };
+    }
+    case "not": {
+      const inner = distillNode(node.filter);
+      return inner === null ? null : { type: "not", filter: inner };
+    }
+    default:
+      if (!isFilledLeaf(node)) return null;
+      return distillLeaf(node);
+  }
+}
+
+/**
+ * Strips non-FilterSpec metadata (whitelist approach) and removes
+ * unfilled leaves (type is undefined or any required field is undefined).
+ */
+export function distillFilterSpec<T extends FilterSpecLeaf<unknown>>(
+  filter: null | undefined | FilterSpec<T, unknown, unknown>,
+): null | FilterSpec<T> {
+  if (filter == null) return null;
+  return distillNode(filter);
+}

package/src/filters/index.ts

@@ -1,2 +1,3 @@
-export * from "./converter";
+export * from "./converters";
+export * from "./distill";
 export * from "./types";

package/src/filters/types.ts

@@ -8,51 +8,10 @@ export type SimplifiedUniversalPColumnEntry = {
   obj: SimplifiedPColumnSpec;
 };
 
-export type FilterSpecNode<Leaf, CommonNode = {}, CommonLeaf = {}> =
-  | (CommonLeaf & Leaf)
-  | (CommonNode & { type: "not"; filter: FilterSpecNode<Leaf, CommonNode, CommonLeaf> })
-  | (CommonNode & { type: "or"; filters: FilterSpecNode<Leaf, CommonNode, CommonLeaf>[] })
-  | (CommonNode & { type: "and"; filters: FilterSpecNode<Leaf, CommonNode, CommonLeaf>[] });
-
-export type FilterSpecLeaf<T = SUniversalPColumnId> =
-  | { type: undefined }
-  | { type: "isNA"; column: T }
-  | { type: "isNotNA"; column: T }
-  | { type: "patternEquals"; column: T; value: string }
-  | { type: "patternNotEquals"; column: T; value: string }
-  | { type: "patternContainSubsequence"; column: T; value: string }
-  | { type: "patternNotContainSubsequence"; column: T; value: string }
-  | { type: "patternMatchesRegularExpression"; column: T; value: string }
-  | {
-      type: "patternFuzzyContainSubsequence";
-      column: T;
-      value: string;
-      maxEdits?: number;
-      substitutionsOnly?: boolean;
-      wildcard?: string;
-    }
-  | { type: "inSet"; column: T; value: string[] }
-  | { type: "notInSet"; column: T; value: string[] }
-  | { type: "topN"; column: T; n: number }
-  | { type: "bottomN"; column: T; n: number }
-  | { type: "equal"; column: T; x: number }
-  | { type: "notEqual"; column: T; x: number }
-  | { type: "lessThan"; column: T; x: number }
-  | { type: "greaterThan"; column: T; x: number }
-  | { type: "lessThanOrEqual"; column: T; x: number }
-  | { type: "greaterThanOrEqual"; column: T; x: number }
-  | { type: "equalToColumn"; column: T; rhs: T }
-  | { type: "lessThanColumn"; column: T; rhs: T; minDiff?: number }
-  | { type: "greaterThanColumn"; column: T; rhs: T; minDiff?: number }
-  | { type: "lessThanColumnOrEqual"; column: T; rhs: T; minDiff?: number }
-  | { type: "greaterThanColumnOrEqual"; column: T; rhs: T; minDiff?: number };
-
-export type FilterSpec<
-  Leaf extends FilterSpecLeaf<unknown> = FilterSpecLeaf<SUniversalPColumnId>,
-  CommonNode = {},
-  CommonLeaf = CommonNode,
-> = FilterSpecNode<Leaf, CommonNode, CommonLeaf>;
-
-export type FilterSpecType = Exclude<FilterSpec, { type: undefined }>["type"];
-
-export type FilterSpecOfType<T extends FilterSpecType> = Extract<FilterSpec, { type: T }>;
+export type {
+  FilterSpecNode,
+  FilterSpecLeaf,
+  FilterSpec,
+  FilterSpecType,
+  FilterSpecOfType,
+} from "@milaboratories/pl-model-common";

package/src/pframe_utils/querySpec.ts

@@ -0,0 +1 @@
+export { collectQueryColumns, isBooleanExpression } from "@milaboratories/pl-model-common";

package/src/render/api.ts

@@ -16,6 +16,7 @@ import type {
   PObjectSpec,
   PSpecPredicate,
   PTableDef,
+  PTableDefV2,
   PTableHandle,
   PTableRecordFilter,
   PTableSorting,
@@ -36,6 +37,7 @@ import {
   mapDataInfo,
   mapPObjectData,
   mapPTableDef,
+  mapPTableDefV2,
   mapValueInVOE,
   PColumnName,
   readAnnotation,
@@ -58,12 +60,9 @@ import type { LabelDerivationOps } from "./util/label";
 import { deriveLabels } from "./util/label";
 import type { APColumnSelectorWithSplit } from "./util/split_selectors";
 import { patchInSetFilters } from "./util/pframe_upgraders";
-import { allPColumnsReady } from "./util";
-
-export type PColumnDataUniversal<TreeEntry = TreeNodeAccessor> =
-  | TreeEntry
-  | DataInfo<TreeEntry>
-  | PColumnValues;
+import { allPColumnsReady } from "./util/pcolumn_data";
+import type { PColumnDataUniversal } from "./internal";
+import { collectQueryColumns } from "@milaboratories/pl-model-common";
 
 /**
  * Helper function to match domain objects
@@ -682,6 +681,13 @@ export abstract class RenderCtxBase<Args, Data> {
     return this.ctx.createPTable(mapPTableDef(rawDef, (po) => transformPColumnData(po)));
   }
 
+  public createPTableV2(def: PTableDefV2<PColumn<PColumnDataUniversal>>): PTableHandle | undefined {
+    const columns = collectQueryColumns(def.query);
+    this.verifyInlineAndExplicitColumnsSupport(columns);
+    if (!allPColumnsReady(columns)) return undefined;
+    return this.ctx.createPTableV2(mapPTableDefV2(def, (po) => transformPColumnData(po)));
+  }
+
   /** @deprecated scheduled for removal from SDK */
   public getBlockLabel(blockId: string): string {
     return this.ctx.getBlockLabel(blockId);
@@ -721,6 +727,7 @@ export class RenderCtx<Args, Data> extends RenderCtxBase<Args, Data> {
 /** Render context for legacy v1/v2 blocks - provides backward compatibility */
 export class RenderCtxLegacy<Args, UiState> extends RenderCtxBase<Args, UiState> {
   private _argsCache?: { v: Args };
+
   public get args(): Args {
     if (this._argsCache === undefined) {
       const raw = this.ctx.args;

package/src/render/index.ts

@@ -2,5 +2,6 @@ export * from "./api";
 export * from "./traversal_ops";
 export * from "./accessor";
 export * from "./util";
-export { type ExtractFutureRefType } from "./future";
 export { FutureRef } from "./future";
+export type { PColumnDataUniversal } from "./internal";
+export type { ExtractFutureRefType } from "./future";

package/src/render/internal.ts

@@ -13,12 +13,14 @@ import type {
   PObjectSpec,
   PSpecPredicate,
   PTableDef,
+  PTableDefV2,
   PTableHandle,
   ResultCollection,
   ValueOrError,
   DataInfo,
   RangeBytes,
 } from "@milaboratories/pl-model-common";
+import type { TreeNodeAccessor } from "./accessor";
 
 export const StagingAccessorName = "staging";
 export const MainAccessorName = "main";
@@ -26,6 +28,11 @@ export const MainAccessorName = "main";
 export type AccessorHandle = Branded<string, "AccessorHandle">;
 export type FutureHandle = Branded<string, "FutureHandle">;
 
+export type PColumnDataUniversal<TreeEntry = TreeNodeAccessor> =
+  | TreeEntry
+  | DataInfo<TreeEntry>
+  | PColumnValues;
+
 export interface GlobalCfgRenderCtxMethods<AHandle = AccessorHandle, FHandle = FutureHandle> {
   //
   // Root accessor creation
@@ -146,6 +153,10 @@ export interface GlobalCfgRenderCtxMethods<AHandle = AccessorHandle, FHandle = F
 
   createPTable(def: PTableDef<PColumn<AHandle | PColumnValues | DataInfo<AHandle>>>): PTableHandle;
 
+  createPTableV2(
+    def: PTableDefV2<PColumn<AHandle | PColumnValues | DataInfo<AHandle>>>,
+  ): PTableHandle;
+
   //
   // Computable
   //

package/src/render/util/column_collection.ts

@@ -33,7 +33,7 @@ import {
 import canonicalize from "canonicalize";
 import type { Optional } from "utility-types";
 import type { TreeNodeAccessor } from "../accessor";
-import type { PColumnDataUniversal } from "../api";
+import type { PColumnDataUniversal } from "../internal";
 import { filterDataInfoEntries } from "./axis_filtering";
 import type { LabelDerivationOps, TraceEntry } from "./label";
 import { deriveLabels } from "./label";

package/src/render/util/pcolumn_data.ts

@@ -16,7 +16,7 @@ import {
   type PColumnKey,
 } from "@milaboratories/pl-model-common";
 import { TreeNodeAccessor } from "../accessor";
-import type { PColumnDataUniversal } from "../api";
+import type { PColumnDataUniversal } from "../internal";
 
 const PCD_PREFIX = "PColumnData/";