pivotkit-core reference¶

Four entry points: pivotkit-core (the engine), pivotkit-core/export (XLSX and CSV) and pivotkit-core/link (a view in a link), the only importers of fflate, and pivotkit-core/templates (a list of templates). Every function takes its required inputs first and all optional settings in one options object last. Modules not listed here are internal and may change in any release.

import { encode, normalize, computePivot, toGrid, toEChartsOption } from "pivotkit-core";
import { toXlsx, toCsv, toCsvBytes, toTsv, toJson, rowsToCsv, rowsToCsvBytes, rowsToXlsx } from "pivotkit-core/export";
import { parseTemplates, templatesFromSchema } from "pivotkit-core/templates";
import type { PivotResult, Grid, View, Encoded } from "pivotkit-core";   // TypeScript

Data¶

encode(rows, options?)¶

Turns an array of objects into typed columns: Int32 codes with dictionaries for labels, Float64 for measures. Returns Encoded.

Encoded has length, columns, schema.fields (name, type, and detected when a text column holds only numbers, so a UI can offer inferNumbers or a types override), column(name) (a case-insensitive lookup), timeZone, and issues (column names that collide case-insensitively). Names match case-insensitively; the data's own spelling is kept for display.

fieldItems(data, field, options?)¶

The distinct values of a field (a derived field of options.view too) with label and row count, in the table's label order, blank last: what a filter list shows. Counts are over all rows, before filters. Returns { field, type, items: { value, label, count }[], truncated }, or null for an unknown field. Options: view, locale, labels, limits.

suggestDateUnit(data, field)¶

The date grouping a date field gets on an axis, from the span of its values: up to 62 days "day", up to two years "yearMonth", up to six years "yearQuarter", longer "year"; null for fewer than two days or a field that is not a date.

fieldDefaultsFromSchema(schema, options?)¶

What a JSON Schema or an OpenAPI document says about each field of a row, in the shape of pivotkit-react's fieldDefaults: title becomes label, description stays description, externalDocs.url becomes href (https only), type integer or number and format date or date-time become type, enum becomes order. schema is the row's schema (an object with properties, or an array of rows), or an OpenAPI 3 / Swagger 2 document with options.schema, the name of a schema in components.schemas (or definitions) or a local $ref ("#/components/schemas/Release"). Only references inside the document are followed, allOf parts are merged, a nullable anyOf/oneOf is read as its one schema, each $ref target is read once. Nothing is fetched or run; texts are plain (no control, bidi or zero-width characters) and capped (label 120, description 1,000 characters, 1,000 fields and enum entries, 32 levels of $ref, 20,000 schema objects). A property with nothing to say is left out. Returns { defaults, issues }: defaults is the fieldDefaults object, issues ({ path, message }[]) what could not be read (a reference outside the document or not local, a cycle, a cap reached), as normalize() reports a view's. Throws INVALID_ARGUMENT for input that is no schema at all. See Field descriptions and names.

Views¶

A view is the report as JSON; Views and saved views describes its keys.

View files¶

A view with its name, the data it was made for and the fields it uses, as one JSON document: what pivotkit-react shares as JSON, as a file and (in its link profile) as a link. The format, its rules and its JSON Schema are in View file format.

Pivot¶

computePivot(data, view, options?)¶

Builds the row and column key trees with subtotals and totals. The view is normalized first, so raw user input is fine. Options: locale, limits (work is computed before the aggregation starts; groups and pivotCells are counted while the key trees and the cells grow; over one, LIMIT_EXCEEDED).

The PivotResult has, among others:

Drill-down¶

Output¶

toGrid(result, options?)¶

Header and body rows with merges, totals, formatted text and raw values, toggles for collapsed groups and conditional-formatting ratios. Options: locale, labels, limits (cells caps the grid's size, counted before anything is allocated).

A GridCell has text (formatted), value (raw), kind ("corner", "colHeader", "rowHeader", "value"), total (0 none, 1 subtotal, 2 grand total), and where they apply rowSpan, colSpan, valueType, format, field, rowPath, colPath, valueIndex, toggle ({ axis, path, collapsed }), style ({ scale, bar, color } for colour scales and data bars) and, on value cells, hasRows (false: no source row behind the cell, nothing to drill into). With one value, its name is a single header cell over all of its columns, as in Excel.

toSeries(result, options?) and toEChartsOption(result, options?)¶

Chart data, and a plain Apache ECharts option for bar, stacked bar, line, area, pie, donut and heatmap. ECharts itself is not imported.

chart.type "auto" (the view's default) is drawn as autoChartType(view, data) says: "line" when a date or a grouping of one along the time line (not weekday, hour, month of year) is on Rows, else "bar". A pie's share is written as the locale writes a percentage; a heatmap's colour scale (visualMap.formatter) in the value's number format.

autoChartType(view, data)¶

What the chart type "auto" stands for, for a normalized view and its data: "line" when a field on Rows is a date or a grouping of one along the time line (a repeating one such as weekday is categories), else "bar". A date on Columns alone gives "bar"; a UI that wants lines there swaps rows and columns for the chart (pivotkit-react does).

toSeries gives categories (the whole path of each category, "Asia / Japan"), categoryLevels (its label per level, ["Asia", "Japan"]), categoryPaths, series and totals. The view's display settings are part of the option: a title, the legend where chart.legend puts it (and room for it), value labels (label of the series; for a pie or a donut outside or, with chart.labelPosition "inside", on the slices without a label line), smooth lines, and with chart.groupLabels ("auto" or "on"; the UI hides "auto" ones in a small chart) and two or more row fields a second category axis with the outer field's items, once per group at its middle, with a separator tick where a group starts (xAxis or yAxis is then a list of two). Where to write the category labels (chart.axisLabels) depends on the chart's size, so the UI decides it (pivotkit-react's categoryLabelLayout).

Links: pivotkit-core/link¶

A view as a short text for a link and back; a separate entry point, so a page that never shares does not load fflate. The format is pivotkit's share format: 1. and the JSON compressed with raw DEFLATE, in base64url. pivotkit-react encodes the link profile of a view file (toViewFile(view, meta, { link: true })); decodeViewLink gives back whatever object was encoded, which fromViewFile reads (a bare view too). See Sharing.

Templates: pivotkit-core/templates¶

A list of named views (shared views, a person's own) and the templates an OpenAPI document or a JSON Schema carries in the extension x-pivotkit-views (pivotkit's own convention, not part of either standard). A separate entry point: a UI loads it only where it reads templates (pivotkit-react with its menus). See Templates and shared views.

Export: pivotkit-core/export¶

What the files contain, and where Excel's number formats cannot follow the grid, is in Security and Values.

Helpers¶

Types¶

View, ValueSpec, ValueRef, FilterSpec, DerivedSpec, SortSpec, Issue, IssueParams, Encoded, Column, ColumnType, SchemaField, PivotResult, PivotNode, Grid, GridCell, FieldItem, ChartTheme, Formatter, Limits, Labels, SchemaFieldDefaults, PivotkitErrorCode, ViewFileMeta, ViewFileRead, ViewFileCompatibility and ViewFileSource, from pivotkit-core.

Performance¶

Benchmark of the engine with 100,000 rows (median of 5 runs, Node 26 on one Mac with Apple silicon; approximate, other machines differ; npm run bench -w pivotkit-core measures your own):