@iyulab/u-numflow 0.6.3 → 0.7.0

package/README.md

@@ -38,31 +38,34 @@ u-numflow = "0.2"
 ```
 
 ```rust
-use u_numflow::stats::OnlineStats;
-use u_numflow::distributions::{PertDistribution, Distribution};
-use u_numflow::random::Rng;
+use u_numflow::distributions::Pert;
+use u_numflow::random::{create_rng, shuffle};
+use u_numflow::stats::WelfordAccumulator;
 
-// Online statistics with numerical stability
-let mut stats = OnlineStats::new();
+// Online statistics with numerical stability (Welford)
+let mut stats = WelfordAccumulator::new();
 for x in [1.0, 2.0, 3.0, 4.0, 5.0] {
-    stats.push(x);
+    stats.update(x);
 }
-assert_eq!(stats.mean(), 3.0);
+assert_eq!(stats.mean(), Some(3.0));
 
-// PERT distribution sampling
-let pert = PertDistribution::new(1.0, 4.0, 7.0);
-let mut rng = Rng::seed_from_u64(42);
-let sample = pert.sample(&mut rng);
+// PERT distribution: moments and quantiles; sample by inverting a uniform draw
+let pert = Pert::new(1.0, 4.0, 7.0).unwrap();
+assert_eq!(pert.mean(), 4.0);
+let p90 = pert.quantile(0.9).unwrap();
+assert!(p90 > 4.0 && p90 < 7.0);
 
 // Seeded shuffling for reproducibility
+let mut rng = create_rng(42);
 let mut items = vec![1, 2, 3, 4, 5];
-u_numflow::random::shuffle(&mut items, &mut rng);
+shuffle(&mut items, &mut rng);
 
 // Box-Cox transformation (non-normal data normalization)
-use u_numflow::transforms::{estimate_lambda, box_cox};
+use u_numflow::transforms::{box_cox, estimate_lambda};
 let data = [1.0, 2.0, 4.0, 8.0, 16.0];
-let lambda = estimate_lambda(&data, -2.0, 2.0).unwrap(); // MLE via golden-section
-let transformed = box_cox(&data, lambda).unwrap();
+let fit = estimate_lambda(&data, -2.0, 2.0).unwrap(); // MLE via golden-section
+let transformed = box_cox(&data, fit.lambda).unwrap();
+assert_eq!(transformed.len(), data.len());
 
 // Discrete Fourier transform of any length
 use u_numflow::fourier::rfft;
@@ -100,12 +103,17 @@ The package resolves per environment via a conditional `exports` map:
 | Bundlers (webpack, Vite, …) | ESM + WebAssembly ESM-integration (`default` condition) |
 | Node.js — `require()`, ESM `import`, CJS TS runners (`tsx`, `ts-node`) | CJS glue loading the wasm from the filesystem (`node` condition) — no loader hooks or flags |
 
+A browser **without** a bundler is not supported: the package loads its `.wasm`
+file with an ES module import, which browsers refuse (`application/wasm` is not a
+module script type), so `<script type="module">` from a CDN fails, and CDN
+re-bundling services fail on the same import. Use a bundler or Node.
+
 Exported functions: `mean`, `std_dev`, `variance`, `normal_cdf`, `normal_sf` (upper tail `P(Z > x)`, computed directly so tail probabilities keep ~15 significant digits), `box_cox`, `estimate_lambda` (returns `{ lambda, at_bound }` — `at_bound` is `true` when the likelihood was still rising at an end of the search range, so `lambda` is that limit), and
 `rfft(data) -> Float64Array` — the DFT of a real sequence of any length, interleaved as
 `[re0, im0, re1, im1, …]` (bins `k` and `n − k` are conjugates, so `0..=n/2` describes the spectrum).
 
 Distribution functions for critical values and p-values — each returns a `number` and
-**throws** (a message naming the argument) when an argument is outside the domain,
+**throws** (an `Error` naming the argument — see *Errors* below) when an argument is outside the domain,
 rather than returning `NaN`:
 
 | Function | Returns |
