@stll/calculations 0.0.1-placeholder.0 → 0.1.1

package/README.md

@@ -0,0 +1,13 @@
+# @stll/calculations
+
+Typed, unit-safe reducers for Stella workspace columns.
+
+The package provides counting, numeric and monetary reductions, including
+view-scoped percentages. Mixed units remain unsupported instead of producing a
+misleading total.
+
+```ts
+import { runCalculation } from "@stll/calculations";
+```
+
+Public API changes require a changeset.

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+import { CentsAmount, MoneyTotalsEntry } from "@stll/money";
+//#region src/index.d.ts
+declare const CALCULATION_KINDS: readonly ["count", "count-unique", "count-empty", "count-filled", "percent-empty", "percent-filled", "sum", "average", "median", "min", "max", "range", "percent-of-total"];
+type CalculationKind = (typeof CALCULATION_KINDS)[number];
+/** Kinds that reduce the values themselves rather than counting rows. */
+declare const NUMERIC_CALCULATION_KINDS: readonly ["sum", "average", "median", "min", "max", "range", "percent-of-total"];
+type NumericCalculationKind = (typeof NUMERIC_CALCULATION_KINDS)[number];
+declare const isNumericCalculationKind: (kind: CalculationKind) => kind is NumericCalculationKind;
+/**
+ * One row's contribution to a calculation.
+ *
+ * A property renderer decides which arm a cell maps to. `empty` is its own arm
+ * rather than a null value so "no value" is never confused with the number
+ * zero, which is what makes count-empty and average disagree correctly.
+ */
+type CalculationValue = {
+  type: "empty";
+} | {
+  type: "number";
+  value: number;
+} | {
+  type: "money";
+  amountCents: CentsAmount;
+  currency: string;
+} | {
+  type: "text";
+  value: string;
+};
+type CalculationUnsupportedReason =
+/** A numeric reduction over values that are not numbers. */
+"non-numeric" |
+/** Numbers mixed with money, or money the reduction cannot combine. */
+"mixed-units" |
+/** A reduction that needs at least one value, over none. */
+"no-values" |
+/** A share of the whole, asked without being told what the whole is. */
+"no-scope";
+type CalculationResult =
+/** A number of rows. */
+{
+  type: "count";
+  kind: CalculationKind;
+  value: number;
+} |
+/** A share between 0 and 1. */
+{
+  type: "ratio";
+  kind: CalculationKind;
+  value: number;
+} |
+/** A plain number in the property's own unit. */
+{
+  type: "number";
+  kind: CalculationKind;
+  value: number;
+} |
+/** One amount per currency, sorted by currency code. */
+{
+  type: "money";
+  kind: CalculationKind;
+  totals: readonly MoneyTotalsEntry[];
+} | {
+  type: "unsupported";
+  kind: CalculationKind;
+  reason: CalculationUnsupportedReason;
+};
+type RunCalculationParams = {
+  kind: CalculationKind;
+  /** The values in the column, in row order. */
+  values: readonly CalculationValue[];
+  /**
+   * Every value in the view, for a reduction relative to the whole
+   * (percent-of-total). Omitting it is not "relative to itself" — that answer
+   * is always 100% and always meaningless — so percent-of-total without a
+   * scope is unsupported rather than wrong.
+   */
+  scopeValues?: readonly CalculationValue[] | undefined;
+};
+declare const runCalculation: ({ kind, values, scopeValues }: RunCalculationParams) => CalculationResult;
+//#endregion
+export { CALCULATION_KINDS, CalculationKind, CalculationResult, CalculationUnsupportedReason, CalculationValue, type CentsAmount, type MoneyTotalsEntry, NUMERIC_CALCULATION_KINDS, NumericCalculationKind, RunCalculationParams, isNumericCalculationKind, runCalculation };

package/dist/index.js

