@iyulab/u-metaheur 0.10.0 → 0.12.0

package/README.md

@@ -78,10 +78,10 @@ assert!((result.best - 3.0).abs() < 0.1);
 
 ```toml
 [dependencies]
-u-metaheur = "0.10"
+u-metaheur = "0.12"
 
 # with serde support
-u-metaheur = { version = "0.10", features = ["serde"] }
+u-metaheur = { version = "0.12", features = ["serde"] }
 ```
 
 ## Build & Test
@@ -142,6 +142,10 @@ console.log(sa.best_distance, sa.iterations_run);
 `cooling_rate`. Every setting is optional except `nodes`, and a setting the
 function does not have is rejected rather than ignored.
 
+`codes()` returns every refusal `code` the functions throw, with the fields that
+can come with it — `{ refusals: [{ code, fields }], violations: [] }` — built from
+the table the refusals come from; the table below explains each.
+
 ### Errors
 
 A refusal throws an `Error` whose `message` is readable text and which carries a
@@ -162,7 +166,8 @@ try {
 | `insufficient_data` | `parameter` (`"nodes"`), `min`, `got` | Fewer than 2 nodes |
 | `parameter_out_of_range` | `parameter`, `min`, `max`, `exclusive_min`, `exclusive_max`, `got` | `population_size < 2`, `generations` or `iterations` below 1 (a negative count included: `population_size: -1` is `{ min: 2, max: null, got: -1 }`, the same as `1`), `initial_temp ≤ 0`, or `cooling_rate` outside (0, 1). `min` / `max` are the closed (included) bounds and are always present — `null` on a side that is open or unbounded; `exclusive_min` / `exclusive_max` are the open (excluded) bounds, present only when that end is open: `initial_temp` (> 0) is refused with `min: null, exclusive_min: 0`, `cooling_rate` with `exclusive_min: 0, exclusive_max: 1` |
 | `value_not_finite` | `parameter`, `index` | A NaN or ±Infinity anywhere in an argument — `parameter` is the path to it (`config.nodes[1]`), `index` its position in that array, or `null` |
-| `malformed_input` | `parameter` | An argument of the wrong shape or type (a missing or unknown key), a count that is not a whole number (`population_size: 2.5` — `parameter` is the field), or a JSON string |
+| `malformed_input` | `parameter`, `index` (inside an array) | An argument of the wrong shape or type (a missing or unknown key), a count that is not a whole number (`population_size: 2.5` — `parameter` is the field), or a JSON string |
+| `internal` | — | A result the package could not hand back — a fault in the package, not in the input; please report it |
 
 ### TypeScript
 

package/node/u_metaheur.cjs

@@ -1,5 +1,22 @@
 /* @ts-self-types="./u_metaheur.d.cts" */
 
+/**
+ * Every refusal `code` the functions of this package throw, with the fields
+ * that can come with it: `{ refusals: [{ code, fields }], violations: [] }`.
+ *
+ * It is built from the table the refusals come from, so a caller that
+ * translates codes can check its list against the package's.
+ * @returns {Codes}
+ */
+function codes() {
+    const ret = wasm.codes();
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+exports.codes = codes;
+
 /**
  * Runs a Genetic Algorithm for TSP.
  *

package/node/u_metaheur.d.cts

@@ -1,5 +1,33 @@
 /* tslint:disable */
 /* eslint-disable */
+/**
+ * A refusal reason: the `code` an `Error` carries and the fields that can
+ * stand beside it.
+ */
+export interface RefusalCode {
+    code: string;
+    fields: string[];
+}
+
+/**
+ * A violation a checker reports. This package has no checker; the type is
+ * here so every engine's [`Codes`] has one shape.
+ */
+export interface ViolationCode {
+    code: string;
+    fields: string[];
+    checkers: string[];
+}
+
+/**
+ * What this package can answer with besides a result: every refusal
+ * `code`, and no violations -- it has no checker.
+ */
+export interface Codes {
+    refusals: RefusalCode[];
+    violations: ViolationCode[];
+}
+
 export interface GaConfig {
     nodes: [number, number][];
     /**
@@ -36,6 +64,15 @@ export interface SaResult {
 }
 
 
+/**
+ * Every refusal `code` the functions of this package throw, with the fields
+ * that can come with it: `{ refusals: [{ code, fields }], violations: [] }`.
+ *
+ * It is built from the table the refusals come from, so a caller that
+ * translates codes can check its list against the package's.
+ */
+export function codes(): Codes;
+
 /**
  * Runs a Genetic Algorithm for TSP.
  *

package/package.json

@@ -5,7 +5,7 @@
     "iyulab"
   ],
   "description": "Domain-agnostic metaheuristic optimization framework: GA, BRKGA, SA, ALNS.",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/u_metaheur.d.ts

@@ -1,5 +1,33 @@
 /* tslint:disable */
 /* eslint-disable */
+/**
+ * A refusal reason: the `code` an `Error` carries and the fields that can
+ * stand beside it.
+ */
+export interface RefusalCode {
+    code: string;
+    fields: string[];
+}
+
+/**
+ * A violation a checker reports. This package has no checker; the type is
+ * here so every engine's [`Codes`] has one shape.
+ */
+export interface ViolationCode {
+    code: string;
+    fields: string[];
+    checkers: string[];
+}
+
+/**
+ * What this package can answer with besides a result: every refusal
+ * `code`, and no violations -- it has no checker.
+ */
+export interface Codes {
+    refusals: RefusalCode[];
+    violations: ViolationCode[];
+}
+
 export interface GaConfig {
     nodes: [number, number][];
     /**
@@ -36,6 +64,15 @@ export interface SaResult {
 }
 
 
+/**
+ * Every refusal `code` the functions of this package throw, with the fields
+ * that can come with it: `{ refusals: [{ code, fields }], violations: [] }`.
+ *
+ * It is built from the table the refusals come from, so a caller that
+ * translates codes can check its list against the package's.
+ */
+export function codes(): Codes;
+
 /**
  * Runs a Genetic Algorithm for TSP.
  *

package/u_metaheur.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./u_metaheur_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    run_ga, run_sa
+    codes, run_ga, run_sa
 } from "./u_metaheur_bg.js";

package/u_metaheur_bg.js

@@ -1,3 +1,19 @@
+/**
+ * Every refusal `code` the functions of this package throw, with the fields
+ * that can come with it: `{ refusals: [{ code, fields }], violations: [] }`.
+ *
+ * It is built from the table the refusals come from, so a caller that
+ * translates codes can check its list against the package's.
+ * @returns {Codes}
+ */
+export function codes() {
+    const ret = wasm.codes();
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * Runs a Genetic Algorithm for TSP.
  *