@dou-ui/pivot 0.0.0-stage → 0.1.0-alpha.0

package/dist/types/engine/compute.d.ts

@@ -0,0 +1,173 @@
+import { type PivotAggregator } from './aggregate';
+import { type PivotFormula } from './formula';
+import { IntIndex, type PivotIndexPacket } from './hash';
+import { type PivotResolvedShow } from './show';
+export type { PivotResolvedShow };
+import type { PivotResolvedField, PivotSource } from './source';
+import { PivotTree, type PivotTreePacket } from './tree';
+import type { PivotConfig, PivotFormat, PivotMark, PivotShow, PivotShowAs, PivotValueSort } from './types';
+/** A value of the config with everything filled in. */
+export interface PivotResolvedValue {
+    field: PivotResolvedField<unknown> | null;
+    aggregate: string;
+    /** The custom aggregator, for names that are not built in. */
+    aggregator?: PivotAggregator;
+    /** As given; the component works out a header when there is none. */
+    label?: string;
+    format?: PivotFormat;
+    /** Whether the value is a count, written without decimals. */
+    integer: boolean;
+    /** Whether it stands in for an empty `values` (a count of records). */
+    implicit?: boolean;
+    /** A calculated value's formula, as written (`aggregate` is then `'formula'`). */
+    formula?: string;
+    /** How it is shown, as given (the axis is worked out by the result). */
+    show?: PivotShow;
+    mark?: Required<PivotMark>;
+}
+/** The ways of showing a value that write it as a percentage. */
+export declare const PERCENT_SHOWS: ReadonlySet<PivotShowAs>;
+/** A `show` as an object. */
+export declare const showOf: (show: PivotShowAs | PivotShow | undefined) => PivotShow | undefined;
+/** A `mark` with its tone filled in. */
+export declare const markOf: (mark: "bar" | "scale" | PivotMark | undefined) => Required<PivotMark> | undefined;
+/**
+ * Reads a calculated value's formula and finds its fields by name (or by
+ * label). Throws a `PivotFormulaError` when it is not well formed, names a
+ * field that is not there, or sums up one that is not a number.
+ */
+export declare function checkPivotFormula<Row>(source: PivotSource<Row>, text: string): PivotFormula;
+export interface PivotComputeOptions {
+    /** Aggregators by name, beside the built-in ones. */
+    aggregators?: Readonly<Record<string, PivotAggregator>>;
+}
+/** The fields of the config resolved against a source, without reading any records. */
+export declare function resolveConfig(source: PivotSource<unknown>, config: PivotConfig, options?: PivotComputeOptions): {
+    rows: {
+        field: PivotResolvedField<unknown>;
+        sort: "asc" | "desc";
+        subtotal: boolean;
+        by: import("./group").PivotGroupBy | undefined;
+    }[];
+    columns: {
+        field: PivotResolvedField<unknown>;
+        sort: "asc" | "desc";
+        subtotal: boolean;
+        by: import("./group").PivotGroupBy | undefined;
+    }[];
+    values: PivotResolvedValue[];
+    formulas: (PivotFormula | null)[];
+};
+/**
+ * Groups the records by the config's row and column fields and sums up
+ * its values for every group, subtotal and total.
+ *
+ * Each record is placed once, in its innermost row group and innermost
+ * column group; the values are summed per such pair, and every subtotal
+ * is then merged from those pairs, never from the records again.
+ */
+export declare function computePivot<Row>(source: PivotSource<Row>, config: PivotConfig, options?: PivotComputeOptions): PivotResult;
+interface PivotResultInit {
+    rows: PivotTree;
+    columns: PivotTree;
+    values: PivotResolvedValue[];
+    matched: number;
+    cells: IntIndex;
+    width: number;
+    data: Float64Array[];
+    slotOf: Int32Array;
+    leafRow: Int32Array;
+    leafCol: Int32Array;
+}
+/**
+ * A `PivotResult` as data: typed arrays a worker moves to the page without
+ * copying, or plain arrays from JSON (a result summed up on a server).
+ */
+export interface PivotPacket {
+    rows: PivotTreePacket;
+    columns: PivotTreePacket;
+    values: {
+        field: string | null;
+        aggregate: string;
+        integer: boolean;
+        implicit?: boolean;
+        label?: string;
+        formula?: string;
+        show?: PivotShow;
+        mark?: Required<PivotMark>;
+    }[];
+    matched: number;
+    cells: PivotIndexPacket;
+    width: number;
+    data: ArrayLike<number>[];
+    slotOf: ArrayLike<number>;
+    leafRow: ArrayLike<number>;
+    leafCol: ArrayLike<number>;
+}
+/** The groups on both axes and every cell's values. */
+export declare class PivotResult {
+    readonly rows: PivotTree;
+    readonly columns: PivotTree;
+    readonly values: readonly PivotResolvedValue[];
+    /** How many records passed the filters. */
+    readonly matched: number;
+    private cells;
+    private width;
+    private data;
+    /** Each record's innermost cell, -1 when filtered out; and each such cell's groups. */
+    private slotOf;
+    private leafRow;
+    private leafCol;
+    constructor(init: PivotResultInit);
+    /**
+     * The result as data, to send from a worker or a server. With `plain`,
+     * plain arrays for `JSON.stringify` (typed arrays do not survive it);
+     * empty cells go as `null`.
+     */
+    pack({ plain }?: {
+        plain?: boolean;
+    }): PivotPacket;
+    private packTyped;
+    /** The typed arrays in a packet, to move them instead of copying (`postMessage`'s transfer list). */
+    static transferables(packet: PivotPacket): ArrayBuffer[];
+    /**
+     * A result made from `pack()`'s output. Fields are described by
+     * `source` (no record is read), formats come from `config`.
+     */
+    static unpack<Row>(packet: PivotPacket, source: PivotSource<Row>, config?: PivotConfig): PivotResult;
+    private showing;
+    private ranges;
+    private shownBy;
+    /**
+     * How a value is shown, its `show` with the axis worked out; null when as
+     * it is. `show` stands in for the value's own (`null` for none).
+     */
+    show(valueIndex?: number, show?: PivotShow | null): PivotResolvedShow | null;
+    /**
+     * The value as it is shown: a share, a difference, a running total or a
+     * rank when the value has a `show` (or one is given), the summed-up value
+     * otherwise. Nothing is summed up again.
+     */
+    shown(row: number, column: number, valueIndex?: number, show?: PivotShow | null): number;
+    /**
+     * The smallest and largest shown values of the innermost cells (those
+     * under no subtotal or total), which marks are drawn against.
+     */
+    range(valueIndex?: number, show?: PivotShow | null): {
+        min: number;
+        max: number;
+    };
+    /**
+     * The value at `valueIndex` (its place in `values`) of a row group and a
+     * column group; `NaN` when no record falls in both. The trees' `total`
+     * is the grand total.
+     */
+    get(row: number, column: number, valueIndex?: number): number;
+    /** The indexes of the records in a row group and a column group, for showing the details. */
+    indices(row: number, column: number): number[];
+    /**
+     * The children of every row group, reordered by a column's values (or as
+     * they are when `sort` is empty). Nothing is summed up again.
+     */
+    rowOrder(sort: PivotValueSort | null | undefined): Int32Array;
+}