@@ -0,0 +1,264 @@
+import { panic } from "better-result";
+import { MoneyTotals, cents } from "@stll/money";
+//#region src/index.ts
+/**
+* Column calculations: the reduction a view shows under (or beside) a column.
+*
+* The language is deliberately small and deliberately shared. A board's column
+* header and a table's footer row must agree on what "sum" means, or the same
+* rows read two different totals depending on which view is open; one reducer
+* is what makes that agreement structural rather than a convention.
+*
+* Money never crosses currencies. A monetary reduction returns one line per
+* currency (`MoneyTotals` buckets them), so there is no code path in which two
+* currencies silently add up to a number that means nothing.
+*/
+const CALCULATION_KINDS = [
+	"count",
+	"count-unique",
+	"count-empty",
+	"count-filled",
+	"percent-empty",
+	"percent-filled",
+	"sum",
+	"average",
+	"median",
+	"min",
+	"max",
+	"range",
+	"percent-of-total"
+];
+/** Kinds that reduce the values themselves rather than counting rows. */
+const NUMERIC_CALCULATION_KINDS = [
+	"sum",
+	"average",
+	"median",
+	"min",
+	"max",
+	"range",
+	"percent-of-total"
+];
+const isNumericCalculationKind = (kind) => NUMERIC_CALCULATION_KINDS.some((candidate) => candidate === kind);
+const runCalculation = ({ kind, values, scopeValues }) => {
+	switch (kind) {
+		case "count": return {
+			type: "count",
+			kind,
+			value: values.length
+		};
+		case "count-empty": return {
+			type: "count",
+			kind,
+			value: countEmpty(values)
+		};
+		case "count-filled": return {
+			type: "count",
+			kind,
+			value: values.length - countEmpty(values)
+		};
+		case "count-unique": return {
+			type: "count",
+			kind,
+			value: countUnique(values)
+		};
+		case "percent-empty": return {
+			type: "ratio",
+			kind,
+			value: share(countEmpty(values), values)
+		};
+		case "percent-filled": return {
+			type: "ratio",
+			kind,
+			value: share(values.length - countEmpty(values), values)
+		};
+		case "sum":
+		case "average":
+		case "median":
+		case "min":
+		case "max":
+		case "range": return reduceNumeric(kind, values);
+		case "percent-of-total": return scopeValues === void 0 ? {
+			type: "unsupported",
+			kind,
+			reason: "no-scope"
+		} : percentOfTotal(kind, values, scopeValues);
+		default: return panic(`Unhandled kind: ${String(kind)}`);
+	}
+};
+const countEmpty = (values) => values.filter((value) => value.type === "empty").length;
+const share = (part, values) => values.length === 0 ? 0 : part / values.length;
+/**
+* Distinctness key. Money is keyed by currency and amount together, so 100 CZK
+* and 100 EUR are two values, not one.
+*/
+const uniqueKey = (value) => {
+	switch (value.type) {
+		case "empty": return null;
+		case "number": return `n:${value.value}`;
+		case "money": return `m:${value.currency}:${value.amountCents}`;
+		case "text": return `t:${value.value}`;
+		default: return panic(`Unhandled value: ${String(value)}`);
+	}
+};
+const countUnique = (values) => {
+	const seen = /* @__PURE__ */ new Set();
+	for (const value of values) {
+		const key = uniqueKey(value);
+		if (key !== null) seen.add(key);
+	}
+	return seen.size;
+};
+/**
+* Split the non-empty values into a single unit, or say why they have none.
+* Numbers and money together are the interesting failure: each side is
+* reducible on its own, and combining them would produce a number whose unit
+* nobody can name.
+*/
+const classify = (values) => {
+	const numbers = [];
+	const buckets = /* @__PURE__ */ new Map();
+	for (const value of values) switch (value.type) {
+		case "empty": break;
+		case "text": return {
+			type: "unsupported",
+			reason: "non-numeric"
+		};
+		case "number":
+			numbers.push(value.value);
+			break;
+		case "money": {
+			const bucket = buckets.get(value.currency);
+			if (bucket) bucket.push(value.amountCents);
+			else buckets.set(value.currency, [value.amountCents]);
+			break;
+		}
+		default: return panic(`Unhandled value: ${String(value)}`);
+	}
+	if (numbers.length > 0 && buckets.size > 0) return {
+		type: "unsupported",
+		reason: "mixed-units"
+	};
+	if (buckets.size > 0) return {
+		type: "money",
+		buckets
+	};
+	if (numbers.length > 0) return {
+		type: "numbers",
+		values: numbers
+	};
+	return {
+		type: "unsupported",
+		reason: "no-values"
+	};
+};
+const REDUCERS = {
+	sum: (values) => values.reduce((total, value) => total + value, 0),
+	average: (values) => values.reduce((total, value) => total + value, 0) / values.length,
+	median: (values) => {
+		const sorted = [...values].toSorted((a, b) => a - b);
+		const middle = Math.floor(sorted.length / 2);
+		const upper = sorted[middle] ?? 0;
+		if (sorted.length % 2 === 1) return upper;
+		return ((sorted[middle - 1] ?? 0) + upper) / 2;
+	},
+	min: (values) => Math.min(...values),
+	max: (values) => Math.max(...values),
+	range: (values) => Math.max(...values) - Math.min(...values)
+};
+const reduceNumeric = (kind, values) => {
+	const classified = classify(values);
+	switch (classified.type) {
+		case "unsupported":
+			if (kind === "sum" && classified.reason === "no-values") return {
+				type: "number",
+				kind,
+				value: 0
+			};
+			return {
+				type: "unsupported",
+				kind,
+				reason: classified.reason
+			};
+		case "numbers": return {
+			type: "number",
+			kind,
+			value: REDUCERS[kind](classified.values)
+		};
+		case "money": {
+			const totals = new MoneyTotals();
+			for (const [currency, amounts] of classified.buckets) totals.add(currency, cents(Math.round(REDUCERS[kind](amounts))));
+			return {
+				type: "money",
+				kind,
+				totals: totals.entries()
+			};
+		}
+		default: return panic(`Unhandled classified: ${String(classified)}`);
+	}
+};
+/**
+* The column's total as a share of the view's total.
+*
+* A ratio only means something when both totals are counted in the same thing,
+* so each side carries its unit out of `singleTotal` and a mismatch is rejected
+* rather than divided: 100 EUR of a 100 CZK whole is not "all of it", and five
+* of a hundred euros is not five percent.
+*/
+const percentOfTotal = (kind, values, scopeValues) => {
+	const part = singleTotal(values);
+	const whole = singleTotal(scopeValues);
+	if (whole.type === "unsupported") return {
+		type: "unsupported",
+		kind,
+		reason: whole.reason
+	};
+	if (part.type === "unsupported" && part.reason !== "no-values") return {
+		type: "unsupported",
+		kind,
+		reason: part.reason
+	};
+	if (part.type === "total" && part.unit !== whole.unit) return {
+		type: "unsupported",
+		kind,
+		reason: "mixed-units"
+	};
+	if (whole.value === 0) return {
+		type: "unsupported",
+		kind,
+		reason: "no-values"
+	};
+	return {
+		type: "ratio",
+		kind,
+		value: (part.type === "unsupported" ? 0 : part.value) / whole.value
+	};
+};
+const singleTotal = (values) => {
+	const classified = classify(values);
+	switch (classified.type) {
+		case "unsupported": return {
+			type: "unsupported",
+			reason: classified.reason
+		};
+		case "numbers": return {
+			type: "total",
+			value: REDUCERS.sum(classified.values),
+			unit: "number"
+		};
+		case "money": {
+			if (classified.buckets.size > 1) return {
+				type: "unsupported",
+				reason: "mixed-units"
+			};
+			const [currency, amounts] = [...classified.buckets.entries()].at(0) ?? ["", []];
+			return {
+				type: "total",
+				value: REDUCERS.sum(amounts),
+				unit: currency
+			};
+		}
+		default: return panic(`Unhandled classified: ${String(classified)}`);
+	}
+};
+//#endregion
+export { CALCULATION_KINDS, NUMERIC_CALCULATION_KINDS, isNumericCalculationKind, runCalculation };

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@stll/calculations",
-  "version": "0.0.1-placeholder.0",
-  "description": "Placeholder to bootstrap npm trusted publishing. Real releases are published from stella/stella via GitHub Actions.",
-  "license": "Apache-2.0"
+  "version": "0.1.1",
+  "description": "Typed, unit-safe reducers for workspace column calculations.",
+  "keywords": [
+    "calculations",
+    "columns",
+    "money",
+    "reductions",
+    "workspace"
+  ],
+  "homepage": "https://github.com/stella/stella/tree/main/packages/calculations",
+  "bugs": {
+    "url": "https://github.com/stella/stella/issues"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stella/stella.git",
+    "directory": "packages/calculations"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "git clean -xdf dist .cache .turbo node_modules",
+    "build": "tsdown",
+    "pack:dry-run": "bun pm pack --dry-run",
+    "test": "bun test src",
+    "test:property": "bun test --preload @stll/property-testing/preload $(grep -rlF 'fc.assert' src)",
+    "typecheck": "bun ../../packages/scripts/src/tsc-native.ts --noEmit",
+    "lint": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --report-unused-disable-directives-severity=error --deny-warnings --type-aware packages/calculations",
+    "lint:fix": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --type-aware --fix packages/calculations",
+    "format": "bun ../../scripts/run-oxfmt.ts .",
+    "prepack": "bun run build"
+  },
+  "dependencies": {
+    "@stll/money": "^0.2.0",
+    "better-result": "3.0.0"
+  },
+  "devDependencies": {
+    "@stll/property-testing": "0.0.0",
+    "@stll/typescript-config": "0.0.0",
+    "bun-types": "1.4.2",
+    "fast-check": "^4.9.0",
+    "tsdown": "0.22.14"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
 }