formulab 0.12.0 → 0.13.0

package/dist/utility/correlation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"correlation.d.ts","sourceRoot":"","sources":["../../src/utility/correlation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEtE,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,iBAAiB,GAAG,IAAI,CA8B7E"}
+{"version":3,"file":"correlation.d.ts","sourceRoot":"","sources":["../../src/utility/correlation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEtE;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,iBAAiB,CAmCtE"}

package/dist/utility/correlation.js

@@ -1,8 +1,19 @@
 import { roundTo } from '../utils.js';
+/**
+ * Pearson correlation coefficient between two equal-length samples.
+ *
+ * @param input - Paired samples x and y
+ * @returns Correlation coefficient r, r-squared, and sample size n
+ * @throws RangeError if x and y lengths differ or contain fewer than 2 points
+ */
 export function correlation(input) {
     const { x, y } = input;
-    if (!x || !y || x.length !== y.length || x.length < 2)
-        return null;
+    if (!x || !y || x.length !== y.length) {
+        throw new RangeError(`x and y must have the same length, got ${x?.length ?? 0} and ${y?.length ?? 0}`);
+    }
+    if (x.length < 2) {
+        throw new RangeError(`x and y must contain at least 2 points, got ${x.length}`);
+    }
     const n = x.length;
     const meanX = x.reduce((a, v) => a + v, 0) / n;
     const meanY = y.reduce((a, v) => a + v, 0) / n;

package/dist/utility/correlation.js.map

@@ -1 +1 @@
-{"version":3,"file":"correlation.js","sourceRoot":"","sources":["../../src/utility/correlation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGtC,MAAM,UAAU,WAAW,CAAC,KAAuB;IACjD,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,KAAK,CAAC;IACvB,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAEnE,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;IACnB,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IAE/C,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;QACxB,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;QACxB,KAAK,IAAI,EAAE,GAAG,EAAE,CAAC;QACjB,KAAK,IAAI,EAAE,GAAG,EAAE,CAAC;QACjB,KAAK,IAAI,EAAE,GAAG,EAAE,CAAC;IACnB,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC;IACvC,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;IAE3C,MAAM,CAAC,GAAG,KAAK,GAAG,KAAK,CAAC;IAExB,OAAO;QACL,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;QAChB,EAAE,EAAE,OAAO,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"correlation.js","sourceRoot":"","sources":["../../src/utility/correlation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGtC;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAuB;IACjD,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,KAAK,CAAC;IACvB,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QACtC,MAAM,IAAI,UAAU,CAAC,0CAA0C,CAAC,EAAE,MAAM,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC,EAAE,CAAC,CAAC;IACzG,CAAC;IACD,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjB,MAAM,IAAI,UAAU,CAAC,+CAA+C,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IAClF,CAAC;IAED,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;IACnB,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IAE/C,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;QACxB,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;QACxB,KAAK,IAAI,EAAE,GAAG,EAAE,CAAC;QACjB,KAAK,IAAI,EAAE,GAAG,EAAE,CAAC;QACjB,KAAK,IAAI,EAAE,GAAG,EAAE,CAAC;IACnB,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC;IACvC,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;IAE3C,MAAM,CAAC,GAAG,KAAK,GAAG,KAAK,CAAC;IAExB,OAAO;QACL,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;QAChB,EAAE,EAAE,OAAO,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/utility/depreciation.d.ts

@@ -1,3 +1,11 @@
 import type { DepreciationInput, DepreciationResult } from './types.js';
-export declare function depreciation(input: DepreciationInput): DepreciationResult | null;
+/**
+ * Depreciation schedule by straight-line or declining-balance method.
+ *
+ * @param input - Asset cost, salvage value, useful life, and method
+ * @returns Annual depreciation, year-by-year schedule, and total depreciation
+ * @throws RangeError if assetCost <= 0, salvageValue < 0, usefulLife <= 0,
+ *   salvageValue >= assetCost, or method is unknown
+ */
+export declare function depreciation(input: DepreciationInput): DepreciationResult;
 //# sourceMappingURL=depreciation.d.ts.map

package/dist/utility/depreciation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"depreciation.d.ts","sourceRoot":"","sources":["../../src/utility/depreciation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAyB,MAAM,YAAY,CAAC;AAE/F,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,kBAAkB,GAAG,IAAI,CAYhF"}
+{"version":3,"file":"depreciation.d.ts","sourceRoot":"","sources":["../../src/utility/depreciation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAyB,MAAM,YAAY,CAAC;AAE/F;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,kBAAkB,CAgBzE"}

package/dist/utility/depreciation.js

@@ -1,17 +1,30 @@
 import { roundTo } from '../utils.js';
+/**
+ * Depreciation schedule by straight-line or declining-balance method.
+ *
+ * @param input - Asset cost, salvage value, useful life, and method
+ * @returns Annual depreciation, year-by-year schedule, and total depreciation
+ * @throws RangeError if assetCost <= 0, salvageValue < 0, usefulLife <= 0,
+ *   salvageValue >= assetCost, or method is unknown
+ */
 export function depreciation(input) {
     const { assetCost, salvageValue, usefulLife, method } = input;
-    if (assetCost <= 0 || salvageValue < 0 || usefulLife <= 0)
-        return null;
-    if (salvageValue >= assetCost)
-        return null;
+    if (assetCost <= 0)
+        throw new RangeError(`assetCost must be > 0, got ${assetCost}`);
+    if (salvageValue < 0)
+        throw new RangeError(`salvageValue must be >= 0, got ${salvageValue}`);
+    if (usefulLife <= 0)
+        throw new RangeError(`usefulLife must be > 0, got ${usefulLife}`);
+    if (salvageValue >= assetCost) {
+        throw new RangeError(`salvageValue must be less than assetCost, got salvageValue=${salvageValue}, assetCost=${assetCost}`);
+    }
     if (method === 'straight-line') {
         return straightLine(assetCost, salvageValue, usefulLife);
     }
     if (method === 'declining-balance') {
         return decliningBalance(assetCost, salvageValue, usefulLife);
     }
-    return null;
+    throw new RangeError(`method must be 'straight-line' or 'declining-balance', got ${String(method)}`);
 }
 function straightLine(cost, salvage, life) {
     const annual = (cost - salvage) / life;

package/dist/utility/depreciation.js.map

@@ -1 +1 @@
-{"version":3,"file":"depreciation.js","sourceRoot":"","sources":["../../src/utility/depreciation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGtC,MAAM,UAAU,YAAY,CAAC,KAAwB;IACnD,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IAC9D,IAAI,SAAS,IAAI,CAAC,IAAI,YAAY,GAAG,CAAC,IAAI,UAAU,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACvE,IAAI,YAAY,IAAI,SAAS;QAAE,OAAO,IAAI,CAAC;IAE3C,IAAI,MAAM,KAAK,eAAe,EAAE,CAAC;QAC/B,OAAO,YAAY,CAAC,SAAS,EAAE,YAAY,EAAE,UAAU,CAAC,CAAC;IAC3D,CAAC;IACD,IAAI,MAAM,KAAK,mBAAmB,EAAE,CAAC;QACnC,OAAO,gBAAgB,CAAC,SAAS,EAAE,YAAY,EAAE,UAAU,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,YAAY,CAAC,IAAY,EAAE,OAAe,EAAE,IAAY;IAC/D,MAAM,MAAM,GAAG,CAAC,IAAI,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC;IACvC,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAE7C,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,IAAI,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC;QACxC,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI;YACJ,YAAY,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;YAChC,uBAAuB,EAAE,OAAO,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC,CAAC;YAClD,SAAS,EAAE,OAAO,CAAC,IAAI,GAAG,MAAM,GAAG,IAAI,EAAE,CAAC,CAAC;SAC5C,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,kBAAkB,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QACtC,QAAQ;QACR,iBAAiB,EAAE,OAAO,CAAC,IAAI,GAAG,OAAO,EAAE,CAAC,CAAC;KAC9C,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,IAAY,EAAE,OAAe,EAAE,IAAY;IACnE,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAChD,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAC7C,IAAI,SAAS,GAAG,IAAI,CAAC;IACrB,IAAI,WAAW,GAAG,CAAC,CAAC;IAEpB,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,IAAI,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC;QACxC,MAAM,GAAG,GAAG,IAAI,KAAK,IAAI;YACvB,CAAC,CAAC,SAAS,GAAG,OAAO,CAAC,oCAAoC;YAC1D,CAAC,CAAC,SAAS,GAAG,IAAI,CAAC;QACrB,WAAW,IAAI,GAAG,CAAC;QACnB,SAAS,IAAI,GAAG,CAAC;QAEjB,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI;YACJ,YAAY,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;YAC7B,uBAAuB,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;YAChD,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;SACjC,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,kBAAkB,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC;QACxD,QAAQ;QACR,iBAAiB,EAAE,OAAO,CAAC,IAAI,GAAG,OAAO,EAAE,CAAC,CAAC;KAC9C,CAAC;AACJ,CAAC"}
+{"version":3,"file":"depreciation.js","sourceRoot":"","sources":["../../src/utility/depreciation.ts"],"names":[],"mappings":"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"}

package/dist/utility/histogram.d.ts

@@ -1,3 +1,10 @@
 import type { HistogramInput, HistogramResult } from './types.js';
-export declare function histogram(input: HistogramInput): HistogramResult | null;
+/**
+ * Histogram binning with optional explicit bin count (Sturges' rule by default) and range.
+ *
+ * @param input - Data values, optional bin count, optional [min, max] range
+ * @returns Bins with counts/frequencies, bin width, and total count
+ * @throws RangeError if data is empty or bins < 1
+ */
+export declare function histogram(input: HistogramInput): HistogramResult;
 //# sourceMappingURL=histogram.d.ts.map

package/dist/utility/histogram.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"histogram.d.ts","sourceRoot":"","sources":["../../src/utility/histogram.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAgB,MAAM,YAAY,CAAC;AAEhF,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,eAAe,GAAG,IAAI,CA2CvE"}
+{"version":3,"file":"histogram.d.ts","sourceRoot":"","sources":["../../src/utility/histogram.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAgB,MAAM,YAAY,CAAC;AAEhF;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,eAAe,CAwDhE"}

package/dist/utility/histogram.js

@@ -1,18 +1,36 @@
 import { roundTo } from '../utils.js';
+/**
+ * Histogram binning with optional explicit bin count (Sturges' rule by default) and range.
+ *
+ * @param input - Data values, optional bin count, optional [min, max] range
+ * @returns Bins with counts/frequencies, bin width, and total count
+ * @throws RangeError if data is empty or bins < 1
+ */
 export function histogram(input) {
     const { data } = input;
-    if (!data || data.length === 0)
-        return null;
+    if (!data || data.length === 0) {
+        throw new RangeError('data must contain at least one value');
+    }
     const n = data.length;
     // Sturges' rule for default bin count
     const numBins = input.bins ?? Math.max(1, Math.ceil(Math.log2(n) + 1));
-    if (numBins < 1)
-        return null;
-    const min = Math.min(...data);
-    const max = Math.max(...data);
+    if (numBins < 1) {
+        throw new RangeError(`bins must be >= 1, got ${numBins}`);
+    }
+    // Use explicit range when provided and valid; fall back to data-derived min/max
+    let min;
+    let max;
+    if (input.range && input.range[1] > input.range[0]) {
+        min = input.range[0];
+        max = input.range[1];
+    }
+    else {
+        min = Math.min(...data);
+        max = Math.max(...data);
+    }
     // Handle case where all values are identical
-    const range = max - min;
-    const binWidth = range === 0 ? 1 : range / numBins;
+    const span = max - min;
+    const binWidth = span === 0 ? 1 : span / numBins;
     const bins = [];
     for (let i = 0; i < numBins; i++) {
         const lower = min + i * binWidth;
@@ -25,7 +43,9 @@ export function histogram(input) {
         });
     }
     for (const value of data) {
-        let idx = range === 0 ? 0 : Math.floor((value - min) / binWidth);
+        let idx = span === 0 ? 0 : Math.floor((value - min) / binWidth);
+        if (idx < 0)
+            idx = 0; // clamp values below min into first bin
         if (idx >= numBins)
             idx = numBins - 1; // include max in last bin
         bins[idx].count++;

package/dist/utility/histogram.js.map

@@ -1 +1 @@
-{"version":3,"file":"histogram.js","sourceRoot":"","sources":["../../src/utility/histogram.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGtC,MAAM,UAAU,SAAS,CAAC,KAAqB;IAC7C,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;IACvB,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAE5C,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;IACtB,sCAAsC;IACtC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACvE,IAAI,OAAO,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAE7B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IAC9B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IAE9B,6CAA6C;IAC7C,MAAM,KAAK,GAAG,GAAG,GAAG,GAAG,CAAC;IACxB,MAAM,QAAQ,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,OAAO,CAAC;IAEnD,MAAM,IAAI,GAAmB,EAAE,CAAC;IAChC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,GAAG,GAAG,CAAC,GAAG,QAAQ,CAAC;QACjC,MAAM,KAAK,GAAG,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC;QACvC,IAAI,CAAC,IAAI,CAAC;YACR,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;YACxB,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;YACxB,KAAK,EAAE,CAAC;YACR,SAAS,EAAE,CAAC;SACb,CAAC,CAAC;IACL,CAAC;IAED,KAAK,MAAM,KAAK,IAAI,IAAI,EAAE,CAAC;QACzB,IAAI,GAAG,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC;QACjE,IAAI,GAAG,IAAI,OAAO;YAAE,GAAG,GAAG,OAAO,GAAG,CAAC,CAAC,CAAC,0BAA0B;QACjE,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC;IACpB,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,GAAG,CAAC,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5C,CAAC;IAED,OAAO;QACL,IAAI;QACJ,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC9B,UAAU,EAAE,CAAC;KACd,CAAC;AACJ,CAAC"}
+{"version":3,"file":"histogram.js","sourceRoot":"","sources":["../../src/utility/histogram.ts"],"names":[],"mappings":"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"}

package/dist/utility/lcc.d.ts

@@ -1,3 +1,11 @@
 import type { LccInput, LccResult } from './types.js';
-export declare function lcc(input: LccInput): LccResult | null;
+/**
+ * Calculate life cycle cost (LCC) with present-value discounting
+ *
+ * @param input - LCC input parameters
+ * @returns LCC result with total cost, present values, and annual equivalent cost
+ * @throws RangeError if initialCost is negative, lifespan is not positive,
+ *   or discountRate is outside [0, 1)
+ */
+export declare function lcc(input: LccInput): LccResult;
 //# sourceMappingURL=lcc.d.ts.map

package/dist/utility/lcc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lcc.d.ts","sourceRoot":"","sources":["../../src/utility/lcc.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEtD,wBAAgB,GAAG,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,IAAI,CA0BrD"}
+{"version":3,"file":"lcc.d.ts","sourceRoot":"","sources":["../../src/utility/lcc.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;;;;GAOG;AACH,wBAAgB,GAAG,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,CAiC9C"}

package/dist/utility/lcc.js

@@ -1,10 +1,23 @@
 import { roundTo } from '../utils.js';
+/**
+ * Calculate life cycle cost (LCC) with present-value discounting
+ *
+ * @param input - LCC input parameters
+ * @returns LCC result with total cost, present values, and annual equivalent cost
+ * @throws RangeError if initialCost is negative, lifespan is not positive,
+ *   or discountRate is outside [0, 1)
+ */
 export function lcc(input) {
     const { initialCost, annualOperatingCost, annualMaintenanceCost, disposalCost, lifespan, discountRate } = input;
-    if (initialCost < 0 || lifespan <= 0)
-        return null;
-    if (discountRate < 0 || discountRate >= 1)
-        return null;
+    if (initialCost < 0) {
+        throw new RangeError(`initialCost must be >= 0, got ${initialCost}`);
+    }
+    if (lifespan <= 0) {
+        throw new RangeError(`lifespan must be > 0, got ${lifespan}`);
+    }
+    if (discountRate < 0 || discountRate >= 1) {
+        throw new RangeError(`discountRate must be in [0, 1), got ${discountRate}`);
+    }
     // Present value of annuity factor: (1 - (1+r)^-n) / r
     const pvFactor = discountRate === 0
         ? lifespan

package/dist/utility/lcc.js.map

@@ -1 +1 @@
-{"version":3,"file":"lcc.js","sourceRoot":"","sources":["../../src/utility/lcc.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGtC,MAAM,UAAU,GAAG,CAAC,KAAe;IACjC,MAAM,EAAE,WAAW,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,KAAK,CAAC;IAChH,IAAI,WAAW,GAAG,CAAC,IAAI,QAAQ,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAClD,IAAI,YAAY,GAAG,CAAC,IAAI,YAAY,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAEvD,sDAAsD;IACtD,MAAM,QAAQ,GAAG,YAAY,KAAK,CAAC;QACjC,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,YAAY,CAAC;IAEzD,MAAM,qBAAqB,GAAG,mBAAmB,GAAG,QAAQ,CAAC;IAC7D,MAAM,uBAAuB,GAAG,qBAAqB,GAAG,QAAQ,CAAC;IACjE,MAAM,oBAAoB,GAAG,YAAY,GAAG,CAAC,CAAC,GAAG,YAAY,CAAC,IAAI,QAAQ,CAAC;IAE3E,MAAM,QAAQ,GAAG,WAAW,GAAG,qBAAqB,GAAG,uBAAuB,GAAG,oBAAoB,CAAC;IAEtG,yBAAyB;IACzB,MAAM,oBAAoB,GAAG,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAE7E,OAAO;QACL,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC9B,qBAAqB,EAAE,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAAC;QACxD,uBAAuB,EAAE,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAAC;QAC5D,oBAAoB,EAAE,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAAC;QACtD,oBAAoB,EAAE,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAAC;KACvD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"lcc.js","sourceRoot":"","sources":["../../src/utility/lcc.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGtC;;;;;;;GAOG;AACH,MAAM,UAAU,GAAG,CAAC,KAAe;IACjC,MAAM,EAAE,WAAW,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,KAAK,CAAC;IAChH,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,UAAU,CAAC,iCAAiC,WAAW,EAAE,CAAC,CAAC;IACvE,CAAC;IACD,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;QAClB,MAAM,IAAI,UAAU,CAAC,6BAA6B,QAAQ,EAAE,CAAC,CAAC;IAChE,CAAC;IACD,IAAI,YAAY,GAAG,CAAC,IAAI,YAAY,IAAI,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,UAAU,CAAC,uCAAuC,YAAY,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED,sDAAsD;IACtD,MAAM,QAAQ,GAAG,YAAY,KAAK,CAAC;QACjC,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,YAAY,CAAC;IAEzD,MAAM,qBAAqB,GAAG,mBAAmB,GAAG,QAAQ,CAAC;IAC7D,MAAM,uBAAuB,GAAG,qBAAqB,GAAG,QAAQ,CAAC;IACjE,MAAM,oBAAoB,GAAG,YAAY,GAAG,CAAC,CAAC,GAAG,YAAY,CAAC,IAAI,QAAQ,CAAC;IAE3E,MAAM,QAAQ,GAAG,WAAW,GAAG,qBAAqB,GAAG,uBAAuB,GAAG,oBAAoB,CAAC;IAEtG,yBAAyB;IACzB,MAAM,oBAAoB,GAAG,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAE7E,OAAO;QACL,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC9B,qBAAqB,EAAE,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAAC;QACxD,uBAAuB,EAAE,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAAC;QAC5D,oBAAoB,EAAE,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAAC;QACtD,oBAAoB,EAAE,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAAC;KACvD,CAAC;AACJ,CAAC"}

package/dist/utility/linearInterpolation.d.ts

@@ -1,3 +1,11 @@
 import type { LinearInterpolationInput, LinearInterpolationResult } from './types.js';
-export declare function linearInterpolation(input: LinearInterpolationInput): LinearInterpolationResult | null;
+/**
+ * Linear interpolation (and extrapolation) over a tabulated x/y series
+ *
+ * @param input - x/y table and target x value
+ * @returns Interpolated value with bracketing indices and extrapolation flag
+ * @throws RangeError if x or y is missing, x and y lengths differ,
+ *   or fewer than 2 points are provided
+ */
+export declare function linearInterpolation(input: LinearInterpolationInput): LinearInterpolationResult;
 //# sourceMappingURL=linearInterpolation.d.ts.map

package/dist/utility/linearInterpolation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"linearInterpolation.d.ts","sourceRoot":"","sources":["../../src/utility/linearInterpolation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAEtF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,wBAAwB,GAAG,yBAAyB,GAAG,IAAI,CAyCrG"}
+{"version":3,"file":"linearInterpolation.d.ts","sourceRoot":"","sources":["../../src/utility/linearInterpolation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAEtF;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,wBAAwB,GAAG,yBAAyB,CAiD9F"}

package/dist/utility/linearInterpolation.js

@@ -1,8 +1,23 @@
 import { roundTo } from '../utils.js';
+/**
+ * Linear interpolation (and extrapolation) over a tabulated x/y series
+ *
+ * @param input - x/y table and target x value
+ * @returns Interpolated value with bracketing indices and extrapolation flag
+ * @throws RangeError if x or y is missing, x and y lengths differ,
+ *   or fewer than 2 points are provided
+ */
 export function linearInterpolation(input) {
     const { x, y, target } = input;
-    if (!x || !y || x.length !== y.length || x.length < 2)
-        return null;
+    if (!x || !y) {
+        throw new RangeError('x and y arrays are required');
+    }
+    if (x.length !== y.length) {
+        throw new RangeError(`x and y must have the same length, got x.length=${x.length}, y.length=${y.length}`);
+    }
+    if (x.length < 2) {
+        throw new RangeError(`x must contain at least 2 points, got ${x.length}`);
+    }
     // Find bracketing interval
     let lowerIndex = 0;
     let upperIndex = x.length - 1;

package/dist/utility/linearInterpolation.js.map

@@ -1 +1 @@
-{"version":3,"file":"linearInterpolation.js","sourceRoot":"","sources":["../../src/utility/linearInterpolation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGtC,MAAM,UAAU,mBAAmB,CAAC,KAA+B;IACjE,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IAC/B,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAEnE,2BAA2B;IAC3B,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,UAAU,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;IAC9B,IAAI,eAAe,GAAG,KAAK,CAAC;IAE5B,IAAI,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACnB,UAAU,GAAG,CAAC,CAAC;QACf,UAAU,GAAG,CAAC,CAAC;QACf,eAAe,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAClC,CAAC;SAAM,IAAI,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;QACrC,UAAU,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;QAC1B,UAAU,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;QAC1B,eAAe,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC7C,CAAC;SAAM,CAAC;QACN,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,IAAI,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,MAAM,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;gBACzC,UAAU,GAAG,CAAC,CAAC;gBACf,UAAU,GAAG,CAAC,GAAG,CAAC,CAAC;gBACnB,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,EAAE,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC;IACzB,MAAM,EAAE,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC;IACzB,MAAM,EAAE,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC;IACzB,MAAM,EAAE,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC;IAEzB,MAAM,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;IACpD,MAAM,KAAK,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;IAEjC,OAAO;QACL,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACxB,UAAU;QACV,UAAU;QACV,eAAe;KAChB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"linearInterpolation.js","sourceRoot":"","sources":["../../src/utility/linearInterpolation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGtC;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAA+B;IACjE,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IAC/B,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QACb,MAAM,IAAI,UAAU,CAAC,6BAA6B,CAAC,CAAC;IACtD,CAAC;IACD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QAC1B,MAAM,IAAI,UAAU,CAAC,mDAAmD,CAAC,CAAC,MAAM,cAAc,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5G,CAAC;IACD,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjB,MAAM,IAAI,UAAU,CAAC,yCAAyC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5E,CAAC;IAED,2BAA2B;IAC3B,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,UAAU,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;IAC9B,IAAI,eAAe,GAAG,KAAK,CAAC;IAE5B,IAAI,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACnB,UAAU,GAAG,CAAC,CAAC;QACf,UAAU,GAAG,CAAC,CAAC;QACf,eAAe,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAClC,CAAC;SAAM,IAAI,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;QACrC,UAAU,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;QAC1B,UAAU,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;QAC1B,eAAe,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC7C,CAAC;SAAM,CAAC;QACN,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,IAAI,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,MAAM,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;gBACzC,UAAU,GAAG,CAAC,CAAC;gBACf,UAAU,GAAG,CAAC,GAAG,CAAC,CAAC;gBACnB,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,EAAE,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC;IACzB,MAAM,EAAE,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC;IACzB,MAAM,EAAE,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC;IACzB,MAAM,EAAE,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC;IAEzB,MAAM,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;IACpD,MAAM,KAAK,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;IAEjC,OAAO;QACL,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACxB,UAAU;QACV,UAAU;QACV,eAAe;KAChB,CAAC;AACJ,CAAC"}

package/dist/utility/movingAverage.d.ts

@@ -1,3 +1,11 @@
 import type { MovingAverageInput, MovingAverageResult } from './types.js';
-export declare function movingAverage(input: MovingAverageInput): MovingAverageResult | null;
+/**
+ * Calculate moving average (simple or exponential) over a data series
+ *
+ * @param input - Data series, window size, and method ('sma' | 'ema')
+ * @returns Moving average values
+ * @throws RangeError if data is empty, window is less than 1,
+ *   window exceeds data length, or method is not 'sma' or 'ema'
+ */
+export declare function movingAverage(input: MovingAverageInput): MovingAverageResult;
 //# sourceMappingURL=movingAverage.d.ts.map

package/dist/utility/movingAverage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"movingAverage.d.ts","sourceRoot":"","sources":["../../src/utility/movingAverage.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAE1E,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,mBAAmB,GAAG,IAAI,CAWnF"}
+{"version":3,"file":"movingAverage.d.ts","sourceRoot":"","sources":["../../src/utility/movingAverage.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAE1E;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,mBAAmB,CAmB5E"}

package/dist/utility/movingAverage.js

@@ -1,15 +1,30 @@
 import { roundTo } from '../utils.js';
+/**
+ * Calculate moving average (simple or exponential) over a data series
+ *
+ * @param input - Data series, window size, and method ('sma' | 'ema')
+ * @returns Moving average values
+ * @throws RangeError if data is empty, window is less than 1,
+ *   window exceeds data length, or method is not 'sma' or 'ema'
+ */
 export function movingAverage(input) {
     const { data, window, method } = input;
-    if (!data || data.length === 0 || window < 1 || window > data.length)
-        return null;
+    if (!data || data.length === 0) {
+        throw new RangeError('data must contain at least one value');
+    }
+    if (window < 1) {
+        throw new RangeError(`window must be >= 1, got ${window}`);
+    }
+    if (window > data.length) {
+        throw new RangeError(`window must be <= data length (${data.length}), got ${window}`);
+    }
     if (method === 'sma') {
         return { values: sma(data, window) };
     }
     if (method === 'ema') {
         return { values: ema(data, window) };
     }
-    return null;
+    throw new RangeError(`method must be 'sma' or 'ema', got ${String(method)}`);
 }
 function sma(data, window) {
     const result = [];

package/dist/utility/movingAverage.js.map

@@ -1 +1 @@
-{"version":3,"file":"movingAverage.js","sourceRoot":"","sources":["../../src/utility/movingAverage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGtC,MAAM,UAAU,aAAa,CAAC,KAAyB;IACrD,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IACvC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,GAAG,CAAC,IAAI,MAAM,GAAG,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAElF,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;QACrB,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;IACvC,CAAC;IACD,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;QACrB,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;IACvC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,GAAG,CAAC,IAAc,EAAE,MAAc;IACzC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,IAAI,GAAG,GAAG,CAAC,CAAC;QACZ,KAAK,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACzC,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC;QACjB,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,GAAG,CAAC,IAAc,EAAE,MAAc;IACzC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC3B,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,yCAAyC;IACzC,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC;IACjB,CAAC;IACD,IAAI,IAAI,GAAG,GAAG,GAAG,MAAM,CAAC;IACxB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAE9B,KAAK,IAAI,CAAC,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1C,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACpC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"movingAverage.js","sourceRoot":"","sources":["../../src/utility/movingAverage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGtC;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,KAAyB;IACrD,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IACvC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,UAAU,CAAC,sCAAsC,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QACf,MAAM,IAAI,UAAU,CAAC,4BAA4B,MAAM,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACzB,MAAM,IAAI,UAAU,CAAC,kCAAkC,IAAI,CAAC,MAAM,UAAU,MAAM,EAAE,CAAC,CAAC;IACxF,CAAC;IAED,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;QACrB,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;IACvC,CAAC;IACD,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;QACrB,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;IACvC,CAAC;IACD,MAAM,IAAI,UAAU,CAAC,sCAAsC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAC/E,CAAC;AAED,SAAS,GAAG,CAAC,IAAc,EAAE,MAAc;IACzC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,IAAI,GAAG,GAAG,CAAC,CAAC;QACZ,KAAK,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACzC,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC;QACjB,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,GAAG,CAAC,IAAc,EAAE,MAAc;IACzC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC3B,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,yCAAyC;IACzC,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC;IACjB,CAAC;IACD,IAAI,IAAI,GAAG,GAAG,GAAG,MAAM,CAAC;IACxB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAE9B,KAAK,IAAI,CAAC,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1C,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACpC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/utility/normalize.d.ts

@@ -1,3 +1,10 @@
 import type { NormalizeInput, NormalizeResult } from './types.js';
-export declare function normalize(input: NormalizeInput): NormalizeResult | null;
+/**
+ * Normalize a data series via min-max scaling or z-score standardization
+ *
+ * @param input - Data series and method ('min-max' | 'z-score')
+ * @returns Normalized values with min/max/mean/stdDev metadata
+ * @throws RangeError if data is empty or method is not 'min-max' or 'z-score'
+ */
+export declare function normalize(input: NormalizeInput): NormalizeResult;
 //# sourceMappingURL=normalize.d.ts.map

package/dist/utility/normalize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/utility/normalize.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElE,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,eAAe,GAAG,IAAI,CAiCvE"}
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/utility/normalize.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElE;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,eAAe,CAmChE"}

package/dist/utility/normalize.js

@@ -1,8 +1,16 @@
 import { roundTo } from '../utils.js';
+/**
+ * Normalize a data series via min-max scaling or z-score standardization
+ *
+ * @param input - Data series and method ('min-max' | 'z-score')
+ * @returns Normalized values with min/max/mean/stdDev metadata
+ * @throws RangeError if data is empty or method is not 'min-max' or 'z-score'
+ */
 export function normalize(input) {
     const { data, method } = input;
-    if (!data || data.length === 0)
-        return null;
+    if (!data || data.length === 0) {
+        throw new RangeError('data must contain at least one value');
+    }
     const n = data.length;
     const min = Math.min(...data);
     const max = Math.max(...data);
@@ -22,7 +30,7 @@ export function normalize(input) {
             : data.map((v) => roundTo((v - mean) / stdDev, 6));
     }
     else {
-        return null;
+        throw new RangeError(`method must be 'min-max' or 'z-score', got ${String(method)}`);
     }
     return {
         values,

package/dist/utility/normalize.js.map

@@ -1 +1 @@
-{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../src/utility/normalize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGtC,MAAM,UAAU,SAAS,CAAC,KAAqB;IAC7C,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IAC/B,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAE5C,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;IACtB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IAC9B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IACnE,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAEnC,IAAI,MAAgB,CAAC;IAErB,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,GAAG,GAAG,GAAG,CAAC;QACxB,MAAM,GAAG,KAAK,KAAK,CAAC;YAClB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YACnB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IACrD,CAAC;SAAM,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,GAAG,MAAM,KAAK,CAAC;YACnB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YACnB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IACvD,CAAC;SAAM,CAAC;QACN,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO;QACL,MAAM;QACN,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACpB,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACpB,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QACtB,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;KAC3B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../src/utility/normalize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGtC;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,KAAqB;IAC7C,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IAC/B,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,UAAU,CAAC,sCAAsC,CAAC,CAAC;IAC/D,CAAC;IAED,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;IACtB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IAC9B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IACnE,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAEnC,IAAI,MAAgB,CAAC;IAErB,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,GAAG,GAAG,GAAG,CAAC;QACxB,MAAM,GAAG,KAAK,KAAK,CAAC;YAClB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YACnB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IACrD,CAAC;SAAM,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,GAAG,MAAM,KAAK,CAAC;YACnB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YACnB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IACvD,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,UAAU,CAAC,8CAA8C,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACvF,CAAC;IAED,OAAO;QACL,MAAM;QACN,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACpB,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACpB,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QACtB,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;KAC3B,CAAC;AACJ,CAAC"}

package/dist/utility/npv.d.ts

@@ -1,3 +1,11 @@
 import type { NpvInput, NpvResult } from './types.js';
-export declare function npv(input: NpvInput): NpvResult | null;
+/**
+ * Calculate net present value (NPV), IRR, and profitability index
+ *
+ * @param input - Initial investment, cash flow series, and discount rate
+ * @returns NPV result (irr is null when the IRR iteration does not converge)
+ * @throws RangeError if initialInvestment is negative, cashFlows is empty,
+ *   or discountRate is outside [0, 1)
+ */
+export declare function npv(input: NpvInput): NpvResult;
 //# sourceMappingURL=npv.d.ts.map

package/dist/utility/npv.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"npv.d.ts","sourceRoot":"","sources":["../../src/utility/npv.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEtD,wBAAgB,GAAG,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,IAAI,CAqBrD"}
+{"version":3,"file":"npv.d.ts","sourceRoot":"","sources":["../../src/utility/npv.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;;;;GAOG;AACH,wBAAgB,GAAG,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,CA4B9C"}

package/dist/utility/npv.js

@@ -1,10 +1,23 @@
 import { roundTo } from '../utils.js';
+/**
+ * Calculate net present value (NPV), IRR, and profitability index
+ *
+ * @param input - Initial investment, cash flow series, and discount rate
+ * @returns NPV result (irr is null when the IRR iteration does not converge)
+ * @throws RangeError if initialInvestment is negative, cashFlows is empty,
+ *   or discountRate is outside [0, 1)
+ */
 export function npv(input) {
     const { initialInvestment, cashFlows, discountRate } = input;
-    if (initialInvestment < 0 || !cashFlows || cashFlows.length === 0)
-        return null;
-    if (discountRate < 0 || discountRate >= 1)
-        return null;
+    if (initialInvestment < 0) {
+        throw new RangeError(`initialInvestment must be >= 0, got ${initialInvestment}`);
+    }
+    if (!cashFlows || cashFlows.length === 0) {
+        throw new RangeError('cashFlows must contain at least one value');
+    }
+    if (discountRate < 0 || discountRate >= 1) {
+        throw new RangeError(`discountRate must be in [0, 1), got ${discountRate}`);
+    }
     const pvCashFlows = cashFlows.reduce((acc, cf, i) => {
         return acc + cf / (1 + discountRate) ** (i + 1);
     }, 0);

package/dist/utility/npv.js.map

@@ -1 +1 @@
-{"version":3,"file":"npv.js","sourceRoot":"","sources":["../../src/utility/npv.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGtC,MAAM,UAAU,GAAG,CAAC,KAAe;IACjC,MAAM,EAAE,iBAAiB,EAAE,SAAS,EAAE,YAAY,EAAE,GAAG,KAAK,CAAC;IAC7D,IAAI,iBAAiB,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/E,IAAI,YAAY,GAAG,CAAC,IAAI,YAAY,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAEvD,MAAM,WAAW,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE;QAClD,OAAO,GAAG,GAAG,EAAE,GAAG,CAAC,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAClD,CAAC,EAAE,CAAC,CAAC,CAAC;IAEN,MAAM,QAAQ,GAAG,WAAW,GAAG,iBAAiB,CAAC;IAEjD,MAAM,OAAO,GAAG,WAAW,CAAC;IAC5B,MAAM,kBAAkB,GAAG,iBAAiB,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,iBAAiB,CAAC;IAErF,MAAM,GAAG,GAAG,YAAY,CAAC,iBAAiB,EAAE,SAAS,CAAC,CAAC;IAEvD,OAAO;QACL,GAAG,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;QACzB,GAAG,EAAE,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI;QAC1C,kBAAkB,EAAE,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;KACnD,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CAAC,UAAkB,EAAE,SAAmB;IAC3D,oCAAoC;IACpC,IAAI,IAAI,GAAG,GAAG,CAAC,CAAC,gBAAgB;IAChC,MAAM,OAAO,GAAG,GAAG,CAAC;IACpB,MAAM,SAAS,GAAG,IAAI,CAAC;IAEvB,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC;QAC1C,IAAI,MAAM,GAAG,CAAC,UAAU,CAAC;QACzB,IAAI,UAAU,GAAG,CAAC,CAAC;QAEnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC1C,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAChB,MAAM,UAAU,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;YAClD,MAAM,IAAI,UAAU,CAAC;YACrB,UAAU,IAAI,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACzD,CAAC;QAED,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS;YAAE,OAAO,IAAI,CAAC;QAC9C,IAAI,UAAU,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAElC,IAAI,GAAG,IAAI,GAAG,MAAM,GAAG,UAAU,CAAC;QAElC,IAAI,IAAI,IAAI,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC,CAAC,WAAW;IAC1C,CAAC;IAED,OAAO,IAAI,CAAC,CAAC,mBAAmB;AAClC,CAAC"}
+{"version":3,"file":"npv.js","sourceRoot":"","sources":["../../src/utility/npv.ts"],"names":[],"mappings":"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"}

package/dist/utility/percentile.d.ts

@@ -1,3 +1,10 @@
 import type { PercentileInput, PercentileResult } from './types.js';
-export declare function percentile(input: PercentileInput): PercentileResult | null;
+/**
+ * Calculate a percentile of a data series (linear interpolation between ranks)
+ *
+ * @param input - Data series and percentile (0-100)
+ * @returns Percentile result
+ * @throws RangeError if data is empty or percentile is outside [0, 100]
+ */
+export declare function percentile(input: PercentileInput): PercentileResult;
 //# sourceMappingURL=percentile.d.ts.map

package/dist/utility/percentile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"percentile.d.ts","sourceRoot":"","sources":["../../src/utility/percentile.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEpE,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,GAAG,IAAI,CAsB1E"}
+{"version":3,"file":"percentile.d.ts","sourceRoot":"","sources":["../../src/utility/percentile.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEpE;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,CA0BnE"}

package/dist/utility/percentile.js

@@ -1,10 +1,19 @@
 import { roundTo } from '../utils.js';
+/**
+ * Calculate a percentile of a data series (linear interpolation between ranks)
+ *
+ * @param input - Data series and percentile (0-100)
+ * @returns Percentile result
+ * @throws RangeError if data is empty or percentile is outside [0, 100]
+ */
 export function percentile(input) {
     const { data, percentile: p } = input;
-    if (!data || data.length === 0)
-        return null;
-    if (p < 0 || p > 100)
-        return null;
+    if (!data || data.length === 0) {
+        throw new RangeError('data must contain at least one value');
+    }
+    if (p < 0 || p > 100) {
+        throw new RangeError(`percentile must be in [0, 100], got ${p}`);
+    }
     const sorted = [...data].sort((a, b) => a - b);
     const n = sorted.length;
     if (p === 0)

package/dist/utility/percentile.js.map

@@ -1 +1 @@
-{"version":3,"file":"percentile.js","sourceRoot":"","sources":["../../src/utility/percentile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGtC,MAAM,UAAU,UAAU,CAAC,KAAsB;IAC/C,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,GAAG,KAAK,CAAC;IACtC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG;QAAE,OAAO,IAAI,CAAC;IAElC,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/C,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC;IAExB,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IACxD,IAAI,CAAC,KAAK,GAAG;QAAE,OAAO,EAAE,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;IAE9D,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACjC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAG,IAAI,GAAG,KAAK,CAAC;IAE1B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAErE,OAAO;QACL,UAAU,EAAE,CAAC;QACb,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;KACzB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"percentile.js","sourceRoot":"","sources":["../../src/utility/percentile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGtC;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,KAAsB;IAC/C,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,GAAG,KAAK,CAAC;IACtC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,UAAU,CAAC,sCAAsC,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;QACrB,MAAM,IAAI,UAAU,CAAC,uCAAuC,CAAC,EAAE,CAAC,CAAC;IACnE,CAAC;IAED,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/C,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC;IAExB,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IACxD,IAAI,CAAC,KAAK,GAAG;QAAE,OAAO,EAAE,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;IAE9D,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACjC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAG,IAAI,GAAG,KAAK,CAAC;IAE1B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAErE,OAAO;QACL,UAAU,EAAE,CAAC;QACb,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;KACzB,CAAC;AACJ,CAAC"}

package/dist/utility/regression.d.ts

@@ -1,3 +1,11 @@
 import type { RegressionInput, RegressionResult } from './types.js';
-export declare function regression(input: RegressionInput): RegressionResult | null;
+/**
+ * Simple linear regression (least squares)
+ *
+ * @param input - Regression input with x and y data arrays
+ * @returns Slope, intercept, R² and equation string
+ * @throws RangeError if x or y is missing, if x and y lengths differ,
+ *   if fewer than 2 data points are provided, or if all x values are identical
+ */
+export declare function regression(input: RegressionInput): RegressionResult;
 //# sourceMappingURL=regression.d.ts.map

package/dist/utility/regression.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"regression.d.ts","sourceRoot":"","sources":["../../src/utility/regression.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEpE,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,GAAG,IAAI,CA2C1E"}
+{"version":3,"file":"regression.d.ts","sourceRoot":"","sources":["../../src/utility/regression.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEpE;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,CAqDnE"}

package/dist/utility/regression.js

@@ -1,8 +1,23 @@
 import { roundTo } from '../utils.js';
+/**
+ * Simple linear regression (least squares)
+ *
+ * @param input - Regression input with x and y data arrays
+ * @returns Slope, intercept, R² and equation string
+ * @throws RangeError if x or y is missing, if x and y lengths differ,
+ *   if fewer than 2 data points are provided, or if all x values are identical
+ */
 export function regression(input) {
     const { x, y } = input;
-    if (!x || !y || x.length !== y.length || x.length < 2)
-        return null;
+    if (!x || !y) {
+        throw new RangeError('x and y data arrays are required');
+    }
+    if (x.length !== y.length) {
+        throw new RangeError(`x and y must have the same length, got ${x.length} and ${y.length}`);
+    }
+    if (x.length < 2) {
+        throw new RangeError(`at least 2 data points are required, got ${x.length}`);
+    }
     const n = x.length;
     const meanX = x.reduce((a, v) => a + v, 0) / n;
     const meanY = y.reduce((a, v) => a + v, 0) / n;
@@ -16,8 +31,9 @@ export function regression(input) {
         sumX2 += dx * dx;
         sumY2 += dy * dy;
     }
-    if (sumX2 === 0)
-        return null;
+    if (sumX2 === 0) {
+        throw new RangeError('x values must not all be identical (zero variance in x)');
+    }
     const slope = sumXY / sumX2;
     const intercept = meanY - slope * meanX;
     const ssTot = sumY2;