std/sheet

Import from @norbital-ai/std/sheet

std/sheet (§3.7, §5.4, D15): the one Cell[][] ⇄ rows codec. The host reads file references through ctx.files.table (a string-cell table) or ctx.files.sheet (worksheets with typed cells); this module only maps cells to typed rows and back. The first row is the header; a header matches a column name, a date period is two columns <name>.from / <name>.to (inclusive, blank to = open), and an unknown header is an error.

Cell type

type Cell = string | number | boolean | null;

One spreadsheet cell's value.

Source: packages/std/src/sheet.ts:10

ColumnSpec type

type ColumnSpec = 'text' | 'int' | 'decimal' | 'date' | 'time' | 'bool' | {
    readonly enum: readonly string[];
} | {
    readonly period: 'date';
} | {
    readonly optional: ColumnSpec;
};

How a sheet column decodes to a typed value: a scalar kind, an enum, or a date period over two columns (<name>.from, <name>.to).

Source: packages/std/src/sheet.ts:14

SheetStyle type

type SheetStyle = {
    readonly bold?: readonly number[];
    readonly merge?: readonly (readonly [row: number, col: number, toRow: number, toCol: number])[];
    readonly band?: {
        readonly fill: string;
        readonly every?: number;
    };
    readonly numFmt?: {
        readonly [column: string]: string;
    };
};

Presentation hints the host applies when it writes the file; rows and columns are 0-based cell indexes.

Members

Name	Type	Description
bold?	readonly number[]
merge?	readonly (readonly [row: number, col: number, toRow: number, toCol: number])[]
band?	{ readonly fill: string; readonly every?: number; }
numFmt?	{ readonly [column: string]: string; }

Source: packages/std/src/sheet.ts:25

columns function

function columns<const C extends Spec>(c: C): C

Declares a sheet's columns; the value is the spec itself, typed for decode's rows.

Parameters

Name	Type	Description
c	C

Source: packages/std/src/sheet.ts:54

decode function

function decode<const C extends Spec>(cells: readonly (readonly Cell[])[], cols: C): { rows: RowOf<C>[]; errors: SheetError[]; }

Rows from cells; every bad cell, missing column and unknown header is an error, and no row with an error is returned.

Parameters

Name	Type	Description
cells	readonly (readonly Cell[])[]
cols	C

Source: packages/std/src/sheet.ts:131

encode function

function encode<const C extends Spec>(rows: readonly NoInfer<RowOf<C>>[], cols: C): Cell[][]

Cells from rows: the header, then one line per row (a period as its two cells, a decimal as its exact text).

Parameters

Name	Type	Description
rows	readonly NoInfer<RowOf<C>>[]
cols	C

Source: packages/std/src/sheet.ts:189