@platforma-sdk/model 1.79.24 → 1.80.0

package/src/columns/column_recipes/column_filtered_recipe.ts

@@ -0,0 +1,184 @@
+import {
+  applyAxisFilters,
+  stringifyColumnFilteredId,
+  type AxisFilterByIdx,
+  type AxisSpec,
+  type ColumnFilteredId,
+  type ColumnFilteredKey,
+  type PColumnSpec,
+  type PObjectId,
+  type SingleAxisSelector,
+  type SpecOverrides,
+  type SpecQuery,
+} from "@milaboratories/pl-model-common";
+import type { GlobalCfgRenderCtx } from "../../render/internal";
+import type { ColumnFieldStatus, ColumnResolutionStatus } from "./types";
+import { ColumnRecipe } from "./index";
+import { ColumnOverriddenRecipe } from "./column_overrided_recipe";
+import { rebrandLeafId } from "./leaf_rebrand";
+
+/**
+ * Recipe wrapper that fixes the values of selected axes of an inner recipe
+ * (axis slicing). The id is `FilteredPColumnId { source: inner.id,
+ * axisFilters }`.
+ *
+ * Flat-merge invariant: `inner` is never another {@link ColumnFilteredRecipe}.
+ * Repeated {@link wrap} concatenates `axisFilters` at the current level.
+ *
+ * Layering: `withSpecs` on a Filtered recipe yields
+ * `Overridden<Filtered<inner>>` — Overridden is always the outermost layer.
+ * The reverse layering (`Filtered<Overridden<...>>`) is not reachable via
+ * the public interface.
+ */
+export class ColumnFilteredRecipe implements ColumnRecipe<ColumnFilteredId> {
+  /**
+   * Wrap any recipe with axis filters. If `inner` is already a
+   * {@link ColumnFilteredRecipe}, concatenates `axisFilters` and returns a
+   * new Filtered sharing the original `inner`.
+   *
+   * Validates every axis index against `inner.getSpec().axesSpec` at
+   * construction — throws on an out-of-range index. After {@link wrap}, the
+   * recipe is guaranteed to be spec-complete.
+   *
+   * Order semantics: new filters are appended after existing ones, preserving
+   * their relative order. AND composition is otherwise commutative; order
+   * only affects canonicalize/equality.
+   */
+  static wrap(col: ColumnRecipe, axisFilters: AxisFilterByIdx[]): ColumnFilteredRecipe {
+    const combined =
+      col instanceof ColumnFilteredRecipe ? [...col.axisFilters, ...axisFilters] : axisFilters;
+    const base = col instanceof ColumnFilteredRecipe ? col.inner : col;
+
+    if (combined.length === 0) {
+      throw new Error("ColumnFilteredRecipe.wrap: at least one axis filter must be provided");
+    }
+
+    const innerSpec = base.getSpec();
+    const fixed = new Set<number>();
+    for (const [idx] of combined) {
+      if (innerSpec.axesSpec[idx] === undefined) {
+        throw new Error(
+          `ColumnFilteredRecipe.wrap: axis index ${idx} out of range (inner has ${innerSpec.axesSpec.length} axes)`,
+        );
+      }
+      fixed.add(idx);
+    }
+    if (fixed.size >= innerSpec.axesSpec.length) {
+      throw new Error(
+        `ColumnFilteredRecipe.wrap: filters fix all ${innerSpec.axesSpec.length} axes — at least one axis must remain`,
+      );
+    }
+
+    return new ColumnFilteredRecipe(base, combined);
+  }
+
+  /**
+   * Static counterpart to {@link wrap}: returns the resolution status of a
+   * {@link ColumnFilteredKey} without constructing the recipe. Axis filters
+   * do not add references — status collapses to the source's status.
+   */
+  static getStatusByKey(
+    key: ColumnFilteredKey,
+    opts: { ctx?: GlobalCfgRenderCtx } = {},
+  ): ColumnResolutionStatus {
+    if (typeof key.source !== "string") {
+      throw new Error(
+        "ColumnFilteredRecipe.getStatusByKey: filtered column with non-string source",
+      );
+    }
+    return ColumnRecipe.getStatus(key.source, opts);
+  }
+
+  readonly id: ColumnFilteredId;
+  private specCache?: { readonly value: PColumnSpec };
+  private queryCache?: { readonly value: SpecQuery };
+  private dataStatusCache?: { readonly value: ColumnFieldStatus };
+
+  private constructor(
+    private readonly inner: ColumnRecipe,
+    private readonly axisFilters: AxisFilterByIdx[],
+  ) {
+    this.id = stringifyColumnFilteredId({
+      source: inner.id,
+      axisFilters,
+    });
+  }
+
+  /** Wrapped recipe — exposed so external walkers can descend. */
+  getInner(): ColumnRecipe {
+    return this.inner;
+  }
+
+  /** Axis filters do not introduce references to other columns. */
+  getReferencedIds(): PObjectId[] {
+    return this.inner.getReferencedIds();
+  }
+
+  getDataStatus(): ColumnFieldStatus {
+    if (this.dataStatusCache === undefined) {
+      this.dataStatusCache = { value: this.inner.getDataStatus() };
+    }
+    return this.dataStatusCache.value;
+  }
+
+  /**
+   * Final spec — the inner spec with fixed axes removed. Indices in
+   * `axisFilters` are positional against `inner.getSpec().axesSpec` and were
+   * validated at {@link wrap} time.
+   */
+  getSpec(): PColumnSpec {
+    if (this.specCache === undefined) {
+      this.specCache = { value: applyAxisFilters(this.inner.getSpec(), this.axisFilters) };
+    }
+    return this.specCache.value;
+  }
+
+  /**
+   * Wraps the inner query in `SpecQuerySliceAxes`. Index→selector resolution
+   * goes through the inner spec — guaranteed available since {@link wrap}
+   * validated all indices at construction.
+   */
+  getQuery(): SpecQuery {
+    if (this.queryCache === undefined) {
+      const innerQuery = this.inner.getQuery();
+      if (this.axisFilters.length === 0) {
+        // Pass-through (no filters): rebrand the inner leaf to this.id so
+        // wrappers in the chain don't reintroduce the inner's id at the
+        // leaf — keeps the resolver/leaf-id contract uniform.
+        this.queryCache = { value: rebrandLeafId(innerQuery, this.inner.id, this.id) };
+      } else {
+        const innerSpec = this.inner.getSpec();
+        this.queryCache = {
+          value: {
+            type: "sliceAxes",
+            input: rebrandLeafId(innerQuery, this.inner.id, this.id),
+            axisFilters: this.axisFilters.map(([idx, value]) => ({
+              axisSelector: toAxisSelector(innerSpec.axesSpec[idx]),
+              constant: value,
+            })),
+          },
+        };
+      }
+    }
+    return this.queryCache.value;
+  }
+
+  /**
+   * Filtered + overrides → Overridden<Filtered>. Overridden is always the
+   * outermost layer.
+   */
+  withSpecs(overrides: SpecOverrides): ColumnRecipe {
+    return ColumnOverriddenRecipe.wrap(this, overrides);
+  }
+}
+
+function toAxisSelector(axis: AxisSpec): SingleAxisSelector {
+  const selector: SingleAxisSelector = { name: axis.name, type: axis.type };
+  if (axis.domain !== undefined && Object.keys(axis.domain).length > 0) {
+    selector.domain = axis.domain;
+  }
+  if (axis.contextDomain !== undefined && Object.keys(axis.contextDomain).length > 0) {
+    selector.contextDomain = axis.contextDomain;
+  }
+  return selector;
+}