package/dist/types/engine/engine.d.ts

@@ -0,0 +1,29 @@
+import { type PivotAggregator } from './aggregate';
+import { type PivotResult } from './compute';
+import type { PivotConfig } from './types';
+import type { PivotSource } from './source';
+export interface PivotComputeRequest {
+    /** Aggregators by name, beside the built-in ones. */
+    aggregators?: Readonly<Record<string, PivotAggregator>>;
+    /** Aborted when a newer config makes this one stale. */
+    signal?: AbortSignal;
+}
+/**
+ * Sums up the records somewhere else than in the page: in a worker
+ * (`createPivotWorker`), or on a server. `DouPivot` asks it for a result
+ * whenever the fields to sum up change, and shows only the newest one.
+ */
+export interface PivotEngine {
+    compute<Row>(source: PivotSource<Row>, config: PivotConfig, request?: PivotComputeRequest): Promise<PivotResult>;
+    /** Lets go of what it holds (a worker, a connection) when the table goes away. */
+    dispose?(): void;
+}
+/**
+ * The fields a config reads, and how: grouped (`dimensions`: on an axis,
+ * filtered, counted) or as numbers (`measures`: summed and the like).
+ * No record is read.
+ */
+export declare function neededColumns<Row>(source: PivotSource<Row>, config: PivotConfig, aggregators?: Readonly<Record<string, PivotAggregator>>): {
+    dimensions: string[];
+    measures: string[];
+};

