@iyulab/u-numflow 0.6.4 → 0.7.0

package/README.md

@@ -103,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 |
@@ -126,6 +131,27 @@ 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 parameter and return types, and the

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
@@ -292,10 +292,18 @@ function __wbg_get_imports() {
         __wbg___wbindgen_throw_41e9ee4f547fc59a: function(arg0, arg1) {
             throw new Error(getStringFromWasm0(arg0, arg1));
         },
+        __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.4",
+  "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
@@ -272,10 +272,18 @@ export function __wbg_String_8564e559799eccda(arg0, arg1) {
 export function __wbg___wbindgen_throw_41e9ee4f547fc59a(arg0, arg1) {
     throw new Error(getStringFromWasm0(arg0, arg1));
 }
+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);