package/src/columns/column_recipes/column_overrided_recipe.ts

@@ -0,0 +1,146 @@
+import {
+  applySpecOverrides,
+  createColumnOverriddenId,
+  mergeSpecOverrides,
+  type ColumnOverriddenId,
+  type ColumnOverriddenKey,
+  type ColumnUniversalId,
+  type PColumnSpec,
+  type PObjectId,
+  type SpecOverrides,
+  type SpecQuery,
+} from "@milaboratories/pl-model-common";
+import type { GlobalCfgRenderCtx } from "../../render/internal";
+import type { ColumnFieldStatus, ColumnResolutionStatus } from "./types";
+import { ColumnRecipe } from "./index";
+import { Column } from "../column";
+import { rebrandLeafId } from "./leaf_rebrand";
+
+/**
+ * A recipe whose id is not an Overridden wrap — valid `source` for Overridden.
+ * Mirrors the spec-level invariant on {@link ColumnOverriddenKey.source}.
+ */
+type NonOverriddenColumn = Column<Exclude<ColumnUniversalId, ColumnOverriddenId>>;
+
+/**
+ * Recipe wrapper that overlays {@link SpecOverrides} on top of any other
+ * recipe. The id is `ColumnOverriddenKey { source: inner.id, specOverrides }`.
+ *
+ * Flat-merge invariant: `inner` is never another {@link ColumnOverriddenRecipe}.
+ * Repeated overrides go through {@link wrap} / {@link withSpecs}, which merge
+ * `specOverrides` at the current level and keep wrapper depth constant.
+ *
+ * This invariant matches the one enforced inside `unwrapOverrides` from
+ * pl-model-common: it explicitly throws on a nested override-wrap.
+ */
+export class ColumnOverriddenRecipe implements Column<ColumnOverriddenId> {
+  /**
+   * Wrap any recipe with overrides. If `inner` is already a
+   * {@link ColumnOverriddenRecipe}, merges `overrides` into the existing ones
+   * and returns a new Overridden sharing the original `inner`. No
+   * `Overridden<Overridden<X>>` is produced.
+   */
+  static wrap(col: Column, overrides: SpecOverrides): ColumnOverriddenRecipe {
+    if (col instanceof ColumnOverriddenRecipe) {
+      return new ColumnOverriddenRecipe(col.inner, mergeSpecOverrides(col.overrides, overrides));
+    }
+    // `inner` is not an Overridden wrap (the `instanceof` branch above handles
+    // that). Narrow the id union here so the constructor parameter stays
+    // honest with `ColumnOverriddenKey.source`.
+    return new ColumnOverriddenRecipe(col as NonOverriddenColumn, overrides);
+  }
+
+  /**
+   * Static counterpart to {@link wrap}: returns the resolution status of a
+   * {@link ColumnOverriddenKey} without constructing the recipe. Overrides
+   * do not add references — status collapses to the source's status.
+   */
+  static getStatusByKey(
+    key: ColumnOverriddenKey,
+    opts: { ctx?: GlobalCfgRenderCtx } = {},
+  ): ColumnResolutionStatus {
+    return ColumnRecipe.getStatus(key.source, opts);
+  }
+
+  readonly id: ColumnOverriddenId;
+  private specCache?: { readonly value: PColumnSpec };
+  private queryCache?: { readonly value: SpecQuery };
+  private dataStatusCache?: { readonly value: ColumnFieldStatus };
+
+  private constructor(
+    private readonly inner: NonOverriddenColumn,
+    private readonly overrides: SpecOverrides,
+  ) {
+    this.id = createColumnOverriddenId({
+      source: inner.id,
+      specOverrides: overrides,
+    });
+  }
+
+  /** Wrapped recipe — exposed so external walkers can descend. */
+  getInner(): Column {
+    return this.inner;
+  }
+
+  /**
+   * `inner` owns all references; overrides are a pure spec patch and do not
+   * introduce new column refs.
+   */
+  getReferencedIds(): PObjectId[] {
+    return this.inner.getReferencedIds();
+  }
+
+  getDataStatus(): ColumnFieldStatus {
+    if (this.dataStatusCache === undefined) {
+      this.dataStatusCache = { value: this.inner.getDataStatus() };
+    }
+    return this.dataStatusCache.value;
+  }
+
+  /**
+   * Take the inner spec and overlay our overrides. `applySpecOverrides`
+   * extracts the overrides from `this.id` itself.
+   */
+  getSpec(): PColumnSpec {
+    if (this.specCache === undefined) {
+      this.specCache = { value: applySpecOverrides(this.inner.getSpec(), this.id) };
+    }
+    return this.specCache.value;
+  }
+
+  /**
+   * Emit a client-side `specOverride` node wrapping the inner query.
+   *
+   * This is a structural-but-collapsible node: it carries the override
+   * patch through the query tree so consumers see the full recipe shape,
+   * but it is collapsed at the host boundary (`resolvePColumn`) before
+   * the query reaches pframe-engine. The engine never sees this node.
+   *
+   * Overrides do not change query topology — they are a pure spec patch.
+   */
+  getQuery(): SpecQuery {
+    if (this.queryCache === undefined) {
+      // Rebrand the inner column leaf to this.id (rich Overridden id) so
+      // filter/sort references emitted with this recipe's id match the
+      // leaf the engine sees. The specOverride node still wraps the leaf
+      // and is collapsed at the host boundary into a spec patch on the
+      // resolved PColumn.
+      this.queryCache = {
+        value: {
+          type: "specOverride",
+          input: rebrandLeafId(this.inner.getQuery(), this.inner.id, this.id),
+          override: this.overrides,
+        },
+      };
+    }
+    return this.queryCache.value;
+  }
+
+  /**
+   * Flat merge: new overrides merge with existing ones; `inner` is unchanged.
+   * The result is an Overridden of the same depth.
+   */
+  withSpecs(overrides: SpecOverrides): Column {
+    return ColumnOverriddenRecipe.wrap(this, overrides);
+  }
+}