@milaboratories/pf-spec 1.0.0

package/src/p-frame.test.ts

@@ -0,0 +1,265 @@
+import type { PColumnSpec, PObjectId } from "@milaboratories/pl-model-common";
+import { expect, test } from "vitest";
+import { buildQuery, rewriteLegacyFilters } from "./index.ts";
+import { PFrame } from "./p-frame.ts";
+
+const column1Spec: PColumnSpec = {
+  kind: "PColumn",
+  name: "column1",
+  valueType: "Int",
+  axesSpec: [{ type: "Int", name: "a1" }],
+};
+
+const column2Spec: PColumnSpec = {
+  kind: "PColumn",
+  name: "column2",
+  valueType: "Int",
+  axesSpec: [{ type: "Int", name: "a1" }],
+};
+
+test("findColumns", () => {
+  using pframe = new PFrame({ column1: column1Spec });
+
+  const response = pframe.findColumns({
+    columnFilter: {},
+    compatibleWith: [],
+    strictlyCompatible: false,
+  });
+
+  expect(response).toEqual({
+    hits: [
+      {
+        hit: { columnId: "column1", spec: column1Spec },
+        mappingVariants: [],
+      },
+    ],
+  });
+});
+
+test("discoverColumns", () => {
+  using pframe = new PFrame({
+    column1: column1Spec,
+    column2: column2Spec,
+  });
+
+  const request = {
+    axes: [],
+    includeColumns: [],
+    constraints: {
+      allowFloatingSourceAxes: true,
+      allowFloatingHitAxes: true,
+      allowSourceQualifications: true,
+      allowHitQualifications: true,
+    },
+  };
+
+  const response = pframe.discoverColumns(request);
+
+  expect(response).toEqual({
+    hits: [
+      {
+        hit: { columnId: "column1", spec: column1Spec },
+        mappingVariants: [],
+        path: [],
+      },
+      {
+        hit: { columnId: "column2", spec: column2Spec },
+        mappingVariants: [],
+        path: [],
+      },
+    ],
+  });
+});
+
+test("deleteColumns", () => {
+  using pframe = new PFrame({});
+
+  const response = pframe.deleteColumns({
+    columns: [
+      { axesSpec: [{ type: "Int", name: "a1" }], qualifications: [] },
+      {
+        axesSpec: [
+          { type: "Int", name: "a1" },
+          { type: "Int", name: "a2" },
+        ],
+        qualifications: [],
+      },
+    ],
+    delete: 1,
+  });
+
+  expect(response).toEqual({
+    columns: [{ axesSpec: [{ type: "Int", name: "a1" }], qualifications: [] }],
+  });
+});
+
+test("evaluateQuery", () => {
+  using pframe = new PFrame({ column1: column1Spec });
+
+  const response = pframe.evaluateQuery({
+    type: "column",
+    column: "column1" as PObjectId,
+  });
+
+  expect(response.tableSpec).toEqual([
+    {
+      type: "axis",
+      id: { name: "a1", type: "Int" },
+      spec: { name: "a1", type: "Int" },
+    },
+    {
+      type: "column",
+      id: "column1",
+      spec: column1Spec,
+    },
+  ]);
+  expect(response.dataQuery).toEqual({
+    type: "column",
+    column: "column1",
+  });
+});
+
+test("listColumns", () => {
+  using pframe = new PFrame({
+    column1: column1Spec,
+    column2: column2Spec,
+  });
+
+  const columns = pframe.listColumns();
+
+  expect(columns).toEqual([
+    { columnId: "column1", spec: column1Spec },
+    { columnId: "column2", spec: column2Spec },
+  ]);
+});
+
+test("getColumn", () => {
+  using pframe = new PFrame({
+    column1: column1Spec,
+    column2: column2Spec,
+  });
+
+  expect(pframe.getColumn("column1" as PObjectId)).toEqual({
+    columnId: "column1",
+    spec: column1Spec,
+  });
+  expect(pframe.getColumn("missing" as PObjectId)).toBeNull();
+});
+
+test("buildQuery (top-level, no frame needed)", () => {
+  const columnId = "c1" as PObjectId;
+
+  const entry = buildQuery({ version: "v1", column: columnId });
+
+  expect(entry.entry).toEqual({ type: "column", column: columnId });
+});
+
+test("discoverColumns: parallel linkers with cd-disambiguated one-side axes yield 4 variants", () => {
+  // This test mirrors case 42 in pframes-rs-spec. Two sibling linkers each
+  // expose two `a2` axes on the one-side, and a context domain makes the two
+  // axes different. A hit with an `a2` axis that has no context domain
+  // matches both axes. Therefore there are 2 paths x 2 context domain
+  // choices, and the result has 4 variants.
+  const linkerAxes = [
+    { type: "Int", name: "a3" },
+    { type: "Int", name: "a2", parentAxes: [0], contextDomain: { d: "1" } },
+    { type: "Int", name: "a2", parentAxes: [0], contextDomain: { d: "2" } },
+    { type: "Int", name: "a1" },
+  ];
+  const lClosest: PColumnSpec = {
+    kind: "PColumn",
+    name: "linker",
+    valueType: "Int",
+    axesSpec: linkerAxes,
+    domain: { algo: "closest" },
+    annotations: { "pl7.app/isLinkerColumn": "true" },
+  } as PColumnSpec;
+  const lFuel: PColumnSpec = {
+    kind: "PColumn",
+    name: "linker",
+    valueType: "Int",
+    axesSpec: linkerAxes,
+    domain: { algo: "fuelOpt" },
+    annotations: { "pl7.app/isLinkerColumn": "true" },
+  } as PColumnSpec;
+  const hitSpec: PColumnSpec = {
+    kind: "PColumn",
+    name: "hit",
+    valueType: "Int",
+    axesSpec: [
+      { type: "Int", name: "a3" },
+      { type: "Int", name: "a2", parentAxes: [0] },
+    ],
+  };
+
+  using pframe = new PFrame({
+    l_closest: lClosest,
+    l_fuel: lFuel,
+    hit: hitSpec,
+  });
+
+  const response = pframe.discoverColumns({
+    axes: [{ axesSpec: [{ type: "Int", name: "a1" }], qualifications: [] }],
+    maxHops: 1,
+    constraints: {
+      allowFloatingSourceAxes: true,
+      allowFloatingHitAxes: false,
+      allowSourceQualifications: false,
+      allowHitQualifications: true,
+    },
+  });
+
+  expect(response.hits).toHaveLength(2);
+  const paths = response.hits
+    .map((h) => h.path.map((s) => (s.type === "linker" ? s.linker.columnId : s.filter.columnId)))
+    .sort();
+  expect(paths).toEqual([["l_closest"], ["l_fuel"]]);
+  for (const hit of response.hits) {
+    expect(hit.hit.columnId).toBe("hit");
+    expect(hit.mappingVariants).toHaveLength(2);
+    const cdValues = hit.mappingVariants
+      .map((v) => v.qualifications.forHit[0]?.contextDomain?.d)
+      .sort();
+    expect(cdValues).toEqual(["1", "2"]);
+  }
+});
+
+test("rewriteLegacyQuery", () => {
+  using pframe = new PFrame({ column1: column1Spec });
+
+  const response = pframe.rewriteLegacyQuery({
+    src: { type: "column", column: "column1" as PObjectId },
+    filters: [],
+  });
+
+  expect(response).toEqual({
+    type: "column",
+    column: "column1",
+  });
+});
+
+test("rewriteLegacyFilters", () => {
+  const response = rewriteLegacyFilters({
+    tableSpec: [
+      { type: "axis", id: { type: "Int", name: "a1" }, spec: { type: "Int", name: "a1" } },
+      { type: "column", id: "column1" as PObjectId, spec: column1Spec },
+    ],
+    filters: [
+      {
+        type: "bySingleColumnV2",
+        column: { type: "column", id: "column1" as PObjectId },
+        predicate: { operator: "Equal", reference: 30 },
+      },
+    ],
+  });
+
+  // Selectors resolve to indices. The column value is `columnRef` 0.
+  expect(response).toEqual([
+    {
+      type: "numericComparison",
+      operand: "eq",
+      left: { type: "columnRef", value: 0 },
+      right: { type: "constant", value: 30 },
+    },
+  ]);
+});

