@iyulab/u-metaheur 0.4.0 → 0.4.1

package/README.md

@@ -98,6 +98,23 @@ 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 |
 
+### 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:
+
+```ts
+export function run_ga(problem: any): GaResult;
+```
+
+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.
+
 ## Related
 
 - [u-numflow](https://github.com/iyulab/u-numflow) — Mathematical primitives

package/node/u_metaheur.cjs

@@ -13,7 +13,7 @@
  * # Returns
  * JS object with `best_distance`, `best_tour`, `generations_run`.
  * @param {any} config
- * @returns {any}
+ * @returns {GaResult}
  */
 function run_ga(config) {
     const ret = wasm.run_ga(config);
@@ -40,7 +40,7 @@ exports.run_ga = run_ga;
  * # Returns
  * JS object with `best_distance`, `best_tour`, `iterations_run`.
  * @param {any} config
- * @returns {any}
+ * @returns {SaResult}
  */
 function run_sa(config) {
     const ret = wasm.run_sa(config);

package/node/u_metaheur.d.cts

@@ -1,5 +1,17 @@
 /* tslint:disable */
 /* eslint-disable */
+export interface GaResult {
+    best_distance: number;
+    best_tour: number[];
+    generations_run: number;
+}
+
+export interface SaResult {
+    best_distance: number;
+    best_tour: number[];
+    iterations_run: number;
+}
+
 
 /**
  * Runs a Genetic Algorithm for TSP.
@@ -14,7 +26,7 @@
  * # Returns
  * JS object with `best_distance`, `best_tour`, `generations_run`.
  */
-export function run_ga(config: any): any;
+export function run_ga(config: any): GaResult;
 
 /**
  * Runs Simulated Annealing for TSP.
@@ -32,4 +44,4 @@ export function run_ga(config: any): any;
  * # Returns
  * JS object with `best_distance`, `best_tour`, `iterations_run`.
  */
-export function run_sa(config: any): any;
+export function run_sa(config: any): SaResult;

package/package.json

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

package/u_metaheur.d.ts

@@ -1,5 +1,17 @@
 /* tslint:disable */
 /* eslint-disable */
+export interface GaResult {
+    best_distance: number;
+    best_tour: number[];
+    generations_run: number;
+}
+
+export interface SaResult {
+    best_distance: number;
+    best_tour: number[];
+    iterations_run: number;
+}
+
 
 /**
  * Runs a Genetic Algorithm for TSP.
@@ -14,7 +26,7 @@
  * # Returns
  * JS object with `best_distance`, `best_tour`, `generations_run`.
  */
-export function run_ga(config: any): any;
+export function run_ga(config: any): GaResult;
 
 /**
  * Runs Simulated Annealing for TSP.
@@ -32,4 +44,4 @@ export function run_ga(config: any): any;
  * # Returns
  * JS object with `best_distance`, `best_tour`, `iterations_run`.
  */
-export function run_sa(config: any): any;
+export function run_sa(config: any): SaResult;

package/u_metaheur_bg.js

@@ -11,7 +11,7 @@
  * # Returns
  * JS object with `best_distance`, `best_tour`, `generations_run`.
  * @param {any} config
- * @returns {any}
+ * @returns {GaResult}
  */
 export function run_ga(config) {
     const ret = wasm.run_ga(config);
@@ -37,7 +37,7 @@ export function run_ga(config) {
  * # Returns
  * JS object with `best_distance`, `best_tour`, `iterations_run`.
  * @param {any} config
- * @returns {any}
+ * @returns {SaResult}
  */
 export function run_sa(config) {
     const ret = wasm.run_sa(config);