feat: item utilities, colors (#536)

README.md

@@ -44,8 +44,18 @@ npm install warframe-items
 
 ### Usage
 ```js
-const Items = require('warframe-items')
-const items = new Items(options, ...oldItems)
+// CommonJS
+const Items = require('warframe-items');
+const items = new Items(options, ...oldItems);
+
+// ESM
+import Items from 'warframe-items';
+const items = new Items(options, ...oldItems);
+
+// Utilities - Only works in import
+import { find, colors } from 'warframe-items/utilities';
+const excalPrime = find.findItem('/Lotus/Powersuits/Excalibur/ExcaliburPrime');
+// normal items operations now
 ```
 In this example, `items` is an Array with all items. The `...oldItems` param
 allows you to add your own items before our gathered ones.
@@ -116,13 +126,13 @@ to get you started.
 ### File structure
 All relevant scripts are found in `/build/` with
 
-[build.js](/build/build.js)<br>
+[build.mjs](/build/build.mjs)<br>
 The entrypoint for the build script. Here we also save JSON, image and cache data.
 
-[scraper.js](/build/scraper.js)<br>
+[scraper.mjs](/build/scraper.mjs)<br>
 Fetches all external data and returns it to the parser.
 
-[parser.js](/build/parser.js)<br>
+[parser.mjs](/build/parser.mjs)<br>
 Parses the external data to match our schema and returns it to the build script.
 
 <br>

build/parser.mjs

@@ -1,4 +1,4 @@
-import _ from 'lodash';
+import cloneDeep from 'lodash.clonedeep';
 
 import dedupe from './dedupe.mjs';
 import hashManager from './hashManager.mjs';
@@ -148,7 +148,7 @@ class Parser {
 
     const bar = new Progress(`Parsing ${category}`, items.length);
     if (!items.length) {
-      bar.interrupt(`No ${category}`);
+      bar?.interrupt?.(`No ${category}`);
       return [];
     }
     for (let index = 0; index < items.length; index += 1) {
@@ -175,7 +175,7 @@ class Parser {
    * @returns {Partial<Item>}
    */
   filter(original, category, data, previous) {
-    const result = _.cloneDeep(original);
+    const result = cloneDeep(original);
 
     if (result.rewardName) result.uniqueName = result.rewardName;
     this.addType(result);
@@ -212,7 +212,7 @@ class Parser {
    * @returns {Partial<Item>}
    */
   quickFilter(original, category, data, previous) {
-    const result = _.cloneDeep(original);
+    const result = cloneDeep(original);
 
     if (result.rewardName) result.uniqueName = result.rewardName;
     this.addType(result);
@@ -240,7 +240,7 @@ class Parser {
     const blueprint = blueprints.filter(filterBps).find((b) => b.resultType === item.uniqueName);
     if (!blueprint) return item; // Some items just don't have blueprints
     const components = [];
-    const result = _.cloneDeep(item);
+    const result = cloneDeep(item);
 
     // Look for original component entry in all categories
     // eslint-disable-next-line no-restricted-syntax

build/scraper.mjs

@@ -177,7 +177,6 @@ class Scraper {
     const bar = skipProgress ? undefined : new Progress('Fetching Patchlogs', 1);
     if (!skipProgress) {
       bar.tick();
-      bar.interrupt(typeof patchlogs);
     }
 
     return patchlogs;

index.d.ts

@@ -1,9 +1,64 @@
+// Project: warframe-items
 declare module 'warframe-items' {
+    /**
+     * Utilities around items
+     * only available from ESM import
+     */
+    module 'warframe-items/utilities' {
+        interface find {
+            findItem: (uname: string) => Promise<Item | undefined>;
+            loadMods: (upgrades?: Array<ModResolveable>) => Promise<{
+                arcane: Arcane[];
+                mods: ModUnion[];
+            }>
+        }
+        interface colors {
+            safeColor: (color: string) => Pixel | undefined;
+        }
+    }
+
     export default class Items extends Array<Item>{
         constructor(options: ItemsOptions, ...items: Item[]);
         options: ItemsOptions;
         i18n: BundleofI18nBundle<Locale>;
     }
+
+    interface ModResolveable {
+        uniqueName: string;
+        rank?: number;
+    }
+
+    interface Palette {
+        /** Palette name (as seen in-game */
+        name: string;
+        /** Palette description */
+        description: string;
+    }
+
+    interface PaletteEntry {
+        palette: Palette;
+        position: {
+            /** Row position */
+            row: number;
+            /** Column position */
+            col: number;
+        };
+    }
+
+    class Pixel {
+        constructor(hex: string);
+        toJSON(): {
+            hex: string;
+            matches: PaletteEntry[];
+            isTransparent: boolean;
+        };
+        get pallets(): string[];
+        get matches(): PaletteEntry[];
+        /** whether the pixel is transparent */
+        get isTransparent(): boolean;
+        get hex(): string;
+    }
+
     interface ItemsOptions {
         category: Array<Category | 'SentinelWeapons'>;
         ignoreEnemies?: boolean;
@@ -37,6 +92,8 @@ declare module 'warframe-items' {
         ModSet |
         FocusWay;
 
+    type ModUnion = Mod | SingleLevelMod | RivenMod | StanceMod | PrimeMod | RailjackMod;
+
     type UniqueName = string;
     type DateString = string;
 

index.mjs

@@ -36,7 +36,7 @@ import { resolve, dirname } from 'node:path';
 import { readFileSync, readdirSync, accessSync, constants } from 'node:fs';
 import { fileURLToPath } from 'url';
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
+const directory = dirname(fileURLToPath(import.meta.url));
 
 const canAccess = (path) => {
   try {
@@ -51,7 +51,7 @@ const cache = {};
 const require = (filePath) => {
   if (cache[filePath]) return cache[filePath];
 
-  const resolved = resolve(__dirname, filePath);
+  const resolved = resolve(directory, filePath);
   if (canAccess(resolved)) {
     const parsed = JSON.parse(readFileSync(resolved, 'utf-8'));
     cache[filePath] = parsed;
@@ -70,7 +70,7 @@ try {
 }
 
 const ignored = ['All', 'i18n'];
-const defaultCategories = readdirSync(resolve(__dirname, './data/json/'))
+const defaultCategories = readdirSync(resolve(directory, './data/json/'))
   .filter((f) => f.includes('.json'))
   .map((f) => f.replace('.json', ''))
   .filter((f) => !ignored.includes(f));