uesp-eso-build-wrapper 0.2.0 → 0.3.0

package/README.md

@@ -1,10 +1,13 @@
 # uesp-eso-build-wrapper
 
 [![CI](https://github.com/srtomy/uesp-eso-build-wrapper/actions/workflows/ci.yml/badge.svg)](https://github.com/srtomy/uesp-eso-build-wrapper/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/uesp-eso-build-wrapper.svg)](https://www.npmjs.com/package/uesp-eso-build-wrapper)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node >=20.12](https://img.shields.io/badge/node-%3E%3D20.12-brightgreen)](https://nodejs.org/en/download/)
 
 A Node.js/TypeScript wrapper around the [UESP ESO Build Editor](https://github.com/uesp/uesp-esochardata) math engine.
 
-Calculate Elder Scrolls Online **Computed Character Statistics** — Health, Magicka, Stamina, mitigation, crit chance, regeneration, and 200+ more — using UESP's own formulas. No formula reimplementation. No database.
+Calculate Elder Scrolls Online **Computed Character Statistics** — Health, Magicka, Stamina, mitigation, crit chance, regeneration, and 200+ more — using UESP's own formulas. No formula reimplementation.
 
 ## Features
 
@@ -22,11 +25,21 @@ npm install uesp-eso-build-wrapper
 
 ## Quick Start
 
+Game data is not bundled in the npm package — you supply it via `initEsoEngineFromData`.  
+The bundled `vendor/uesp-data/uesp-game-data.json` (committed to this repo) is the canonical source.
+
 ```ts
-import { initEsoEngine, calculateBuild } from 'uesp-eso-build-wrapper';
+import fs from 'fs';
+import { initEsoEngineFromData, calculateBuild } from 'uesp-eso-build-wrapper';
+import type { UespInitData } from 'uesp-eso-build-wrapper';
+
+// Load game data generated by: npm run generate-data -- --db /path/to/local.db
+const initData = JSON.parse(
+  fs.readFileSync('vendor/uesp-data/uesp-game-data.json', 'utf-8')
+) as UespInitData;
 
-// Initialize once — resolves bundled vendor files automatically
-initEsoEngine();
+// Initialize once per process (no-op on subsequent calls)
+initEsoEngineFromData({ initData });
 
 const stats = calculateBuild({
   character: {
@@ -37,10 +50,10 @@ const stats = calculateBuild({
   },
 });
 
-console.log(stats.Health); // 16000
-console.log(stats.Magicka); // 19104
+console.log(stats.Health);       // 16000
+console.log(stats.Magicka);      // 19104
 console.log(stats.MagickaRegen); // 514
-console.log(stats.SpellDamage); // 1000
+console.log(stats.SpellDamage);  // 1000
 ```
 
 ## With Equipped Items
@@ -48,14 +61,12 @@ console.log(stats.SpellDamage); // 1000
 Items are passed directly as returned by the [UESP public item API](https://esolog.uesp.net/exportJson.php?table=minedItem&id=70&level=50&quality=5).
 
 ```ts
-// 1. Fetch item data from UESP API
 const res = await fetch(
   'https://esolog.uesp.net/exportJson.php?table=minedItem&id=70&level=50&quality=5',
 );
 const data = await res.json();
-const item = data.minedItem[0]; // pick the variant you want
+const item = data.minedItem[0];
 
-// 2. Pass it directly — no mapping needed
 const stats = calculateBuild({
   character: {
     race: 'Nord',
@@ -71,18 +82,45 @@ const stats = calculateBuild({
 console.log(stats.Health); // includes item enchant + set bonus
 ```
 
+## With Passives, Buffs, and Skill Bars
+
+```ts
+const stats = calculateBuild({
+  character: {
+    race: 'High Elf',
+    class: 'Sorcerer',
+    level: 50,
+    attributes: { health: 0, magicka: 64, stamina: 0 },
+    mundusStone: 'The Apprentice',
+    championPoints: 160,
+  },
+  // Auto-inject all racial passives at highest rank (mirrors UESP "Auto Purchase Racial Passives")
+  autoPassives: true,
+  // Named buffs from the UESP buff catalog
+  activeBuffs: ['Major Prophecy', 'Minor Slayer', 'Major Sorcery'],
+  // Active skills slotted on bars (affects conditional set bonuses and skill-line passives)
+  skillBars: {
+    bar1: [
+      { skillId: 28807, morphIndex: 2 }, // Crystal Fragments
+      { skillId: 24322 },                 // Mages' Fury
+    ],
+  },
+});
+```
+
 ## API
 
-### `initEsoEngine(resourcesPath?, initDataPath?)`
+### `initEsoEngineFromData(options)`
 
-Initializes the UESP math engine. **Must be called once** before `calculateBuild()`.
+Initializes the UESP math engine from a `UespInitData` object. **Must be called once** before `calculateBuild()`.
 
 Safe to call multiple times — only executes on the first call.
 
-| Param           | Type     | Default        | Description                                      |
-| --------------- | -------- | -------------- | ------------------------------------------------ |
-| `resourcesPath` | `string` | bundled vendor | Path to `esoEditBuild.js` and `esobuilddata.js`  |
-| `initDataPath`  | `string` | bundled vendor | Path to `uesp-init-data.json` with game formulas |
+| Option     | Type           | Description                                    |
+| ---------- | -------------- | ---------------------------------------------- |
+| `initData` | `UespInitData` | Parsed game data (see `vendor/uesp-data/`)     |
+
+---
 
 ### `calculateBuild(input: BuildInput): ComputedStats`
 
@@ -93,22 +131,35 @@ Runs the UESP engine and returns the computed stats.
 ```ts
 interface BuildInput {
   character: {
-    race: string; // "High Elf" | "Nord" | "Breton" | "Khajiit" | ...
-    class: string; // "Sorcerer" | "Dragonknight" | "Nightblade" | ...
-    level: number; // 1–50
+    race: string;           // "High Elf" | "Nord" | "Breton" | "Khajiit" | ...
+    class: string;          // "Sorcerer" | "Dragonknight" | "Nightblade" | ...
+    level: number;          // 1–50
     attributes: {
-      health: number; // attribute points (max 64 total)
+      health: number;       // attribute points (max 64 total)
       magicka: number;
       stamina: number;
     };
-    mundusStone?: string; // "The Thief" | "The Apprentice" | ...
-    cyrodiil?: boolean; // Battle Spirit (PvP)
-    vampireStage?: number; // 0–4
+    mundusStone?: string;   // "The Thief" | "The Apprentice" | ...
+    mundusStone2?: string;  // second Mundus Stone (requires Twice-Born Star set)
+    cyrodiil?: boolean;     // Battle Spirit (PvP)
+    vampireStage?: number;  // 0–4
     werewolfStage?: number; // 0 or 1
     championPoints?: number; // 0–3600
-    rulesVersion?: string; // "Live" (default) | "PTS"
+    rulesVersion?: string;  // "Live" (default) | "PTS"
   };
   items?: Partial<Record<EquipSlot, UespItemApiData>>;
+  championPointNodes?: Record<string | number, ChampionPointNode>;
+  activeBuffs?: string[];     // named buffs — see listAvailableBuffs()
+  toggleSkills?: string[];    // toggled skills — see listAvailableToggleSkills()
+  skillBars?: {
+    bar1?: SkillSlot[];
+    bar2?: SkillSlot[];
+  };
+  activeWeaponBar?: 1 | 2;   // which weapon bar is active (default: 1)
+  passiveSkills?: number[];   // ability IDs of unlocked passive skills
+  autoPassives?: boolean;     // auto-inject racial passives (default: false)
+  enchantOverrides?: Partial<Record<string, { enchantDesc: string; enchantName?: string }>>;
+  toggledSetBonuses?: string[];
 }
 ```
 
@@ -123,7 +174,7 @@ Poison1 | Poison2 | Food | Potion
 
 #### `ComputedStats`
 
-Key stats returned (see [`types.ts`](src/lib/eso-engine/types.ts) for full list):
+Key stats returned (see [`types.ts`](src/lib/eso-engine/types.ts) for the full list):
 
 | Property                                               | Description                               |
 | ------------------------------------------------------ | ----------------------------------------- |
@@ -140,30 +191,127 @@ Key stats returned (see [`types.ts`](src/lib/eso-engine/types.ts) for full list)
 
 > All stat IDs match `g_EsoComputedStats` from the UESP engine (version 49+).
 
-## Updating Formulas After a New ESO Patch
+---
+
+### Catalog Functions
+
+| Function | Returns | Description |
+|---|---|---|
+| `listAvailableBuffs(group?)` | `BuffInfo[]` | 164 named buffs; filter by group `"Major"` \| `"Minor"` \| `"Set"` \| `"Target"` \| … |
+| `listRacialPassives(race)` | `PassiveSkillInfo[]` | All passive ranks for a given race |
+| `listClassPassives(cls)` | `PassiveSkillInfo[]` | All passive ranks for a given class (3 skill lines) |
+| `listPassivesBySkillLine(line)` | `PassiveSkillInfo[]` | Passives for any skill line (Heavy Armor, Undaunted, etc.) |
+| `listAvailableSkillLines()` | `string[]` | All available skill line names |
+| `listAvailableToggleSkills()` | `ToggleSkillInfo[]` | 105 toggle skills; `requiresCyrodiil` marks PvP-only |
+
+```ts
+// Example: see all Major buffs
+const buffs = listAvailableBuffs('Major');
+// Example: find racial passive IDs for a High Elf build
+const passives = listRacialPassives('High Elf');
+const ids = passives.map(p => p.abilityId);
+```
+
+---
 
-When ZeniMax releases a new patch or DLC, the formulas may change. To update:
+## Game Data
+
+Game data (`UespInitData`) is extracted from the UESP SQL dumps and stored in `vendor/uesp-data/uesp-game-data.json`.  
+This file is committed to the repo but **not bundled in the npm package** — consumers are expected to supply their own copy or generate it.
+
+### Generating game data
+
+Requires Node.js ≥ 22 (uses `node:sqlite`).
 
 ```bash
-# 1. Update the UESP submodule
+npm run generate-data -- --db /path/to/local.db [--version 50]
+```
+
+The script reads from `local.db` and writes to `vendor/uesp-data/uesp-game-data.json`.  
+To populate `local.db`, use the seed script from [eso-build-editor](https://github.com/srtomy/eso-build-editor).
+
+### Scripts
+
+| Command | Description |
+|---|---|
+| `npm run generate-data -- --db <path>` | Generate `vendor/uesp-data/uesp-game-data.json` from a SQLite DB |
+| `npm run test:db-init [json] [db] [version]` | Validate committed JSON matches a live DB |
+| `npm run test:build <export.json>` | Print all computed stats for a UESP build export |
+| `npm run test:explore` | Interactive engine exploration script |
+
+---
+
+## Validating Against the UESP Browser
+
+The `scripts/browser-export-build.js` script runs inside the UESP Build Editor DevTools console and exports the full build — inputs and expected stats — as a JSON file.
+
+**How to use:**
+
+1. Open [esobuilds.uesp.net](https://esobuilds.uesp.net), configure your build
+2. Open DevTools (F12) → Console, paste and run `browser-export-build.js`
+3. A `uesp-build-export.json` file is downloaded
+
+**Explore stats interactively:**
+
+```bash
+npm run test:build path/to/uesp-build-export.json
+```
+
+**Add as a golden regression fixture:**
+
+```bash
+cp path/to/uesp-build-export.json tests/fixtures/my-build.json
+npm test
+```
+
+`tests/build-fixtures.test.ts` auto-discovers all `.json` files in `tests/fixtures/` and asserts every stat in `expectedStats` against the wrapper output.
+
+---
+
+## Updating Formulas After a New ESO Patch
+
+```bash
+# 1. Update the UESP engine submodule
 cd vendor/uesp-esochardata
 git fetch upstream && git merge upstream/master
 cd ../..
 
-# 2. Re-extract the formulas from the UESP website
-#    Open https://esobuilds.uesp.net in a browser
-#    Run vendor/uesp-data/browser-extract.js in DevTools Console
-#    Save the result to vendor/uesp-data/uesp-init-data.json
+# 2. Regenerate game data from an up-to-date local.db
+#    (populate local.db first via eso-build-editor's npm run db:seed)
+npm run generate-data -- --db /path/to/local.db --version <patch>
+
+# 3. Commit the updated game data
+git add vendor/uesp-data/uesp-game-data.json
 
-# 3. Run tests to verify
+# 4. Run tests — update any golden values that changed intentionally
 npm test
 ```
 
+## Framework Integration
+
+### Next.js (Vercel / serverless)
+
+The vendor JS files (`esobuilddata.js`, `esoEditBuild.js`) are loaded at runtime via `fs.readFileSync` with a dynamic path. Next.js's output file tracer (`@vercel/nft`) cannot detect them automatically, so they must be declared explicitly in `next.config.ts`:
+
+```ts
+// next.config.ts
+const nextConfig: NextConfig = {
+  serverExternalPackages: ['uesp-eso-build-wrapper'],
+  outputFileTracingIncludes: {
+    '/**': ['./node_modules/uesp-eso-build-wrapper/vendor/**'],
+  },
+};
+```
+
+Without this, the engine will throw at runtime in any serverless environment (Vercel, AWS Lambda, etc.) because the vendor files are not included in the deployment bundle.
+
+---
+
 ## License
 
 MIT © srtomy
 
-This package bundles files from [uesp/uesp-esochardata](https://github.com/uesp/uesp-esochardata) (MIT).
+This package bundles files from [uesp/uesp-esochardata](https://github.com/uesp/uesp-esochardata) (MIT).  
 See [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES) for details.
 
 Elder Scrolls Online is a trademark of ZeniMax Media Inc. This project is not affiliated with or endorsed by ZeniMax Media Inc.

package/dist/lib/eso-engine/calculator.d.ts

@@ -18,6 +18,7 @@
  *   4. Ler os resultados de g_EsoComputedStats[statId].value
  */
 import type { BuffInfo, BuildInput, ComputedStats, PassiveSkillInfo, ToggleSkillInfo } from './types';
+export declare function cacheStatObjects(): void;
 /**
  * Calcula os Computed Character Statistics para a build fornecida.
  *
@@ -42,7 +43,7 @@ export declare function calculateBuild(input: BuildInput): ComputedStats;
  * Each entry maps to one row in the UESP buff tab. Pass `entry.name` to
  * `BuildInput.activeBuffs` to enable that buff in a calculation.
  *
- * Must be called after `initEsoEngine()`.
+ * Must be called after `initEsoEngineFromData()`.
  *
  * @param group - Optional filter. Ex: "Major", "Minor", "Set", "Target",
  *   "Skill", "Potion", "Poison", "Cyrodiil", "Other".
@@ -54,7 +55,7 @@ export declare function listAvailableBuffs(group?: string): BuffInfo[];
  * Each passive may appear in multiple ranks (rank 1, 2, 3).
  * Pass the abilityId of the desired rank to BuildInput.passiveSkills.
  *
- * Must be called after initEsoEngine().
+ * Must be called after initEsoEngineFromData().
  *
  * @param race - Race name as passed to BuildInput.character.race.
  *   Ex: "High Elf", "Nord", "Khajiit"
@@ -65,7 +66,7 @@ export declare function listRacialPassives(race: string): PassiveSkillInfo[];
  * Each passive may appear in multiple ranks (rank 1, 2, 3).
  * Pass the abilityId of the desired rank to BuildInput.passiveSkills.
  *
- * Must be called after initEsoEngine().
+ * Must be called after initEsoEngineFromData().
  *
  * @param className - Class name as passed to BuildInput.character.class.
  *   Ex: "Sorcerer", "Nightblade", "Dragonknight"
@@ -76,7 +77,7 @@ export declare function listClassPassives(className: string): PassiveSkillInfo[]
  * Each passive may appear in multiple ranks (rank 1, 2, 3).
  * Pass the abilityId of the desired rank to BuildInput.passiveSkills.
  *
- * Must be called after initEsoEngine().
+ * Must be called after initEsoEngineFromData().
  *
  * @param skillLine - Skill line name as it appears in g_SkillsData.
  *   Use listAvailableSkillLines() to discover valid names.
@@ -89,7 +90,7 @@ export declare function listPassivesBySkillLine(skillLine: string): PassiveSkill
  * Returns all skill line names that have passive skills available.
  * Use the returned names with listPassivesBySkillLine().
  *
- * Must be called after initEsoEngine().
+ * Must be called after initEsoEngineFromData().
  */
 export declare function listAvailableSkillLines(): string[];
 /**
@@ -100,7 +101,7 @@ export declare function listAvailableSkillLines(): string[];
  * Toggle skills backed by a passive (isPassive=true) need the associated skill
  * in passiveSkills/skillBars for the engine to process the description match.
  *
- * Must be called after initEsoEngine().
+ * Must be called after initEsoEngineFromData().
  */
 export declare function listAvailableToggleSkills(): ToggleSkillInfo[];
 //# sourceMappingURL=calculator.d.ts.map

package/dist/lib/eso-engine/calculator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"calculator.d.ts","sourceRoot":"","sources":["../../../src/lib/eso-engine/calculator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EACV,QAAQ,EACR,UAAU,EAEV,aAAa,EAEb,gBAAgB,EAEhB,eAAe,EAEhB,MAAM,SAAS,CAAC;AAqCjB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,aAAa,CAgc/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,EAAE,CA6B7D;AA2BD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAKnE;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAKvE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAK7E;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,EAAE,CASlD;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,IAAI,eAAe,EAAE,CA6B7D"}
+{"version":3,"file":"calculator.d.ts","sourceRoot":"","sources":["../../../src/lib/eso-engine/calculator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EACV,QAAQ,EACR,UAAU,EAEV,aAAa,EAEb,gBAAgB,EAEhB,eAAe,EAEhB,MAAM,SAAS,CAAC;AAMjB,wBAAgB,gBAAgB,IAAI,IAAI,CAKvC;AAqCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,aAAa,CAwf/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,EAAE,CA6B7D;AA2BD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAKnE;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAKvE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAK7E;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,EAAE,CASlD;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,IAAI,eAAe,EAAE,CA6B7D"}