Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/errored-column-data-status.md
Original file line number Diff line number Diff line change
@@ -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.
57 changes: 51 additions & 6 deletions sdk/model/src/columns/__test_helpers__/stub_registry.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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";
Expand All @@ -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;

Expand Down Expand Up @@ -86,6 +99,7 @@ type NormalizedLeafConfig = {
spec?: PObjectSpec;
accessorLocked: boolean;
specHasData: boolean;
data?: StubDataField;
};

function normalizeLeafInput(raw: StubLeafInput): NormalizedLeafConfig {
Expand All @@ -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 {
Expand All @@ -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: <T>() => 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;
Expand Down
44 changes: 43 additions & 1 deletion sdk/model/src/columns/data_column.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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<StubDataField>(["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);
Expand Down
48 changes: 43 additions & 5 deletions sdk/model/src/columns/data_column.ts
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@ export class DataColumnImpl implements DataColumnRecipe<PObjectId> {
getSpec: () => PColumnSpec;
getData: () => ColumnData;
getDataStatus: () => ColumnFieldStatus;
hasDataError: () => boolean;
},
) {}

Expand Down Expand Up @@ -104,6 +105,16 @@ export class DataColumnImpl implements DataColumnRecipe<PObjectId> {
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);
Expand Down Expand Up @@ -145,8 +156,9 @@ export class DataColumnImpl implements DataColumnRecipe<PObjectId> {
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",
});
}

Expand All @@ -167,6 +179,7 @@ export class DataColumnImpl implements DataColumnRecipe<PObjectId> {
getSpec: () => pColumn.spec,
getData: () => pColumn.data,
getDataStatus: () => "present",
hasDataError: () => false,
});
}

Expand Down Expand Up @@ -299,10 +312,35 @@ function getLeafEntryStatus(entry: LeafEntry<TreeNodeAccessor>): ColumnResolutio
return "present";
}

const readDataAccessor = memoizeByEntry(
({ accessor, name }: LeafEntry<TreeNodeAccessor>): 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<TreeNodeAccessor>): 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<TreeNodeAccessor>): undefined | TreeNodeAccessor {
const read = readData(entry);
return read.type === "node" ? read.node : undefined;
}

const readDataStatus = memoizeByEntry(
({ accessor, name }: LeafEntry<TreeNodeAccessor>): ColumnFieldStatus => {
Expand Down
87 changes: 85 additions & 2 deletions sdk/model/src/columns/utils.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 | StubDataField>([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<StubDataField>(["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");
});
});
Loading
Loading