package/dist/types/engine/formula.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Calculated values: a small expression language over the fields, read
+ * without `eval`. `profit / amount` divides the sum of `profit` by the sum
+ * of `amount` in each cell, so totals are ratios of totals, not sums of ratios.
+ *
+ * - numbers: `12`, `0.5`, `1e3`
+ * - fields: a name (`amount`, `销售额`), or any name in brackets (`[unit price]`)
+ * - `+ - * /`, parentheses and a leading minus
+ * - `sum(f)`, `avg(f)`, `min(f)`, `max(f)`, `count(f)` (records where f is not empty) and `count()`
+ *
+ * A bare field name stands for `sum(name)`. Dividing by zero leaves the cell empty.
+ */
+/** The ways a formula can sum up a field. */
+export type PivotFormulaAggregate = 'sum' | 'avg' | 'min' | 'max' | 'count';
+/** A field a formula reads, and how. `field` is null for `count()`. */
+export interface PivotFormulaTerm {
+    aggregate: PivotFormulaAggregate;
+    field: string | null;
+}
+/** A formula read into its terms and a function of their values. */
+export interface PivotFormula {
+    source: string;
+    /** Each distinct field-and-aggregate the formula reads, in the order of `evaluate`'s input. */
+    terms: PivotFormulaTerm[];
+    /** The formula's value from its terms' values; `NaN` for an empty cell. */
+    evaluate(values: ArrayLike<number>): number;
+}
+/** Why a formula could not be read. */
+export type PivotFormulaErrorCode = 'empty' | 'incomplete' | 'unknownChar' | 'unexpected' | 'expected' | 'unclosedBracket' | 'emptyName' | 'unknownFunction' | 'needsField' | 'needsName' | 'unknownField' | 'notNumber';
+/**
+ * Why a formula could not be read, and where: `at` is a character offset,
+ * `detail` the text the message is about. `code` lets a page word it its own way.
+ */
+export declare class PivotFormulaError extends Error {
+    readonly code: PivotFormulaErrorCode;
+    readonly at: number;
+    readonly detail: string;
+    constructor(code: PivotFormulaErrorCode, at: number, detail?: string);
+}
+/**
+ * Reads a formula. Throws a `PivotFormulaError` when it is not well formed.
+ * Field names are not checked here (see `computePivot`).
+ */
+export declare function parsePivotFormula(text: string): PivotFormula;

package/dist/types/engine/group.d.ts

@@ -0,0 +1,34 @@
+/**
+ * How a field's values are put in groups: dates by a period, numbers in
+ * ranges of `step` (starting at `start`, 0 by default).
+ */
+export type PivotGroupBy = 'year' | 'quarter' | 'month' | 'week' | 'day' | {
+    step: number;
+    start?: number;
+};
+/** The periods a date can be grouped by. */
+export declare const DATE_PERIODS: readonly ["year", "quarter", "month", "week", "day"];
+export type PivotDatePeriod = (typeof DATE_PERIODS)[number];
+/** A name for a grouping, to cache the grouped field under. */
+export declare function groupKey(by: PivotGroupBy | undefined): string;
+/**
+ * A date out of a value: a `Date`, a time in ms, or text such as
+ * `'2026-03-15'` (read in local time, like the other parts of a day).
+ */
+export declare function toDate(value: unknown): Date | null;
+/** The ISO week a day is in, and the year that week belongs to. */
+export declare function isoWeek(date: Date): [year: number, week: number];
+/**
+ * The group a value falls in: plain data that sorts in order and can be
+ * saved in the config (filters, collapsed groups): a year is a number
+ * (`2026`); a quarter, month, week or day is text (`'2026-Q1'`,
+ * `'2026-03'`, `'2026-W12'`, `'2026-03-15'`); a range is its lowest
+ * number. `null` when the value has no group (empty, or not a date / number).
+ */
+export declare function bucketer(by: PivotGroupBy): (value: unknown) => number | string | null;
+/** The parts of a period's group, read back from its text. */
+export declare function readBucket(by: PivotDatePeriod, bucket: unknown): {
+    year: number;
+    part: number;
+    date: Date;
+} | null;

