@steelbreeze/pivot

pivot

A minimalist pivot table library for TypeScript/JavaScript. While small (a mere 701 bytes when minified), this library is large in capability, supporting derived and custom dimensions, derived fields for dimensions and calculations, composite dimensions, filtering.

The library also provides a modest set of numerical selectors. Suggestions for additions, or better still contributions, are welcome.

Why create another pivot table library?

There are plenty of pivot table libraries in existence, so why create another one? Well, this is a spin-off from the steelbreeze/landscape project, where instead of aggregating numerical data from the pivot cube, non-numerical data is needed.

It also focuses just on dimension and cube creation, without any layout considerations keeping it small and unopinionated.

n-cubes

The libary allows 1-n dimensions to be passed into the pivot function allowing n-cube (or hypercube) generation.

Installation

NPM

For installation via the node package manager:

npm i @steelbreeze/pivot

Web

For web via a CDN:

import * as pivot from 'https://cdn.skypack.dev/@steelbreeze/pivot';

Documentation

The documentation can be found here, and more discussion in the Wiki.

Example

The following is the result of pivoting publicly available information about the Fulham Football Club men's squad at the end of the 2020/21 season, calculating the average age of players by position and country.

import { dimension, property, pivot, aggregate, average } from '@steelbreeze/pivot';
import { Player, squad } from './fulham';
import { distinct } from './distinct';

// the position dimension we want in a defined order
const positions = ['Goalkeeper', 'Defender', 'Midfielder', 'Forward'];

// the countries dimension we derive from the squad data and order alphabetically
const countries = squad.map(player => player.country).filter(distinct).sort();

// we then create dimensions which also reference a property in the source data 
const x = dimension(positions, property<Player>('position')); // using the built-in dimension generator matching a property
const y = dimension(countries, (country: string) => (player: Player) => player.country === country); // using a user-defined generator

// create the pivot cube from the squad data using position and country for x and y axes
const cube = pivot(squad, y, x);

// find the average age of players by position by country as at 2021-05-23
const result = query(cube, average(age(new Date('2021-05-23'))));

The full example can be found here.

The selection is the average age of the players grouped by position and country:

        Goalke… Defend… Midfie… Forward
Belgium         32
Camero…                 25
Denmark         24
England         25      23.25   23
France  28      27
Gabon                   27
Jamaica         28              28
Nether…         25
Nigeria         24              22
Portug…                         27
Scotla…                 31
Serbia                          26
Slovak… 24
Spain   33
USA             28

The full example code can be found here.

Alternatively, as can be seen in the web example, non-numerical content can also be queried, mapping the source data to an arbitrary selection:

const result = pivot.map(cube, pivot.select(player => `${player.givenName} ${player.familyName}`));

Resulting in this sort of output:

	Goalkeeper	Defender	Midfielder	Forward
Belgium		Denis Odoi
Cameroon			Andre-Frank Zambo Anguissa
Denmark		Joachim Anderson
England		Tosin Abarabioyo, Joe Bryan	Ruben Loftus-Cheek, Harrison Reed, Josh Onomah, Fabio Carvalho	Ademola Lookman
France	Alphonse Areola	Terence Kongolo
Gabon			Mario Lemina
Jamaica		Michael Hector		Bobby De Cordova-Reid
Netherlands		Kenny Tete
Nigeria		Ola Aina		Josh Maja
Portugal				Ivan Cavaleiro
Scotland			Kevin McDonald, Tom Cairney
Serbia				Aleksander Mitrovic
Slovakia	Marek Rodak
Spain	Fabrico Agosto Ramirez
USA		Tim Ream, Antonee Robinson

Data and calculations correct as of: 2021-05-23.