package/src/p-frame.ts

@@ -0,0 +1,148 @@
+import type {
+  EvaluateQueryResponse,
+  JoinEntry,
+  PColumnIdAndSpec,
+  PColumnSpec,
+  PColumnValue,
+  PObjectId,
+  PTableRecordFilter,
+  PTableSorting,
+  SpecQuery,
+} from "@milaboratories/pl-model-common";
+import type { PFrameInternal } from "@milaboratories/pl-model-middle-layer";
+import { spec as bindings } from "./generated/pframes_rs_wasip2.js";
+
+/** A legacy (V4) query. Code used this type before the unified `SpecQuery`. */
+export type LegacyQuery = {
+  /** The source join entry. It defines the data sources and the join structure. */
+  src: JoinEntry<PObjectId>;
+  /** Optional record-level filters. The query applies these to its results. */
+  filters?: PTableRecordFilter[];
+  /** Optional sort specifications. They set the order of the results. */
+  sorting?: PTableSorting[];
+};
+
+/**
+ * A set of registered column specs, and the spec-plane operations on them.
+ *
+ * Each method uses the specs that this frame holds. No method reads data. The module
+ * surface holds the spec operations that do not need a frame.
+ *
+ * This class holds a WASM resource. Use a `using` declaration to release it. Garbage
+ * collection also releases the resource, but not at a known time.
+ */
+export class PFrame implements Disposable {
+  #frame: bindings.Frame;
+
+  constructor(spec: Record<string, PColumnSpec>) {
+    this.#frame = bindings.Frame.fromJson(JSON.stringify(spec));
+  }
+
+  /** Deletes columns from a columns specification. */
+  deleteColumns(
+    request: PFrameInternal.DeleteColumnFromColumnsRequest,
+  ): PFrameInternal.DeleteColumnFromColumnsResponse {
+    return JSON.parse(bindings.Frame.deleteColumns(JSON.stringify(request)));
+  }
+
+  /** Returns `null` if this frame has no column with the id `columnId`. */
+  getColumn(columnId: PObjectId): PColumnIdAndSpec | null {
+    return JSON.parse(this.#frame.getColumn(JSON.stringify(columnId)));
+  }
+
+  /** Lists each column in this frame with its id and its spec. */
+  listColumns(): PColumnIdAndSpec[] {
+    const columns = JSON.parse(this.#frame.listColumns()) as Record<string, PColumnIdAndSpec>;
+    return Object.values(columns);
+  }
+
+  /**
+   * Discovers the columns that are compatible with a given axes integration.
+   *
+   * The include filters and the exclude filters apply in order. The exclude filters
+   * remove matches from the include set. Each hit has its own traversal `path`. To
+   * materialize a hit as a `SpecQueryJoinEntry`, give the hit's column id and `path`
+   * to {@link buildQuery}.
+   */
+  discoverColumns(
+    request: PFrameInternal.DiscoverColumnsRequestV2,
+  ): PFrameInternal.DiscoverColumnsResponse {
+    return JSON.parse(this.#frame.discoverColumns(JSON.stringify(request)));
+  }
+
+  /** Finds the columns in this frame that match the given filter criteria. */
+  findColumns(request: PFrameInternal.FindColumnsRequest): PFrameInternal.FindColumnsResponse {
+    return JSON.parse(this.#frame.findColumns(JSON.stringify(request)));
+  }
+
+  /** Resolves a query against this frame's specs. Returns a table spec and a data query. */
+  evaluateQuery(request: SpecQuery): EvaluateQueryResponse {
+    return JSON.parse(this.#frame.evaluateQuery(JSON.stringify(request)));
+  }
+
+  /** Upgrades a {@link LegacyQuery} to the current `SpecQuery` format. */
+  rewriteLegacyQuery(request: LegacyQuery): SpecQuery {
+    const src = joinEntryToInternal(request.src);
+    return JSON.parse(this.#frame.rewriteLegacyQuery(JSON.stringify({ ...request, src })));
+  }
+
+  [Symbol.dispose](): void {
+    this.#frame[Symbol.dispose]();
+  }
+}
+
+function joinEntryToInternal(entry: JoinEntry<PObjectId>): PFrameInternal.JoinEntryV4 {
+  const type = entry.type;
+  switch (type) {
+    case "column":
+      return {
+        type: "column",
+        columnId: entry.column,
+      };
+    case "slicedColumn":
+      return {
+        type: "slicedColumn",
+        columnId: entry.column,
+        newId: entry.newId,
+        axisFilters: entry.axisFilters,
+      };
+    case "artificialColumn":
+      return {
+        type: "artificialColumn",
+        columnId: entry.column,
+        newId: entry.newId,
+        axesIndices: entry.axesIndices,
+      };
+    case "inlineColumn":
+      return {
+        type: "inlineColumn",
+        newId: entry.column.id,
+        spec: entry.column.spec,
+        dataInfo: {
+          type: "Json",
+          keyLength: entry.column.spec.axesSpec.length,
+          data: entry.column.data.reduce(
+            (acc, row) => {
+              acc[JSON.stringify(row.key)] = row.val;
+              return acc;
+            },
+            {} as Record<string, PColumnValue>,
+          ),
+        },
+      };
+    case "inner":
+    case "full":
+      return {
+        type: entry.type,
+        entries: entry.entries.map((col) => joinEntryToInternal(col)),
+      };
+    case "outer":
+      return {
+        type: "outer",
+        primary: joinEntryToInternal(entry.primary),
+        secondary: entry.secondary.map((col) => joinEntryToInternal(col)),
+      };
+    default:
+      throw new Error(`unsupported PFrame join entry type: ${type satisfies never}`);
+  }
+}

package/src/rewrite-filters.ts

@@ -0,0 +1,23 @@
+import type {
+  DataQueryBooleanExpression,
+  PTableColumnSpec,
+  PTableRecordFilter,
+} from "@milaboratories/pl-model-common";
+import { spec as bindings } from "./generated/pframes_rs_wasip2.js";
+
+/**
+ * Upgrades the selector-based legacy record filters into index-based boolean
+ * expressions for the data layer. It resolves them against the given unified
+ * table spec, which holds the axes first and then the columns.
+ *
+ * The operation is stateless, because a filter does not change the spec of a
+ * table. Therefore the result is valid for `getUniqueValues`, which works on
+ * the single-column table of the source column. The result is also valid when
+ * you compose a `filter` over a `table` query node.
+ */
+export function rewriteLegacyFilters(request: {
+  tableSpec: PTableColumnSpec[];
+  filters: PTableRecordFilter[];
+}): DataQueryBooleanExpression[] {
+  return JSON.parse(bindings.Frame.rewriteLegacyFilters(JSON.stringify(request)));
+}

package/src/table.test.ts

@@ -0,0 +1,35 @@
+import type { PColumnSpec, PObjectId, PTableColumnSpec } from "@milaboratories/pl-model-common";
+import { expect, test } from "vitest";
+import { findColumn } from "./table.ts";
+
+const column1Spec: PColumnSpec = {
+  kind: "PColumn",
+  name: "column1",
+  valueType: "Int",
+  axesSpec: [{ type: "Int", name: "a1" }],
+};
+
+const tableSpec: PTableColumnSpec[] = [
+  {
+    type: "axis",
+    id: { name: "a1", type: "Int" },
+    spec: { name: "a1", type: "Int" },
+  },
+  {
+    type: "column",
+    id: "column1" as PObjectId,
+    spec: column1Spec,
+  },
+];
+
+test("findColumn - axis", () => {
+  expect(findColumn(tableSpec, { type: "axis", id: { name: "a1", type: "Int" } })).toBe(0);
+});
+
+test("findColumn - column", () => {
+  expect(findColumn(tableSpec, { type: "column", id: "column1" as PObjectId })).toBe(1);
+});
+
+test("findColumn - not found", () => {
+  expect(findColumn(tableSpec, { type: "column", id: "nonexistent" as PObjectId })).toBe(-1);
+});

package/src/table.ts

@@ -0,0 +1,11 @@
+import type { PTableColumnId, PTableColumnSpec } from "@milaboratories/pl-model-common";
+import { spec as bindings } from "./generated/pframes_rs_wasip2.js";
+
+export function findColumn(tableSpec: PTableColumnSpec[], selector: PTableColumnId): number {
+  using table = bindings.Table.fromJson(JSON.stringify(tableSpec));
+  try {
+    return JSON.parse(table.findColumn(JSON.stringify(selector)));
+  } catch {
+    return -1;
+  }
+}