@leanchuck/core

A generic, configurable 80/20 (Pareto) analytics engine. Point it at any dataset, map your fields to an X / Y comparison and a value to rank by, and it classifies every data point into quads and quartiles — the same methodology used for customer × product analysis, generalized for any two dimensions.

• Generic — works with any record shape via field-name or function accessors.
• Configurable — the Pareto split defaults to an exact 0.8, with an optional buffer for "the 80% plus one more" style rules.
• Tree-shakeable — pure ESM with sideEffects: false; import only what you use, either from the root or from focused subpaths.
• Dual module format — ships ESM + CommonJS with full TypeScript types.
• Tiny & dependency-free — no runtime dependencies.

Installation

npm install @leanchuck/core

Quick start

import { analyze } from '@leanchuck/core';

const invoices = [
	{ customer: 'Acme', product: 'Widget', revenue: 500, cost: 300 },
	{ customer: 'Acme', product: 'Gadget', revenue: 100, cost: 80 },
	{ customer: 'Globex', product: 'Widget', revenue: 250, cost: 150 },
	// ...
];

const result = analyze(invoices, {
	x: 'customer', // the X dimension
	y: 'product', // the Y dimension
	value: 'revenue', // what to rank by gmail
	metrics: { cost: 'cost' }, // extra sums to carry along
	pareto: { threshold: 0.8 }, // exact 80/20 (the default)
	quartile: 'rank', // 'rank' (NTILE) or 'value' (distribution)
});

result.x.entries[0]; // top customer, fully classified (class, quartile, share…)
result.quadCounts[1]; // # of rows where both axes are "vital" (Q1)
result.quadValues[4]; // summed revenue of the "trivial/trivial" quad (Q4)
result.points; // every row tagged with its quad

Accessors can be field names or functions, so nothing about your data's shape is assumed:

analyze(rows, {
	x: (r) => `${r.region}/${r.rep}`,
	y: 'sku',
	value: (r) => r.units * r.price,
});

Concepts

| Term | Meaning | | ------------- | --------------------------------------------------------------------------------- | | Pareto | Sort contributors high→low, walk the cumulative share, split vital / trivial. | | Vital few | Contributors within the threshold (the classic top ~80%). | | Quad | Cross the X-axis class with the Y-axis class → quadrant 1–4. | | Quartile | Four equal groups, by rank (NTILE) or by where a value sits in the distribution. |

Quad matrix:

| Quad | X axis | Y axis | | ---- | ------- | ------- | | 1 | vital | vital | | 2 | vital | trivial | | 3 | trivial | vital | | 4 | trivial | trivial |

Configuring the Pareto split

The split is fully configurable. The default is an exact 0.8 cutoff with no buffer. Add a buffer to nudge the boundary (e.g. "80% plus one more"):

analyze(rows, {
	x: 'customer',
	y: 'product',
	value: 'revenue',
	pareto: {
		threshold: 0.8, // base cutoff (0–1)
		buffer: 0.005, // effective cutoff becomes 0.805
		alwaysIncludeTop: true, // largest contributor is always "vital"
	},
});

Subpath imports

Everything is re-exported from the package root, but each module is also available as a focused, tree-shakeable subpath:

import { pareto, classifyPareto } from '@leanchuck/core/pareto';
import { classifyQuad } from '@leanchuck/core/quad';
import { quartileByRank } from '@leanchuck/core/quartile';
import { rollup } from '@leanchuck/core/rollup';
import { percentiles, summarize } from '@leanchuck/core/stats';
import { roundTo, sumBy } from '@leanchuck/core/math';

| Subpath | Contents | | -------------------------- | ---------------------------------------------------- | | @leanchuck/core | Everything, incl. the high-level analyze. | | @leanchuck/core/pareto | Cumulative share + 80/20 classification. | | @leanchuck/core/quad | 2×2 quadrant classification. | | @leanchuck/core/quartile | Rank-based and value-based quartiles. | | @leanchuck/core/rollup | Aggregate a flat dataset into per-dimension entries. | | @leanchuck/core/stats | Percentiles, median, summaries. | | @leanchuck/core/math | Rounding, percentages, sums, means. |

Building blocks

Prefer to compose it yourself? The primitives are exported directly:

import { rollup, pareto, classifyQuad } from '@leanchuck/core';

const customers = rollup(invoices, { by: 'customer', value: 'revenue' });
const ranked = pareto(customers, (c) => c.value, { threshold: 0.8 });

const top = ranked.items.filter((i) => i.class === 'vital');

Scripts

| Script | Description | | -------------------- | ----------------------------------- | | npm run build | Build ESM + CJS + types via tsup. | | npm test | Run the vitest suite. | | npm run typecheck | Type-check without emitting. | | npm run docs | Generate API docs via typedoc. | | npm run docs:serve | Serve the generated docs locally. |

License

MIT