@@ -123,22 +131,45 @@ const { t_distribution_quantile } = require("@iyulab/u-numflow");
 t_distribution_quantile(0.975, 10); // 2.2281…
 ```
 
+**Errors.** A refusal throws an `Error` whose `message` is readable text and which
+carries a `code` naming the reason, next to the values behind it:
+
+```js
+const { t_distribution_quantile } = require("@iyulab/u-numflow");
+try {
+  t_distribution_quantile(1.5, 10);
+} catch (err) {
+  console.log(err.code, err.parameter, err.min, err.max, err.got); // parameter_out_of_range p 0 1 1.5
+}
+```
+
+| `code` | Fields | Meaning |
+|---|---|---|
+| `parameter_out_of_range` | `parameter`, `min`, `max` (or `null`), `got` | `p` not strictly inside (0, 1), or a degrees of freedom that is not a finite number `> 0` (both bounds excluded) |
+| `value_not_finite` | `parameter` (for a scalar argument) | A NaN argument, or a NaN or infinity in `box_cox`/`estimate_lambda` data |
+| `non_positive_data` | — | Box-Cox data with a value `≤ 0` |
+| `insufficient_data` | — | Box-Cox data with fewer than 2 values |
+| `invalid_transform` | — | A Box-Cox result that is not finite |
+| `invalid_lambda_range` | — | `estimate_lambda` bounds that are not finite with `lambda_min < lambda_max` |
+
 ### TypeScript
 
-Every exported function declares its return type, and the declarations are
-generated from the same structs the binding serialises, so they cannot drift
-from what it actually returns:
+Every exported function declares its parameter and return types, and the
+declarations are generated from the same structs the binding reads and
+serialises, so they cannot drift from what it actually accepts and returns:
 
 ```ts
