@loadmap/core 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaime Rojas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,16 @@
-# Temporary Holding Version
+# @loadmap/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The model behind [loadmap](https://jaim3r0jas.github.io/loadmap/), in plain TypeScript with no dependencies: params,
+flows, components whose capacities say where they came from, limits as ranges, the verdict, scenarios, growth,
+`compare()`, `headroom()` and `check()`. It runs in Node, so a test can hold a model to its headroom:
+
+```ts
+import { assertHolds } from '@loadmap/core'
+import { shop } from './shop'
+
+it('keeps its headroom', () => assertHolds(shop)) // throws, listing every failed expectation
+```
+
+`@loadmap/core/calibrate` fits `cost = a + b × rate` from measurements (`fitLinear`); `@loadmap/core/format` has the
+number formats the verdict uses. Most pages install [`@loadmap/react`](https://www.npmjs.com/package/@loadmap/react),
+which re-exports all of this. MIT.

package/dist/calibrate-CRZgyOq5.d.ts

@@ -0,0 +1,52 @@
+type Provenance = 'measured' | 'estimated';
+/** A capacity always says where it came from: the verdict and the assumptions list show it. */
+interface Capacity {
+  value: number;
+  unit: string;
+  provenance: Provenance;
+  source?: string;
+  /** How sure the value is, as a share: 0.3 is ±30 %. The limits become ranges between the two bounds. */
+  within?: number;
+}
+interface CapacityOptions {
+  source?: string;
+  /** ±, as a share of the value: 0.3 is ±30 %. At least 0, below 1. */
+  within?: number;
+}
+/** A capacity read off a dashboard or a load test. */
+declare function measured(value: number, unit: string, o?: string | CapacityOptions): Capacity;
+/** A capacity from a vendor's figure, a benchmark elsewhere or a guess: the verdict says so. */
+declare function estimated(value: number, unit: string, o?: string | CapacityOptions): Capacity;
+/** The capacity's value at its low or high bound; the value itself without a ±. */
+declare function boundOf(c: Capacity, bound: Bound | undefined): number;
+/** Every capacity at its low bound (the pessimistic edge) or its high bound. */
+type Bound = 'low' | 'high';
+/** Where something is reached with every capacity at its low bound (`low`) and at its high bound (`high`). */
+interface CrossingRange {
+  low: number;
+  high: number;
+}
+/** cost = a + b × x, fitted from a measured series. Callable: `fit(x)` is the cost at x. */
+interface LinearFit {
+  (x: number): number;
+  a: number;
+  b: number;
+  /** Coefficient of determination of the fit, 0 to 1. */
+  r2: number;
+  n: number;
+  x: string;
+  y: string;
+  source?: string;
+  provenance: 'measured';
+}
+/**
+ * Ordinary least squares over `points[x]` → `points[y]`. Needs at least two distinct x values.
+ * `through: 'origin'` fixes a at 0 (a cost with no idle part).
+ */
+declare function fitLinear<T extends Record<string, unknown>>(points: readonly T[], o: {
+  x: keyof T & string;
+  y: keyof T & string;
+  source?: string;
+  through?: 'origin';
+}): LinearFit;
+export { CapacityOptions as a, boundOf as c, Capacity as i, estimated as l, fitLinear as n, CrossingRange as o, Bound as r, Provenance as s, LinearFit as t, measured as u };

package/dist/calibrate.d.ts

@@ -0,0 +1,2 @@
+import { i as Capacity, l as estimated, n as fitLinear, s as Provenance, t as LinearFit, u as measured } from "./calibrate-CRZgyOq5.js";
+export { type Capacity, LinearFit, type Provenance, estimated, fitLinear, measured };

package/dist/calibrate.js

@@ -0,0 +1,41 @@
+import { n as estimated, r as measured } from "./capacity-0zHaaRMk.js";
+// src/calibrate.ts
+/**
+* Ordinary least squares over `points[x]` → `points[y]`. Needs at least two distinct x values.
+* `through: 'origin'` fixes a at 0 (a cost with no idle part).
+*/
+function fitLinear(points, o) {
+	const xs = points.map((pt) => Number(pt[o.x]));
+	const ys = points.map((pt) => Number(pt[o.y]));
+	const n = xs.length;
+	if (xs.some((v) => !Number.isFinite(v)) || ys.some((v) => !Number.isFinite(v))) throw new Error(`loadmap: fitLinear(${o.x} → ${o.y}) got a non-numeric point`);
+	if (n < 2 || new Set(xs).size < 2) throw new Error(`loadmap: fitLinear(${o.x} → ${o.y}) needs two distinct x values`);
+	let a;
+	let b;
+	if (o.through === "origin") {
+		a = 0;
+		b = sum(xs.map((x, i) => x * ys[i])) / sum(xs.map((x) => x * x));
+	} else {
+		const mx = sum(xs) / n;
+		const my = sum(ys) / n;
+		b = sum(xs.map((x, i) => (x - mx) * (ys[i] - my))) / sum(xs.map((x) => (x - mx) ** 2));
+		a = my - b * mx;
+	}
+	const my = sum(ys) / n;
+	const ssTot = sum(ys.map((y) => (y - my) ** 2));
+	const ssRes = sum(xs.map((x, i) => (ys[i] - (a + b * x)) ** 2));
+	const r2 = ssTot === 0 ? 1 : Math.max(0, 1 - ssRes / ssTot);
+	const fit = ((x) => a + b * x);
+	return Object.assign(fit, {
+		a,
+		b,
+		r2,
+		n,
+		x: o.x,
+		y: o.y,
+		source: o.source,
+		provenance: "measured"
+	});
+}
+const sum = (v) => v.reduce((s, x) => s + x, 0);
+export { estimated, fitLinear, measured };

package/dist/capacity-0zHaaRMk.js

@@ -0,0 +1,30 @@
+// src/capacity.ts
+/** A capacity read off a dashboard or a load test. */
+function measured(value, unit, o) {
+	return capacity(value, unit, "measured", o);
+}
+/** A capacity from a vendor's figure, a benchmark elsewhere or a guess: the verdict says so. */
+function estimated(value, unit, o) {
+	return capacity(value, unit, "estimated", o);
+}
+function capacity(value, unit, provenance, o) {
+	const { source, within } = typeof o === "string" ? {
+		source: o,
+		within: void 0
+	} : o ?? {};
+	if (within != null && !(within >= 0 && within < 1)) throw new Error(`loadmap: within is a share from 0 to below 1 (0.3 is ±30 %), not ${within}`);
+	const c = {
+		value,
+		unit,
+		provenance,
+		source
+	};
+	if (within) c.within = within;
+	return c;
+}
+/** The capacity's value at its low or high bound; the value itself without a ±. */
+function boundOf(c, bound) {
+	if (!bound || !c.within) return c.value;
+	return c.value * (bound === "low" ? 1 - c.within : 1 + c.within);
+}
+export { estimated as n, measured as r, boundOf as t };

package/dist/format.d.ts

@@ -0,0 +1,28 @@
+/** A number for a reader: 1,234 / 12.3 / 0.4. */
+export declare function fmt(n: number): string;
+/** A compact number: 980 / 1.2k / 34k / 1.5M. */
+export declare function compact(n: number): string;
+/** A load multiple, rounded down so it never promises more than the model: 2.6× / 53×. */
+export declare function multiple(u: number | null, searchMax?: number): string;
+/**
+ * Two load multiples: "7.4×" when both edges read the same, else "between 7.4× and 10×" or, short, "7.4×–10×". An
+ * edge that never comes reads "7.4× or more" ("≥ 7.4×").
+ */
+export declare function multiples(r: {
+  low: number;
+  high: number;
+}, searchMax?: number, short?: boolean): string;
+/** When two edges are reached: "(around March 2029)", "(between March 2029 and May 2030)" or "(… or later)". */
+export declare function months(low: Date | null, high: Date | null): string;
+/** A percentage of a 0–1 share: 50 %. */
+export declare function pct(share: number): string;
+/** A duration in seconds for a meter: 0 s / 42 s / 3 min / > 1 h / stalled. */
+export declare function secs(s: number): string;
+/** The 1-2-5 step at or above x: 1, 2, 5, 10, 20, 50, … */
+export declare function niceStep(x: number): number;
+/** "a", "a and b", "a, b and c". */
+export declare function joinAnd(items: readonly string[]): string;
+/** A month in UTC, "March 2028" or short "Mar 2028". Fixed names, whatever the locale. */
+export declare function monthOf(d: Date, short?: boolean): string;
+/** A date as a reader plans with it, by month: "around March 2028". */
+export declare function around(d: Date): string;

package/dist/format.js

@@ -0,0 +1,85 @@
+// src/format.ts
+/** A number for a reader: 1,234 / 12.3 / 0.4. */
+function fmt(n) {
+	if (!Number.isFinite(n)) return n > 0 ? "∞" : "—";
+	if (Math.abs(n) >= 1e3) return Math.round(n).toLocaleString("en-US");
+	return (Math.round(n * 10) / 10).toString();
+}
+/** A compact number: 980 / 1.2k / 34k / 1.5M. */
+function compact(n) {
+	if (!Number.isFinite(n)) return n > 0 ? "∞" : "—";
+	const a = Math.abs(n);
+	if (a >= 1e6) return `${(n / 1e6).toFixed(1)}M`;
+	if (a >= 1e4) return `${Math.round(n / 1e3)}k`;
+	if (a >= 1e3) return `${(n / 1e3).toFixed(1)}k`;
+	return Math.round(n).toString();
+}
+/** A load multiple, rounded down so it never promises more than the model: 2.6× / 53×. */
+function multiple(u, searchMax = 2e3) {
+	if (u == null) return "—";
+	if (!Number.isFinite(u)) return `beyond ${fmt(searchMax)}×`;
+	return u >= 10 ? `${Math.floor(u)}×` : `${Math.floor(u * 10) / 10}×`;
+}
+/**
+* Two load multiples: "7.4×" when both edges read the same, else "between 7.4× and 10×" or, short, "7.4×–10×". An
+* edge that never comes reads "7.4× or more" ("≥ 7.4×").
+*/
+function multiples(r, searchMax = 2e3, short = false) {
+	const [lo, hi] = [multiple(r.low, searchMax), multiple(r.high, searchMax)];
+	if (lo === hi) return lo;
+	if (!Number.isFinite(r.high)) return short ? `≥ ${lo}` : `${lo} or more`;
+	return short ? `${lo}–${hi}` : `between ${lo} and ${hi}`;
+}
+/** When two edges are reached: "(around March 2029)", "(between March 2029 and May 2030)" or "(… or later)". */
+function months(low, high) {
+	if (!low) return "";
+	if (!high) return ` (${around(low)} or later)`;
+	return monthOf(low) === monthOf(high) ? ` (${around(low)})` : ` (between ${monthOf(low)} and ${monthOf(high)})`;
+}
+/** A percentage of a 0–1 share: 50 %. */
+function pct(share) {
+	return `${Math.round(share * 100)} %`;
+}
+/** A duration in seconds for a meter: 0 s / 42 s / 3 min / > 1 h / stalled. */
+function secs(s) {
+	if (!Number.isFinite(s)) return "stalled";
+	if (s < 1) return "0 s";
+	if (s < 60) return `${Math.round(s)} s`;
+	if (s < 3600) return `${Math.round(s / 60)} min`;
+	return "> 1 h";
+}
+/** The 1-2-5 step at or above x: 1, 2, 5, 10, 20, 50, … */
+function niceStep(x) {
+	const p = 10 ** Math.floor(Math.log10(Math.max(x, 1)));
+	const f = x / p;
+	return (f <= 1 ? 1 : f <= 2 ? 2 : f <= 5 ? 5 : 10) * p;
+}
+/** "a", "a and b", "a, b and c". */
+function joinAnd(items) {
+	if (items.length <= 1) return items[0] ?? "";
+	return `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+}
+const MONTHS = [
+	"January",
+	"February",
+	"March",
+	"April",
+	"May",
+	"June",
+	"July",
+	"August",
+	"September",
+	"October",
+	"November",
+	"December"
+];
+/** A month in UTC, "March 2028" or short "Mar 2028". Fixed names, whatever the locale. */
+function monthOf(d, short = false) {
+	const name = MONTHS[d.getUTCMonth()];
+	return `${short ? name.slice(0, 3) : name} ${d.getUTCFullYear()}`;
+}
+/** A date as a reader plans with it, by month: "around March 2028". */
+function around(d) {
+	return `around ${monthOf(d)}`;
+}
+export { around, compact, fmt, joinAnd, monthOf, months, multiple, multiples, niceStep, pct, secs };