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. */