@teakit/sheet

sum

Sums a sheet, optionally grouped by rows or cols, skipping "-" and undefined.

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

Sheet.sum({ "2024": [1, 2, 3], "2025": [4] }); // 10  (by: "all" default)
Sheet.sum({ "2024": [1, "-", 3, undefined] }); // 4   ("-"/undefined skipped)

Sheet.sum({ "2024": [1, 2], "2025": [3, 4] }, { by: "rows" });
// { "2024": [3], "2025": [7] }

Sheet.sum({ "2024": [1, 2], "2025": [3, 4] }, { by: "cols" });
// [4, 6]

// An empty bucket is "-".
Sheet.sum({ a: ["-", undefined] }); // "-"

// Plug in a custom numeric type via `using` (receives only valid values).
Sheet.sum(sheet, { using: (values) => Arith.sum(...values) });

API Reference

Signature

Sheet.sum<TCell, TKey extends string, TBy extends SheetAggregateBy>(
  sheet: Sheet<TCell, TKey>,
  options?: SheetAggregateOptions<TBy, SheetValueOf<TCell>, TResult>,
): SheetAggregateResult<TKey, TBy, TResult>;

Parameters

ParameterTypeRequiredNotes
options.by"all" | "rows" | "cols"NoDefaults to "all".
options.using(values) => TResultNoReceives only filtered valid values, no context. Defaults to numeric sum.

Returns

  • by: "all" → a single value (or "-").
  • by: "rows" → a sheet of length-1 rows, keys ascending.
  • by: "cols" → an array, one value per column.

Empty buckets are "-" and do not call using.

Throws

  • SHEET_INVALID_AGGREGATE_OPTIONS — invalid by or non-function using.

Agent Contract

FieldValue
Kindstatic aggregation
Canonical namesum
AliasesNone (no sumRows/sumCols/sumSheet)
Mutates inputsNo
ReturnsSheetAggregateResult<TKey, TBy, TResult>

Agent Notes

  • Express direction with { by: "rows" | "cols" }, never a method-name alias.
  • The built-in default handles number; for Arith/Decimal pass using and keep summation semantics.
  • See also mean and median.