@teakit/sheet

merge

Merges several sheets with a resolver, over the union of their keys.

import { Sheet } from "@teakit/sheet";

// Union keys (ascending), max row length, missing -> undefined.
Sheet.merge([{ a: [1, 2] }, { a: [10], b: [20] }], (values) => values);
// { a: [[1, 10], [2, undefined]], b: [[undefined, 20]] }

// "-" is passed to the resolver verbatim (not skipped).
const valueOrZero = (v: unknown): number => (typeof v === "number" ? v : 0);
Sheet.merge(
  [{ "2024": [10, 20] }, { "2024": [1] }, { "2024": ["-", 5] }],
  (values) => values.reduce((sum, v) => sum + valueOrZero(v), 0),
);
// { "2024": [11, 25] }

API Reference

Signature

Sheet.merge<TSheets extends readonly [Sheet, ...Sheet[]], U>(
  sheets: TSheets,
  resolver: SheetMergeResolver<TSheets, U>,
): Sheet<U, SheetUnionKeys<TSheets>>;
// resolver: (values, { key, rowIndex, colIndex }) => U

Parameters

ParameterTypeRequiredNotes
sheets[Sheet, ...Sheet[]]YesNon-empty array.
resolver(values, context) => UYesvalues[i] is each sheet's cell or undefined; context is { key, rowIndex, colIndex }.

Returns

A sheet keyed by the union of input keys (ascending). Each key's row length is the max across inputs; a sheet missing a key or column contributes undefined.

Throws

  • SHEET_INVALID_MERGE_INPUT — non-array / empty sheets, or a non-function resolver.

Agent Contract

FieldValue
Kindstatic combinator
Canonical namemerge
AliasesNone
Mutates inputsNo
ReturnsSheet<U, SheetUnionKeys<TSheets>>

Agent Notes

  • A cell value of "-" is passed to the resolver as "-"; handle it explicitly.
  • Missing key/column is undefined, distinct from a present "-".
  • To pair values into tuples instead of resolving, use zip.