-export function estimate_lambda(data: any): LambdaEstimateDto;
+export function estimate_lambda(data: Float64Array, lambda_min: number, lambda_max: number): LambdaEstimateDto;
 ```
 
 An absent optional value is declared `T | undefined`, which is what the binding
 sends. Nothing needs an `as` cast -- and a wrong assumption about a result's
 shape is a compile error rather than something that fails at run time.
 
-Inputs are still `any`: they are validated at the boundary, and a rejected one
-says what was wrong.
+Every parameter is a number or a `Float64Array`, so there is nothing to
+declare beyond what wasm-bindgen already does; the publishing workflow keeps it
+that way. The binding still validates every input at the boundary, and a
+rejected one says what was wrong.
 
 ## Related
 

package/node/u_numflow.cjs

@@ -6,8 +6,9 @@
  * All values in `data` must be strictly positive.
  *
  * # Errors
- * Returns a `JsValue` error string if data contains non-positive values or
- * has fewer than 2 elements.
+ * Throws `non_positive_data`, `value_not_finite` or `insufficient_data` when
+ * data contains a value ≤ 0, a NaN or infinity, or fewer than 2 elements, and
+ * `invalid_transform` when a result is not finite.
  * @param {Float64Array} data
  * @param {number} lambda
  * @returns {Float64Array}
@@ -72,9 +73,8 @@ exports.chi_squared_quantile = chi_squared_quantile;
  * interior estimate; widen the range to find the unconstrained optimum.
  *
  * # Errors
- * Returns a `JsValue` error string if data contains non-positive values,
- * has fewer than 2 elements, or the range is not finite with
- * `lambda_min < lambda_max`.
+ * Throws as [`box_cox`] does for the data, and `invalid_lambda_range` when the
+ * range is not finite with `lambda_min < lambda_max`.
  * @param {Float64Array} data
  * @param {number} lambda_min
  * @param {number} lambda_max
@@ -289,13 +289,21 @@ function __wbg_get_imports() {
             getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
         },
-        __wbg___wbindgen_throw_5d9e815e6fdf150f: function(arg0, arg1) {
+        __wbg___wbindgen_throw_41e9ee4f547fc59a: function(arg0, arg1) {
             throw new Error(getStringFromWasm0(arg0, arg1));
         },
-        __wbg_new_bebc3f4757acf305: function() {
+        __wbg_new_343a093a3c2ffb4e: function(arg0, arg1) {
+            const ret = new Error(getStringFromWasm0(arg0, arg1));
+            return ret;
+        },
+        __wbg_new_617a8cdb8bb1130e: function() {
             const ret = new Object();
             return ret;
         },
+        __wbg_set_145a351398b48c65: function() { return handleError(function (arg0, arg1, arg2) {
+            const ret = Reflect.set(arg0, arg1, arg2);
+            return ret;
+        }, arguments); },
         __wbg_set_6be42768c690e380: function(arg0, arg1, arg2) {
             arg0[arg1] = arg2;
         },
@@ -325,6 +333,12 @@ function __wbg_get_imports() {
     };
 }
 
+function addToExternrefTable0(obj) {
+    const idx = wasm.__externref_table_alloc();
+    wasm.__wbindgen_externrefs.set(idx, obj);
+    return idx;
+}
+
 function getArrayF64FromWasm0(ptr, len) {
     ptr = ptr >>> 0;
     return getFloat64ArrayMemory0().subarray(ptr / 8, ptr / 8 + len);
@@ -358,6 +372,15 @@ function getUint8ArrayMemory0() {
     return cachedUint8ArrayMemory0;
 }
 
+function handleError(f, args) {
+    try {
+        return f.apply(this, args);
+    } catch (e) {
+        const idx = addToExternrefTable0(e);
+        wasm.__wbindgen_exn_store(idx);
+    }
+}
+
 function passArrayF64ToWasm0(arg, malloc) {
     const ptr = malloc(arg.length * 8, 8) >>> 0;
     getFloat64ArrayMemory0().set(arg, ptr / 8);

package/node/u_numflow.d.cts

@@ -15,8 +15,9 @@ export interface LambdaEstimateDto {
  * All values in `data` must be strictly positive.
  *
  * # Errors
- * Returns a `JsValue` error string if data contains non-positive values or
- * has fewer than 2 elements.
+ * Throws `non_positive_data`, `value_not_finite` or `insufficient_data` when
+ * data contains a value ≤ 0, a NaN or infinity, or fewer than 2 elements, and
+ * `invalid_transform` when a result is not finite.
  */
 export function box_cox(data: Float64Array, lambda: number): Float64Array;
 
@@ -47,9 +48,8 @@ export function chi_squared_quantile(p: number, k: number): number;
  * interior estimate; widen the range to find the unconstrained optimum.
  *
  * # Errors
- * Returns a `JsValue` error string if data contains non-positive values,
- * has fewer than 2 elements, or the range is not finite with
- * `lambda_min < lambda_max`.
+ * Throws as [`box_cox`] does for the data, and `invalid_lambda_range` when the
+ * range is not finite with `lambda_min < lambda_max`.
  */
 export function estimate_lambda(data: Float64Array, lambda_min: number, lambda_max: number): LambdaEstimateDto;
 

package/package.json

@@ -5,7 +5,7 @@
     "iyulab"
   ],
   "description": "Foundational mathematical primitives: statistics, probability distributions, random sampling, and collections.",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/u_numflow.d.ts

@@ -15,8 +15,9 @@ export interface LambdaEstimateDto {
  * All values in `data` must be strictly positive.
  *
  * # Errors
- * Returns a `JsValue` error string if data contains non-positive values or
- * has fewer than 2 elements.
+ * Throws `non_positive_data`, `value_not_finite` or `insufficient_data` when
+ * data contains a value ≤ 0, a NaN or infinity, or fewer than 2 elements, and
+ * `invalid_transform` when a result is not finite.
  */
 export function box_cox(data: Float64Array, lambda: number): Float64Array;
 
@@ -47,9 +48,8 @@ export function chi_squared_quantile(p: number, k: number): number;
  * interior estimate; widen the range to find the unconstrained optimum.
  *
  * # Errors
- * Returns a `JsValue` error string if data contains non-positive values,
- * has fewer than 2 elements, or the range is not finite with
- * `lambda_min < lambda_max`.
+ * Throws as [`box_cox`] does for the data, and `invalid_lambda_range` when the
+ * range is not finite with `lambda_min < lambda_max`.
  */
 export function estimate_lambda(data: Float64Array, lambda_min: number, lambda_max: number): LambdaEstimateDto;
 

package/u_numflow_bg.js

@@ -4,8 +4,9 @@
  * All values in `data` must be strictly positive.
  *
  * # Errors
- * Returns a `JsValue` error string if data contains non-positive values or
- * has fewer than 2 elements.
+ * Throws `non_positive_data`, `value_not_finite` or `insufficient_data` when
+ * data contains a value ≤ 0, a NaN or infinity, or fewer than 2 elements, and
+ * `invalid_transform` when a result is not finite.
  * @param {Float64Array} data
  * @param {number} lambda
  * @returns {Float64Array}
@@ -67,9 +68,8 @@ export function chi_squared_quantile(p, k) {
  * interior estimate; widen the range to find the unconstrained optimum.
  *
  * # Errors
- * Returns a `JsValue` error string if data contains non-positive values,
- * has fewer than 2 elements, or the range is not finite with
- * `lambda_min < lambda_max`.
+ * Throws as [`box_cox`] does for the data, and `invalid_lambda_range` when the
+ * range is not finite with `lambda_min < lambda_max`.
  * @param {Float64Array} data
  * @param {number} lambda_min
  * @param {number} lambda_max
@@ -269,13 +269,21 @@ export function __wbg_String_8564e559799eccda(arg0, arg1) {
     getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
     getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
 }
-export function __wbg___wbindgen_throw_5d9e815e6fdf150f(arg0, arg1) {
+export function __wbg___wbindgen_throw_41e9ee4f547fc59a(arg0, arg1) {
     throw new Error(getStringFromWasm0(arg0, arg1));
 }
-export function __wbg_new_bebc3f4757acf305() {
+export function __wbg_new_343a093a3c2ffb4e(arg0, arg1) {
+    const ret = new Error(getStringFromWasm0(arg0, arg1));
+    return ret;
+}
+export function __wbg_new_617a8cdb8bb1130e() {
     const ret = new Object();
     return ret;
 }
+export function __wbg_set_145a351398b48c65() { return handleError(function (arg0, arg1, arg2) {
+    const ret = Reflect.set(arg0, arg1, arg2);
+    return ret;
+}, arguments); }
 export function __wbg_set_6be42768c690e380(arg0, arg1, arg2) {
     arg0[arg1] = arg2;
 }
@@ -298,6 +306,12 @@ export function __wbindgen_init_externref_table() {
     table.set(offset + 2, true);
     table.set(offset + 3, false);
 }
+function addToExternrefTable0(obj) {
+    const idx = wasm.__externref_table_alloc();
+    wasm.__wbindgen_externrefs.set(idx, obj);
+    return idx;
+}
+
 function getArrayF64FromWasm0(ptr, len) {
     ptr = ptr >>> 0;
     return getFloat64ArrayMemory0().subarray(ptr / 8, ptr / 8 + len);
@@ -331,6 +345,15 @@ function getUint8ArrayMemory0() {
     return cachedUint8ArrayMemory0;
 }
 
+function handleError(f, args) {
+    try {
+        return f.apply(this, args);
+    } catch (e) {
+        const idx = addToExternrefTable0(e);
+        wasm.__wbindgen_exn_store(idx);
+    }
+}
+
 function passArrayF64ToWasm0(arg, malloc) {
     const ptr = malloc(arg.length * 8, 8) >>> 0;
     getFloat64ArrayMemory0().set(arg, ptr / 8);