package/dist/types/engine/hash.d.ts

@@ -0,0 +1,36 @@
+/**
+ * A table from whole numbers (0 to 2^53) to the order they were first seen
+ * in: open addressing over typed arrays, so millions of lookups allocate
+ * nothing and never touch a `Map`.
+ */
+export declare class IntIndex {
+    /** The keys by slot; `-1` marks a free slot. */
+    private table;
+    /** What each slot's key maps to. */
+    private ids;
+    private mask;
+    /** The keys in the order they were added. */
+    keys: Float64Array;
+    size: number;
+    constructor(expected?: number);
+    /** The id of `key`, or -1. */
+    get(key: number): number;
+    /** The id of `key`, adding it with the next id when it is new. */
+    add(key: number): number;
+    /** Its arrays, to send to another thread (moved, not copied) or save. */
+    pack(): PivotIndexPacket;
+    /** An index made from `pack()`'s output; plain arrays (from JSON) work too. */
+    static unpack(packet: PivotIndexPacket): IntIndex;
+    private grow;
+}
+type TypedArrayOf = Float64ArrayConstructor | Int32ArrayConstructor | Uint32ArrayConstructor | Uint8ArrayConstructor;
+/** The array as it is when it is already of that type (moved from a worker), else a typed copy (from JSON). */
+export declare function typed<T extends TypedArrayOf>(Type: T, array: ArrayLike<number>): InstanceType<T>;
+/** An `IntIndex` as data. */
+export interface PivotIndexPacket {
+    table: ArrayLike<number>;
+    ids: ArrayLike<number>;
+    keys: ArrayLike<number>;
+    size: number;
+}
+export {};

package/dist/types/engine/index.d.ts

@@ -0,0 +1,15 @@
+export { checkPivotFormula, computePivot, PERCENT_SHOWS, PivotResult, resolveConfig, } from './compute';
+export type { PivotComputeOptions, PivotPacket, PivotResolvedShow, PivotResolvedValue, } from './compute';
+export { parsePivotFormula, PivotFormulaError } from './formula';
+export type { PivotFormula, PivotFormulaAggregate, PivotFormulaErrorCode, PivotFormulaTerm, } from './formula';
+export { neededColumns } from './engine';
+export type { PivotComputeRequest, PivotEngine } from './engine';
+export { defineAggregator } from './aggregate';
+export type { PivotAggregator } from './aggregate';
+export { compareValues, isColumns, isEmpty, PivotSource, toNumber } from './source';
+export type { PivotColumns, PivotData, PivotDimensionColumn, PivotEncodedColumn, PivotResolvedField, PivotSourceOptions, } from './source';
+export { PivotTree } from './tree';
+export type { PivotLevel } from './tree';
+export type * from './types';
+export { bucketer, DATE_PERIODS, isoWeek, readBucket, toDate } from './group';
+export type { PivotDatePeriod, PivotGroupBy } from './group';

package/dist/types/engine/show.d.ts

@@ -0,0 +1,27 @@
+import type { PivotTree } from './tree';
+import type { PivotShow, PivotShowAs } from './types';
+/** A way of showing a value with its axis worked out. */
+export interface PivotResolvedShow {
+    as: PivotShowAs;
+    axis: 'rows' | 'columns';
+}
+/** The axis a way of showing works along: as given, or the default when that axis has fields. */
+export declare function resolveShow(show: PivotShow, rows: PivotTree, columns: PivotTree): PivotResolvedShow;
+/**
+ * Works out a value as it is shown, from the summed-up values (`get`).
+ * Groups come in their label order, whatever order the rows are shown in.
+ */
+export declare class PivotShown {
+    readonly show: PivotResolvedShow;
+    private rows;
+    private columns;
+    private get;
+    private running;
+    private sorted;
+    constructor(show: PivotResolvedShow, rows: PivotTree, columns: PivotTree, get: (row: number, column: number) => number);
+    value(row: number, column: number): number;
+    /** The group before this one on the axis, or null for the first and for totals. */
+    private previous;
+    private runningTotal;
+    private rank;
+}

package/dist/types/engine/source.d.ts

