@eveshipfit/dogma-engine 11.2.0 → 13.0.0

package/README.md

@@ -74,6 +74,7 @@ All identifiers are those from the SDE.
 
 - `sources` (optional, default false): report per attribute what its value was calculated from.
   Leave it off unless you show it; it makes the calculation several times bigger.
+- `validate` (optional, default false): also report the fitting rules the fit breaks, as `violations`.
 
 ### Calculation
 
@@ -85,6 +86,8 @@ All identifiers are those from the SDE.
   - `id`: which buff, as `dbuffCollections` in the SDE numbers them.
   - `value`: how strong it is, in whatever the buff's operation reads.
 - `outgoing`: what the fit hands to other fits, in the shape `incoming` takes.
+- `violations`: the fitting rules the fit breaks; only with the `validate` option.
+  Absent means they were not looked for, an empty list means none were broken.
 
 Each result has:
 
@@ -114,9 +117,12 @@ What additional attributes exist are defined in [EVEShipFit/sde-patched](https:/
 
 ## Validation
 
-`validate()` checks if the fit violates any rules that would prevent you from flying it in-game.
-It returns the violations, grouped by the kind of rule and, within a kind, in the order of `items`.
-An empty list means the fit breaks no rules.
+The `validate` option checks if the fit violates any rules that would prevent you from flying it in-game.
+The calculation then carries `violations`, grouped by the kind of rule and, within a kind, in the order of `items`.
+An empty list means the fit breaks no rules; absent means the option was off.
+
+Every rule reads the values after skills and modules changed them, so validation is part of `calculate()`
+rather than a call of its own; asking for both costs one calculation, not two.
 
 Each violation has:
 
@@ -162,7 +168,7 @@ cargo add esf-dogma-engine esf-data
 
 ```rust
 use esf_data::{InfoSde, Sde};
-use esf_dogma_engine::{Fit, Options, beacon, calculate, validate};
+use esf_dogma_engine::{Fit, Options, beacon, calculate};
 
 let bytes = std::fs::read("sde.dat")?;
 let sde = Sde::new(&bytes)?;
@@ -189,8 +195,8 @@ let with_sources = calculate(&info, &fit, &Options { sources: true, ..Default::d
 // Or if you have a beacon in space (like wormhole effects):
 let with_beacon = calculate(&info, &Fit { incoming: beacon(&info, beacon_type_id), ..fit }, &Options::default());
 
-// What EVE would not let you fly:
-let violations = validate(&info, &fit, &calculation);
+// What EVE would not let you fly, in `violations` of the calculation:
+let validated = calculate(&info, &fit, &Options { validate: true, ..Default::default() });
 ```
 
 ### Javascript (WebAssembly)
@@ -199,24 +205,24 @@ The WebAssembly variant is published on npm as
 [`@eveshipfit/dogma-engine`](https://www.npmjs.com/package/@eveshipfit/dogma-engine).
 [`@eveshipfit/sde`](https://www.npmjs.com/package/@eveshipfit/sde) ships `sde.dat` in its `dist` folder; serve or bundle that file.
 
-The package is built for bundlers (Vite, webpack 5, ...), which load the `.wasm` themselves.
+The package is an ES module with TypeScript types included, and it runs anywhere: under a bundler
+(Vite, webpack, ...), from a CDN, or in a plain `<script type="module">`.
+Its default export loads the WebAssembly and has to be awaited once before any other function is called.
 
 ```bash
 npm install @eveshipfit/dogma-engine @eveshipfit/sde
 ```
 
 ```js
-import {
-  init,
+import wasmInit, {
   load_sde,
   load_eft,
   save_eft,
   calculate,
-  validate,
   beacon,
 } from "@eveshipfit/dogma-engine";
 
-init();
+await wasmInit();
 
 const sde = await fetch("/sde.dat").then((response) => response.arrayBuffer());
 const buildNumber = load_sde(new Uint8Array(sde));
@@ -236,8 +242,8 @@ const imported = calculate(load_eft("[Rifter, My Rifter]\n200mm AutoCannon I"));
 /* And to write a fit back out as EFT: */
 const eft = save_eft(fit);
 
-/* What EVE would not let you fly; it calculates the fit itself: */
-const violations = validate(fit);
+/* What EVE would not let you fly, in `violations` of the calculation: */
+const validated = calculate(fit, { validate: true });
 ```
 
 ### Python
@@ -279,8 +285,8 @@ imported = dogma.calculate(dogma.load_eft("[Rifter, My Rifter]\n200mm AutoCannon
 # And to write a fit back out as EFT:
 eft = dogma.save_eft(fit)
 
-# What EVE would not let you fly; it calculates the fit itself:
-violations = dogma.validate(fit)
+# What EVE would not let you fly, in `violations` of the calculation:
+validated = dogma.calculate(fit, {"validate": True})
 ```
 
 Fits and calculations are plain dicts, typed with `TypedDict` in `esf_dogma_engine.types`.
@@ -366,7 +372,7 @@ This is done with [wasm-pack](https://rustwasm.github.io/wasm-pack/):
 
 ```bash
 cargo install wasm-pack
-wasm-pack build crates/esf-wasm --release --out-dir ../../pkg
+wasm-pack build crates/esf-wasm --release --target web --out-dir ../../pkg
 ```
 
 In the `pkg` folder is now a NPM module to use.

package/esf_dogma_engine.d.ts

@@ -340,6 +340,10 @@ export interface Calculation {
      * All outgoing projections (effects and buffs).
      */
     outgoing?: Projection;
+    /**
+     * The fitting rules the fit breaks; only with `Options::validate`.
+     */
+    violations?: Violation[];
 }
 
 /**
@@ -374,6 +378,10 @@ export interface Options {
      * Report per attribute the modifiers its value was calculated from.
      */
     sources?: boolean;
+    /**
+     * Report the fitting rules the fit breaks.
+     */
+    validate?: boolean;
 }
 
 /**
@@ -437,8 +445,6 @@ export function beacon(type_id: number): Projection;
  */
 export function calculate(fit: Fit, options?: Options | null): Calculation;
 
-export function init(): void;
-
 /**
  * Load a fit from EFT, the text format EVE copies a fit to the clipboard in.
  */
@@ -462,8 +468,47 @@ export function load_sde(bytes: Uint8Array): number;
  */
 export function save_eft(fit: Fit): string;
 
+export function set_panic_hook(): void;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly beacon: (a: number) => [number, number, number];
+    readonly calculate: (a: any, b: number) => [number, number, number];
+    readonly load_eft: (a: number, b: number) => [number, number, number];
+    readonly load_names: (a: number, b: number) => [number, number, number];
+    readonly load_sde: (a: number, b: number) => [number, number, number];
+    readonly save_eft: (a: any) => [number, number, number, number];
+    readonly set_panic_hook: () => void;
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_exn_store: (a: number) => void;
+    readonly __externref_table_alloc: () => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
 /**
- * Report the fitting rules the fit breaks. Calculates the fit itself, as
- * every rule reads the values after skills and modules changed them.
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
  */
-export function validate(fit: Fit): Violation[];
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;