From 5a42b6e2f4d66ee67d175c3c54ff7a60e9237bed Mon Sep 17 00:00:00 2001 From: Alexandr Date: Mon, 16 Nov 2026 10:17:08 +0100 Subject: [PATCH] Show a column with failed data as error in the data table The leaf data read tells a .data field that holds an error from one that has no value yet. DataColumn gives no data for it, and the probe the table runs over its visible columns reports it, so the column gets the error status and the table output no longer throws. No new read is made: the error comes from the read of the field the probe already does. --- .changeset/errored-column-data-status.md | 5 ++ .../columns/__test_helpers__/stub_registry.ts | 57 ++++++++++-- sdk/model/src/columns/data_column.test.ts | 44 +++++++++- sdk/model/src/columns/data_column.ts | 48 ++++++++-- sdk/model/src/columns/utils.test.ts | 87 ++++++++++++++++++- sdk/model/src/columns/utils.ts | 44 +++++++--- .../createPlDataTable/utils.test.ts | 42 ++++++++- .../PlDataTable/createPlDataTable/utils.ts | 16 +++- 8 files changed, 310 insertions(+), 33 deletions(-) create mode 100644 .changeset/errored-column-data-status.md diff --git a/.changeset/errored-column-data-status.md b/.changeset/errored-column-data-status.md new file mode 100644 index 0000000000..60274b7772 --- /dev/null +++ b/.changeset/errored-column-data-status.md @@ -0,0 +1,5 @@ +--- +"@platforma-sdk/model": patch +--- + +A table built with `createPlDataTableV3` shows a column whose data failed with the `error` status, and no longer fails as a whole. The data of a column failed when its `.data` field holds an error, with or without a value. Before, a field with an error and no value made the table output throw, and a field with an error and a value was shown as ready. `DataColumn` leaves now give `undefined` data for such a column. The error is found by the read the table already makes for its visible columns, so no column is read that was not read before, and `getDataStatus()` still does not read the data. New `getColumnDataState` tells ready, pending and failed data apart; `hasColumnData` behaves as before for data that did not fail. A block picks this up when it is rebuilt with this SDK. diff --git a/sdk/model/src/columns/__test_helpers__/stub_registry.ts b/sdk/model/src/columns/__test_helpers__/stub_registry.ts index 6df1e0ff9e..2649ac0d8b 100644 --- a/sdk/model/src/columns/__test_helpers__/stub_registry.ts +++ b/sdk/model/src/columns/__test_helpers__/stub_registry.ts @@ -12,7 +12,8 @@ * - {@link StubLeafConfig} — fine-grained control: omit `spec` to simulate * "no spec field reachable from this leaf"; set `accessorLocked: false` * to simulate a still-resolving leaf accessor; set `specHasData: false` - * to simulate "spec resource exists but bytes not yet written". + * to simulate "spec resource exists but bytes not yet written"; set `data` + * to plant a `.data` field with a data resource, an error, or both. * * Registry-wide `isFinal` is also configurable — pass `{ isFinal: false }` * to simulate a still-enumerating registry where missing ids should report @@ -26,8 +27,8 @@ import type { PObjectSpec, } from "@milaboratories/pl-model-common"; import { isPColumnSpec } from "@milaboratories/pl-model-common"; -import type { GlobalCfgRenderCtx } from "../../render/internal"; -import type { TreeNodeAccessor } from "../../render/accessor"; +import type { AccessorHandle, GlobalCfgRenderCtx } from "../../render/internal"; +import { TreeNodeAccessor } from "../../render/accessor"; import { _ctxProvidersCache } from "../column_providers"; import type { ColumnsProvider } from "../column_providers"; import { DataColumn, type DataColumnRecipe } from "../data_column"; @@ -40,8 +41,20 @@ export type StubLeafConfig = { accessorLocked?: boolean; /** Drives `spec.hasData()` (ignored when `spec` is omitted). Default `true`. */ specHasData?: boolean; + /** The `${id}.data` field. Omit to simulate a missing field. */ + data?: StubDataField; }; +/** + * State of a stubbed `.data` field: + * - `ready`: a data resource with bytes + * - `pending`: a data resource without bytes yet + * - `unset`: the field is there without a value + * - `errored`: the field holds an error and no value + * - `erroredWithValue`: the field holds an error and a data resource + */ +export type StubDataField = "ready" | "pending" | "unset" | "errored" | "erroredWithValue"; + /** Either the shorthand `PColumnSpec` or a {@link StubLeafConfig}. */ export type StubLeafInput = PColumnSpec | StubLeafConfig; @@ -86,6 +99,7 @@ type NormalizedLeafConfig = { spec?: PObjectSpec; accessorLocked: boolean; specHasData: boolean; + data?: StubDataField; }; function normalizeLeafInput(raw: StubLeafInput): NormalizedLeafConfig { @@ -96,9 +110,24 @@ function normalizeLeafInput(raw: StubLeafInput): NormalizedLeafConfig { spec: raw.spec, accessorLocked: raw.accessorLocked ?? true, specHasData: raw.specHasData ?? true, + data: raw.data, }; } +/** A data resource that answers `hasData()` without a render ctx. */ +class StubDataAccessor extends TreeNodeAccessor { + constructor( + handle: AccessorHandle, + private readonly bytes: boolean, + ) { + super(handle, []); + } + + override hasData(): boolean { + return this.bytes; + } +} + let stubAccessorSeq = 0; function stubAccessorFor(id: PObjectId, cfg: NormalizedLeafConfig): TreeNodeAccessor { @@ -115,15 +144,31 @@ function stubAccessorFor(id: PObjectId, cfg: NormalizedLeafConfig): TreeNodeAcce // for the same id should produce a fresh cache lookup (otherwise tests // that vary leaf state for the same id see stale spec accessors). const handle = `${id}#${++stubAccessorSeq}`; + const dataField = `${id}.data`; + const dataValue = + cfg.data === undefined || cfg.data === "unset" || cfg.data === "errored" + ? undefined + : new StubDataAccessor(`${handle}:data` as AccessorHandle, cfg.data !== "pending"); + const dataErrored = cfg.data === "errored" || cfg.data === "erroredWithValue"; const stub = { handle, resolvePath: [], - traverse: (step: { field?: string } | string) => { + traverse: (step: { field?: string; ignoreError?: true } | string) => { const field = typeof step === "string" ? step : step?.field; - return field === specField ? specHolder : undefined; + if (field === specField) return specHolder; + if (field !== dataField) return undefined; + // The tree's rule: a field's error is thrown unless it is ignored and the field has a value. + const ignoreError = typeof step !== "string" && step.ignoreError === true; + if (dataErrored && !(ignoreError && dataValue !== undefined)) { + throw new Error(`field ${dataField} holds an error`); + } + return dataValue; }, getDataAsJson: () => cfg.spec as unknown as T, - listInputFields: () => (cfg.spec !== undefined ? [specField] : []), + listInputFields: () => [ + ...(cfg.spec !== undefined ? [specField] : []), + ...(cfg.data !== undefined ? [dataField] : []), + ], getInputsLocked: () => cfg.accessorLocked, }; return stub as unknown as TreeNodeAccessor; diff --git a/sdk/model/src/columns/data_column.test.ts b/sdk/model/src/columns/data_column.test.ts index cef3298c3e..747cc2d404 100644 --- a/sdk/model/src/columns/data_column.test.ts +++ b/sdk/model/src/columns/data_column.test.ts @@ -9,7 +9,8 @@ import { } from "@milaboratories/pl-model-common"; import { DataColumnImpl } from "./data_column"; import { _ctxProvidersCache } from "./column_providers"; -import { installStubRegistry } from "./__test_helpers__/stub_registry"; +import { installStubRegistry, type StubDataField } from "./__test_helpers__/stub_registry"; +import { TreeNodeAccessor } from "../render/accessor"; // --- Ambient ctx mock ------------------------------------------------------ // DataColumnImpl constructor pulls `getCfgRenderCtx()` from globalThis. A minimal @@ -202,6 +203,47 @@ describe("DataColumnImpl resolution: fromId / fromAccessor / getStatus", () => { }); }); +// --- data of a leaf --------------------------------------------------------- + +describe("DataColumnImpl data of a leaf", () => { + /** The leaf of a column whose spec is there and whose `.data` field is in the given state. */ + function leafWithData(data: StubDataField): DataColumnImpl { + installStubRegistry(mockCtx, { [baseLeaf]: { spec: stubSpec, data } }); + const leaf = DataColumnImpl.fromId(baseLeaf); + if (!(leaf instanceof DataColumnImpl)) throw new Error("leafWithData: no leaf"); + return leaf; + } + + test("gives the data resource of a field that has a value and no error", () => { + const leaf = leafWithData("ready"); + expect(leaf.getData()).toBeInstanceOf(TreeNodeAccessor); + expect(leaf.hasDataError()).toBe(false); + }); + + test("gives no data for a field without a value yet, and no error", () => { + const leaf = leafWithData("unset"); + expect(leaf.getData()).toBeUndefined(); + expect(leaf.hasDataError()).toBe(false); + }); + + test.each(["errored", "erroredWithValue"])( + "gives no data and reports the error of a field in state %s", + (data) => { + const leaf = leafWithData(data); + expect(leaf.getData()).toBeUndefined(); + expect(leaf.hasDataError()).toBe(true); + // The status tells only that the field is there; it does not read the field. + expect(leaf.getDataStatus()).toBe("present"); + }, + ); + + test("a materialised column has no data error", () => { + const leaf = lazyOf(baseLeaf); + if (!(leaf instanceof DataColumnImpl)) throw new Error("no leaf"); + expect(leaf.hasDataError()).toBe(false); + }); +}); + /** Pull the `LeafEntry` planted by the stub registry for a given id. */ function pluckLeafEntry(id: PObjectId) { const entry = _ctxProvidersCache.get(mockCtx)?.[0]?.getPObjectEntries().get(id); diff --git a/sdk/model/src/columns/data_column.ts b/sdk/model/src/columns/data_column.ts index c05b1d9a4f..fb5336a6ab 100644 --- a/sdk/model/src/columns/data_column.ts +++ b/sdk/model/src/columns/data_column.ts @@ -72,6 +72,7 @@ export class DataColumnImpl implements DataColumnRecipe { getSpec: () => PColumnSpec; getData: () => ColumnData; getDataStatus: () => ColumnFieldStatus; + hasDataError: () => boolean; }, ) {} @@ -104,6 +105,16 @@ export class DataColumnImpl implements DataColumnRecipe { return this.dataStatusCache.value; } + /** + * Whether the column's data failed: its `.data` field holds an error, and + * {@link getData} gives `undefined`. Reads the field, as {@link getData} + * does, so it is asked only where the data is read anyway; + * {@link getDataStatus} does not read it. + */ + hasDataError(): boolean { + return this.options.hasDataError(); + } + /** * Overlay overrides → produces a {@link ColumnOverriddenRecipe} wrapping * this leaf. The leaf itself stays bare (id remains a plain PObjectId); @@ -145,8 +156,9 @@ export class DataColumnImpl implements DataColumnRecipe { if (spec === undefined || !isPColumnSpec(spec)) return undefined; return new DataColumnImpl(entry.id, { getSpec: () => spec, - getData: () => readDataAccessor(entry), + getData: () => readDataNode(entry), getDataStatus: () => readDataStatus(entry), + hasDataError: () => readData(entry).type === "errored", }); } @@ -167,6 +179,7 @@ export class DataColumnImpl implements DataColumnRecipe { getSpec: () => pColumn.spec, getData: () => pColumn.data, getDataStatus: () => "present", + hasDataError: () => false, }); } @@ -299,10 +312,35 @@ function getLeafEntryStatus(entry: LeafEntry): ColumnResolutio return "present"; } -const readDataAccessor = memoizeByEntry( - ({ accessor, name }: LeafEntry): undefined | TreeNodeAccessor => - accessor.traverse({ field: `${name}.data`, assertFieldType: "Input", ignoreError: true }), -); +/** + * The `.data` field of a leaf: its data resource, none while the field has no + * value yet, or the fact that the field holds an error. + */ +type LeafDataRead = + | { readonly type: "node"; readonly node: undefined | TreeNodeAccessor } + | { readonly type: "errored" }; + +/** + * One read of the leaf's `.data` field. A field that holds an error reads as + * `errored` whether or not it also has a value: the data resource behind it + * failed. + */ +const readData = memoizeByEntry(({ accessor, name }: LeafEntry): LeafDataRead => { + const field = `${name}.data`; + try { + return { type: "node", node: accessor.traverse({ field, assertFieldType: "Input" }) }; + } catch (error) { + // Only a field that is there can hold an error; any other failure stays the caller's. + if (!accessor.listInputFields().includes(field)) throw error; + return { type: "errored" }; + } +}); + +/** The leaf's data resource; `undefined` while it is not there, and when the data failed. */ +function readDataNode(entry: LeafEntry): undefined | TreeNodeAccessor { + const read = readData(entry); + return read.type === "node" ? read.node : undefined; +} const readDataStatus = memoizeByEntry( ({ accessor, name }: LeafEntry): ColumnFieldStatus => { diff --git a/sdk/model/src/columns/utils.test.ts b/sdk/model/src/columns/utils.test.ts index 20e989b007..f8ffc6417c 100644 --- a/sdk/model/src/columns/utils.test.ts +++ b/sdk/model/src/columns/utils.test.ts @@ -11,12 +11,18 @@ import { type SpecQuery, type ColumnUniversalId, } from "@milaboratories/pl-model-common"; -import { collectLinkerIds, hitQualifications, queriesQualifications } from "./utils"; +import { + collectLinkerIds, + getColumnDataState, + hasColumnData, + hitQualifications, + queriesQualifications, +} from "./utils"; import { ColumnDiscoveredRecipe } from "./column_recipes/column_discovered_recipe"; import { ColumnFilteredRecipe } from "./column_recipes/column_filtered_recipe"; import { ColumnOverriddenRecipe } from "./column_recipes/column_overrided_recipe"; import type { ColumnFieldStatus, ColumnRecipe } from "./column_recipes/types"; -import { installStubRegistry } from "./__test_helpers__/stub_registry"; +import { installStubRegistry, type StubDataField } from "./__test_helpers__/stub_registry"; // ── ctx mock ──────────────────────────────────────────────────────────────── // ColumnDiscoveredRecipe pulls `getCfgRenderCtx()` for `pframeSpec`. Minimal @@ -247,3 +253,80 @@ describe("queriesQualifications", () => { expect(queriesQualifications(wrapped)).toEqual(quals); }); }); + +// ════════════════════════════════════════════════════════════════════════════ +// getColumnDataState +// ════════════════════════════════════════════════════════════════════════════ + +describe("getColumnDataState", () => { + const first = createLocalPObjectId(["main", "out"], "first"); + const second = createLocalPObjectId(["main", "out"], "second"); + const leafSpec: PColumnSpec = { + kind: "PColumn", + name: "stub", + valueType: "String", + axesSpec: [], + }; + + /** A recipe that depends on the given leaves, in order. */ + class RefsRecipe extends StubRecipe { + constructor(private readonly refs: PObjectId[]) { + super(refs[0], colNode(refs[0])); + } + override getReferencedIds(): PObjectId[] { + return this.refs; + } + } + + /** A recipe over leaves whose `.data` fields are in the given states; `undefined` is no field. */ + function recipeOver(leaves: [PObjectId, undefined | StubDataField][]): ColumnRecipe { + installStubRegistry( + activeCtx, + new Map(leaves.map(([id, data]) => [id, { spec: leafSpec, data }])), + ); + return new RefsRecipe(leaves.map(([id]) => id)); + } + + test("ready when every data resource has bytes", () => { + const column = recipeOver([ + [first, "ready"], + [second, "ready"], + ]); + expect(getColumnDataState(column)).toBe("ready"); + expect(hasColumnData(column)).toBe(true); + }); + + test.each([undefined, "unset", "pending"])( + "pending for a data field in state %s", + (data) => { + const column = recipeOver([[first, data]]); + expect(getColumnDataState(column)).toBe("pending"); + expect(hasColumnData(column)).toBe(false); + }, + ); + + test.each(["errored", "erroredWithValue"])( + "errored for a data field in state %s", + (data) => { + const column = recipeOver([[first, data]]); + expect(getColumnDataState(column)).toBe("errored"); + expect(hasColumnData(column)).toBe(false); + }, + ); + + test("reports the failed data of a leaf that follows a ready one", () => { + const column = recipeOver([ + [first, "ready"], + [second, "errored"], + ]); + expect(getColumnDataState(column)).toBe("errored"); + }); + + test("stops at the first leaf whose data is not ready", () => { + const column = recipeOver([ + [first, "pending"], + [second, "errored"], + ]); + expect(getColumnDataState(column)).toBe("pending"); + }); +}); diff --git a/sdk/model/src/columns/utils.ts b/sdk/model/src/columns/utils.ts index 5f655c68f5..a7137950c6 100644 --- a/sdk/model/src/columns/utils.ts +++ b/sdk/model/src/columns/utils.ts @@ -108,30 +108,46 @@ export function queriesQualifications( } /** - * Whether the recipe's underlying data resources actually carry bytes — - * strictly stronger than `getDataStatus() === "present"`, which only tells - * that the `.data` field is wired onto the accessor. + * What reading a recipe's data finds: bytes in every data resource it depends + * on (`ready`), data still to come (`pending`), or data that failed (`errored`). + */ +export type ColumnDataState = "ready" | "pending" | "errored"; + +/** + * The state of the recipe's underlying data resources — strictly stronger + * than `getDataStatus() === "present"`, which only tells that the `.data` + * field is wired onto the accessor. * * Walks every physical leaf the recipe depends on via * {@link ColumnRecipe.getReferencedIds} (resolves each id back to a - * {@link DataColumnRecipe} through the ambient ctx) and ANDs `hasData()` across - * all of them. Inline {@link PColumnValues} payloads count as present. + * {@link DataColumnRecipe} through the ambient ctx), in order, and stops at + * the first leaf whose data is not ready: a leaf after it is not read. Inline + * {@link PColumnValues} payloads count as ready. * - * Returns `false` if any leaf cannot be re-resolved in `opts.ctx` (treat as - * "not yet ready") rather than throwing — this is a UI-facing predicate, not - * a contract assertion. + * `pending` if any leaf cannot be re-resolved in `opts.ctx` (treat as "not + * yet ready") rather than throwing — this is a UI-facing probe, not a + * contract assertion. */ -export function hasColumnData( +export function getColumnDataState( recipe: ColumnRecipe, opts: { ctx?: GlobalCfgRenderCtx } = {}, -): boolean { +): ColumnDataState { for (const id of recipe.getReferencedIds()) { const leaf = DataColumnImpl.fromId(id, opts); - if (leaf === undefined) return false; - if (leaf.getDataStatus() !== "present") return false; - if (!isLeafDataPresent(leaf.getData())) return false; + if (leaf === undefined) return "pending"; + if (leaf.getDataStatus() !== "present") return "pending"; + if (leaf instanceof DataColumnImpl && leaf.hasDataError()) return "errored"; + if (!isLeafDataPresent(leaf.getData())) return "pending"; } - return true; + return "ready"; +} + +/** Whether the recipe's underlying data resources actually carry bytes. */ +export function hasColumnData( + recipe: ColumnRecipe, + opts: { ctx?: GlobalCfgRenderCtx } = {}, +): boolean { + return getColumnDataState(recipe, opts) === "ready"; } function isLeafDataPresent(data: ColumnData): boolean { diff --git a/sdk/model/src/components/PlDataTable/createPlDataTable/utils.test.ts b/sdk/model/src/components/PlDataTable/createPlDataTable/utils.test.ts index 59274ea5d2..227a3ca0d5 100644 --- a/sdk/model/src/components/PlDataTable/createPlDataTable/utils.test.ts +++ b/sdk/model/src/components/PlDataTable/createPlDataTable/utils.test.ts @@ -5,13 +5,18 @@ import { type PObjectId, } from "@milaboratories/pl-model-common"; import { afterEach, beforeEach, describe, expect, test } from "vitest"; -import { deriveAllLabels, evaluateRules, type LabelableColumn } from "./utils"; +import { buildDataStatusMap, deriveAllLabels, evaluateRules, type LabelableColumn } from "./utils"; import type { ColumnOrderRule, ColumnVisibilityRule } from "./createPlDataTableV3"; import { DataColumn, type DataColumnRecipe } from "../../../columns"; import { createTestCollectionDriver, type TestCollectionDriverHandle, } from "../../../columns/__test_helpers__/collection_driver"; +import { + installStubRegistry, + type StubLeafConfig, +} from "../../../columns/__test_helpers__/stub_registry"; +import { getCfgRenderCtx } from "../../../internal"; // --------------------------------------------------------------------------- // Helpers @@ -247,3 +252,38 @@ describe("evaluateRules", () => { expect(result.get(gid("d"))?.visibility).toBe("hidden"); }); }); + +// --------------------------------------------------------------------------- +// buildDataStatusMap +// --------------------------------------------------------------------------- + +describe("buildDataStatusMap", () => { + test("tells ready, computing, absent and failed data apart", () => { + const spec = makeSpec(); + const leaves: [PObjectId, StubLeafConfig][] = [ + [gid("ready"), { spec, data: "ready" }], + [gid("no-bytes"), { spec, data: "pending" }], + [gid("unset"), { spec, data: "unset" }], + [gid("resolving"), { spec, accessorLocked: false }], + [gid("absent"), { spec }], + [gid("errored"), { spec, data: "errored" }], + [gid("errored-with-value"), { spec, data: "erroredWithValue" }], + ]; + installStubRegistry(getCfgRenderCtx(), new Map(leaves)); + const columns = leaves.map(([id]) => { + const column = DataColumn.fromId(id); + if (column === undefined) throw new Error(`no column for ${id}`); + return column; + }); + + expect(buildDataStatusMap(columns)).toEqual({ + [gid("ready")]: "ready", + [gid("no-bytes")]: "computing", + [gid("unset")]: "computing", + [gid("resolving")]: "computing", + [gid("absent")]: "absent", + [gid("errored")]: "error", + [gid("errored-with-value")]: "error", + }); + }); +}); diff --git a/sdk/model/src/components/PlDataTable/createPlDataTable/utils.ts b/sdk/model/src/components/PlDataTable/createPlDataTable/utils.ts index 67188040b0..432aefa993 100644 --- a/sdk/model/src/components/PlDataTable/createPlDataTable/utils.ts +++ b/sdk/model/src/components/PlDataTable/createPlDataTable/utils.ts @@ -18,7 +18,7 @@ import { } from "../../../labels/derive_distinct_tooltips"; import type { ColumnOrderRule, ColumnVisibilityRule } from "./createPlDataTableV3"; import type { ColumnSelector, MatchQualifications } from "@milaboratories/pl-model-common"; -import { ColumnsCollection, hasColumnData, type ColumnRecipe } from "../../../columns"; +import { ColumnsCollection, getColumnDataState, type ColumnRecipe } from "../../../columns"; import type { GlobalCfgRenderCtx } from "../../../render/internal"; import { isNil, uniqBy } from "es-toolkit"; import { getField } from "@milaboratories/helpers"; @@ -115,11 +115,12 @@ export function evaluateRules( * so it cannot perturb column identity (id-bearing spec overrides would * diverge the visible PTable's column ids from the full table / pframe). * - * Mapping `ColumnFieldStatus` × actual byte-presence → `AnnotationDataStatus`: + * Mapping `ColumnFieldStatus` × the state of the data → `AnnotationDataStatus`: * - `absent` → `"absent"` * - `resolving` → `"computing"` - * - `present` + `hasColumnData()` → `"ready"` + * - `present` + bytes are there → `"ready"` * - `present` + no bytes yet → `"computing"` + * - `present` + the data failed → `"error"` * * Intentionally scoped to visible columns — the probe is meaningful only for * what the user will actually see. @@ -141,7 +142,14 @@ function deriveDataStatus( const field = column.getDataStatus(); if (field === "absent") return "absent"; if (field === "resolving") return "computing"; - return hasColumnData(column, opts) ? "ready" : "computing"; + switch (getColumnDataState(column, opts)) { + case "ready": + return "ready"; + case "pending": + return "computing"; + case "errored": + return "error"; + } } /** Column shape required by label derivation. */