@@ -0,0 +1,108 @@
+import { type PivotGroupBy } from './group';
+import type { PivotField, PivotFieldType } from './types';
+/** A field's groups: each record's group number, and each group's value. */
+export interface PivotDimensionColumn {
+    /** Each record's group. */
+    codes: Uint32Array;
+    /** Each group's value; `null` for the empty group. */
+    labels: unknown[];
+    /** The empty group's number, or -1 when every record has a value. */
+    empty: number;
+    /** Each group's place in the field's natural order (its `order`, then sorted, empty last). */
+    rank: Uint32Array;
+    /** The group of `value`, or -1 when no record has it. */
+    find: (value: unknown) => number;
+}
+/** A field with its type worked out. */
+export interface PivotResolvedField<Row = unknown> extends PivotField<Row> {
+    label: string;
+    type: PivotFieldType;
+}
+export interface PivotSourceOptions<Row> {
+    fields?: readonly PivotField<Row>[];
+    /** For sorting group labels; the runtime's locale when left out. */
+    locale?: string;
+}
+/**
+ * Records given column by column: each field's values in one array (or
+ * typed array), all of the same length. A million records take far less
+ * memory this way than as a million objects.
+ */
+export type PivotColumns = Readonly<Record<string, ArrayLike<unknown>>>;
+/** The records: an array of objects, or their columns. */
+export type PivotData<Row = Record<string, unknown>> = readonly Row[] | PivotColumns;
+/** A field's groups before they are put in order: what a worker is sent. */
+export interface PivotEncodedColumn {
+    codes: Uint32Array;
+    labels: unknown[];
+    empty: number;
+}
+export declare const isColumns: (data: unknown) => data is PivotColumns;
+/**
+ * The records, read field by field into typed arrays the first time each
+ * field is used, and kept until the records change.
+ */
+export declare class PivotSource<Row = Record<string, unknown>> {
+    /** The records as given: objects, or columns. */
+    readonly data: PivotData<Row>;
+    readonly length: number;
+    readonly fields: Map<string, PivotResolvedField<Row>>;
+    readonly locale: string | undefined;
+    private collator;
+    private dimensions;
+    private measures;
+    /** Groups read elsewhere (in the page, for a worker), waiting to be put in order. */
+    private given;
+    constructor(data: PivotData<Row>, options?: PivotSourceOptions<Row> & {
+        length?: number;
+    });
+    /** The record at `index`: the object given, or one made from the columns. */
+    record(index: number): Row;
+    /** How to read a field from record `i`. */
+    private reader;
+    /** Describes a field (or describes it again), as `fields` would have. */
+    define(field: PivotField<Row>): void;
+    /** Hands over groups read elsewhere, such as in the page for a worker. */
+    provide(name: string, column: PivotEncodedColumn): void;
+    /** Hands over a field's numbers read elsewhere. */
+    provideMeasure(name: string, values: Float64Array): void;
+    /** The field called `name`; one is made up for keys the fields do not list. */
+    field(name: string): PivotResolvedField<Row>;
+    /** The field's values, one per record. */
+    values(name: string): unknown[];
+    /**
+     * The field grouped by value, or by `by`: dates by a period, numbers in
+     * ranges. A grouping is worked out from the field's groups, not from the
+     * records, so it costs one pass over the group numbers.
+     */
+    dimension(name: string, by?: PivotGroupBy): PivotDimensionColumn;
+    private group;
+    /** The field as numbers, `NaN` where a record has none. */
+    measure(name: string): Float64Array;
+    /**
+     * Reads a field's numbers a slice at a time, for reading a large field
+     * without holding up the page. The array is new: the source keeps none.
+     */
+    measureSteps(name: string, copy?: boolean): Generator<void, Float64Array>;
+    private resolve;
+    private guess;
+    private encode;
+    /**
+     * Reads a field's groups a slice at a time, for reading a large field
+     * without holding up the page: each record's group number and each
+     * group's value, not yet in order.
+     */
+    encodeSteps(name: string): Generator<void, PivotEncodedColumn>;
+    /** Each group's place: the field's `order` first, then by value, the empty group last. */
+    private rank;
+}
+/** Empty: `null`, `undefined`, `''`, `NaN` and invalid dates all go in the empty group. */
+export declare const isEmpty: (value: unknown) => boolean;
+/** Natural order: numbers and dates by size, text by the locale (digits as numbers), empty last. */
+export declare function compareValues(a: unknown, b: unknown, collator: Intl.Collator): number;
+/** A value as a number: numbers, dates and numeric text; `NaN` for anything else. */
+export declare function toNumber(value: unknown): number;
+/** Runs reading in slices to the end, at once. */
+export declare function run<T>(steps: Generator<void, T>): T;
+/** Finds a group by its value; dates by their time. */
+export declare function finder(labels: readonly unknown[], empty: number): (value: unknown) => number;

package/dist/types/engine/tree.d.ts

@@ -0,0 +1,87 @@
+import type { PivotGroupBy } from './group';
+import { IntIndex, type PivotIndexPacket } from './hash';
+import { type PivotDimensionColumn, type PivotResolvedField } from './source';
+/** A field on an axis, with what the config asked of it. */
+export interface PivotLevel {
+    field: PivotResolvedField<unknown>;
+    column: PivotDimensionColumn;
+    sort: 'asc' | 'desc';
+    subtotal: boolean;
+    /** How the field's values are grouped, when not by each value. */
+    by?: PivotGroupBy;
+}
+/**
+ * The groups along one axis. Node 0 is the whole axis (the grand total);
+ * a node at depth `d` is a group of the `d`-th field inside its parent.
+ * Children are kept in label order, as compressed lists: the children of
+ * `node` are `children[childStart[node]]` up to `children[childStart[node + 1]]`.
+ */
+export declare class PivotTree {
+    /** The root: the grand total, as a row or column group. */
+    readonly total = 0;
+    readonly size: number;
+    readonly levels: readonly PivotLevel[];
+    readonly parent: Int32Array;
+    readonly depth: Uint8Array;
+    /** The group number within its field (`-1` for the root). */
+    readonly code: Int32Array;
+    readonly childStart: Int32Array;
+    readonly children: Int32Array;
+    /** Where each node starts and ends in a walk of the tree, to tell descendants apart. */
+    readonly enter: Int32Array;
+    readonly exit: Int32Array;
+    private index;
+    private stride;
+    constructor(builder: PivotTreeBuilder, levels: readonly PivotLevel[]);
+    /** The tree as data: typed arrays to move to another thread, or to write as JSON. */
+    pack(): PivotTreePacket;
+    /** A tree made from `pack()`'s output, with fields described by `field`. */
+    static unpack(packet: PivotTreePacket, field: (name: string) => PivotResolvedField<unknown>): PivotTree;
+    /** The node's own value (its group label); `undefined` for the root. */
+    label(node: number): unknown;
+    /** The labels from the outermost group down to `node`. */
+    path(node: number): unknown[];
+    /** The node with these labels, or -1. */
+    find(path: readonly unknown[]): number;
+    /** Whether `node` has groups inside it. */
+    isGroup(node: number): boolean;
+    /** Whether `node` is `ancestor` or inside it. */
+    within(node: number, ancestor: number): boolean;
+    private walk;
+}
+/** A `PivotTree` as data. */
+export interface PivotTreePacket {
+    size: number;
+    stride: number;
+    parent: ArrayLike<number>;
+    depth: ArrayLike<number>;
+    code: ArrayLike<number>;
+    childStart: ArrayLike<number>;
+    children: ArrayLike<number>;
+    enter: ArrayLike<number>;
+    exit: ArrayLike<number>;
+    index: PivotIndexPacket;
+    levels: {
+        field: string;
+        sort: 'asc' | 'desc';
+        subtotal: boolean;
+        by?: PivotGroupBy;
+        labels: unknown[];
+        empty: number;
+        rank: ArrayLike<number>;
+    }[];
+}
+/** Grows a tree one record at a time: each record walks down its groups. */
+export declare class PivotTreeBuilder {
+    readonly stride: number;
+    parent: Int32Array<ArrayBuffer>;
+    depth: Uint8Array<ArrayBuffer>;
+    code: Int32Array<ArrayBuffer>;
+    size: number;
+    readonly index: IntIndex;
+    /** `stride` is more than any group number, so (parent, group) makes a unique key. */
+    constructor(stride: number);
+    /** The child of `node` for group `code`, made when new. */
+    child(node: number, code: number): number;
+    private grow;
+}