libram 0.7.11 → 0.7.13

package/dist/session.js

@@ -1,9 +1,10 @@
 import { todayToString, myName, bufferToFile, fileToBuffer, mySessionItems, mySessionMeat, toItem, } from "kolmafia";
 import { getFoldGroup } from "./lib";
 import { $item, $items } from "./template-string";
-import { sumNumbers } from "./utils";
+import { sum } from "./utils";
 /**
  * Return a mapping of the session items, mapping foldable items to a single of their forms
+ *
  * @returns the item session results, with foldables mapped to a single of their folding forms
  */
 function mySessionItemsWrapper() {
@@ -44,26 +45,18 @@ function mySessionItemsWrapper() {
     return inventory;
 }
 /**
- * Performa a binary element-wise operation on two inventories
+ * Perform a binary element-wise operation on two inventories
+ *
  * @param a The LHS inventory to perform the operation on
  * @param b The RHS inventory to perform the operation on
  * @param op an operator to compute between the sets
- * @param commutative if true use the value of b for any items not in a. if false, ignore values not in a
  * @returns a new map representing the combined inventories
  */
-function inventoryOperation(a, b, op, commutative) {
+function inventoryOperation(a, b, op) {
     // return every entry that is in a and not in b
     const difference = new Map();
-    for (const [item, quantity] of a.entries()) {
-        const combinedQuantity = op(quantity, b.get(item) ?? 0);
-        difference.set(item, combinedQuantity);
-    }
-    if (commutative) {
-        for (const [item, quantity] of b.entries()) {
-            if (!a.has(item)) {
-                difference.set(item, quantity);
-            }
-        }
+    for (const item of new Set([...a.keys(), ...b.keys()])) {
+        difference.set(item, op(a.get(item) ?? 0, b.get(item) ?? 0));
     }
     const diffEntries = [...difference.entries()];
     return new Map(diffEntries.filter((value) => value[1] !== 0));
@@ -72,6 +65,7 @@ function inventoryOperation(a, b, op, commutative) {
  * A wrapper around tracking items and meat gained from this session
  * Smartly handles foldables being added/removed based on their state
  * Provides operations to add sessions and subtract Sessions so you can isolate the value of each Session using a baseline
+ *
  * @member meat the raw meat associated with this Session
  * @member items a map representing the items gained/lost during this Session
  */
@@ -80,6 +74,7 @@ export class Session {
     items;
     /**
      * Construct a new session
+     *
      * @param meat the amount of meat associated with this session
      * @param items the items associated with this session
      */
@@ -89,6 +84,7 @@ export class Session {
     }
     /**
      * Register session results that do not get tracked natively
+     *
      * @param target either the Item or a string saying "meat" of what quantity to modify
      * @param quantity How much to modify the tracked amount by
      */
@@ -102,6 +98,7 @@ export class Session {
     }
     /**
      * Value this session
+     *
      * @param itemValue a function that, when given an item, will give a meat value of the item
      * @returns ItemResult with the full value of this session given the input function
      */
@@ -111,21 +108,23 @@ export class Session {
         const itemDetails = [...this.items.entries()].map(([item, quantity]) => {
             return { item, quantity, value: itemValue(item) * quantity };
         });
-        const items = Math.floor(sumNumbers(itemDetails.map((detail) => detail.value)));
+        const items = Math.floor(sum(itemDetails, "value"));
         return { meat, items, total: meat + items, itemDetails };
     }
     /**
      * Subtract the contents of another session from this one, removing any items that have a resulting quantity of 0
      *  (this will ignore elements in b but not in a)
+     *
      * @param other the session from which to pull values to remove from this session
      * @returns a new session representing the difference between this session and the other session
      */
     diff(other) {
-        return new Session(this.meat - other.meat, inventoryOperation(this.items, other.items, (a, b) => a - b, false));
+        return new Session(this.meat - other.meat, inventoryOperation(this.items, other.items, (a, b) => a - b));
     }
     /**
      * Subtract the contents of snasphot b from session a, removing any items that have a resulting quantity of 0
      *  (this will ignore elements in b but not in a)
+     *
      * @param a the session from which to subtract elements
      * @param b the session from which to add elements
      * @returns a new session representing the difference between a and b
@@ -135,14 +134,16 @@ export class Session {
     }
     /**
      * Generate a new session combining multiple sessions together
+     *
      * @param other the session from which to add elements to this set
      * @returns a new session representing the addition of other to this
      */
     add(other) {
-        return new Session(this.meat + other.meat, inventoryOperation(this.items, other.items, (a, b) => a + b, true));
+        return new Session(this.meat + other.meat, inventoryOperation(this.items, other.items, (a, b) => a + b));
     }
     /**
      * Combine the contents of sessions
+     *
      * @param sessions the set of sessions to combine together
      * @returns a new session representing the difference between a and b
      */
@@ -156,6 +157,7 @@ export class Session {
     }
     /**
      * Export this session to a file in the data/ directory. Conventionally this file should end in ".json"
+     *
      * @param filename The file into which to export
      */
     toFile(filename) {
@@ -167,6 +169,7 @@ export class Session {
     }
     /**
      * Import a session from a file in the data/ directory. Conventionally the file should end in ".json"
+     *
      * @param filename The file from which to import
      * @returns the session represented by the file
      */

package/dist/since.d.ts

@@ -1,5 +1,6 @@
 /**
  * Provides functions for checking KoLmafia's version and revision.
+ *
  * @packageDocumentation
  */
 /**
@@ -14,11 +15,11 @@ export declare class KolmafiaVersionError extends Error {
  * Otherwise, does nothing.
  *
  * This behaves like the `since rXXX;` statement in ASH.
+ *
  * @param revision Revision number
  * @throws {KolmafiaVersionError}
  *    If KoLmafia's revision number is less than `revision`.
  * @throws {TypeError} If `revision` is not an integer
- *
  * @example
  * ```ts
  * // Throws if KoLmafia revision is less than r20500
@@ -32,6 +33,7 @@ export declare function sinceKolmafiaRevision(revision: number): void;
  * Otherwise, does nothing.
  *
  * This behaves like the `since X.Y;` statement in ASH.
+ *
  * @param majorVersion Major version number
  * @param minorVersion Minor version number
  * @deprecated Point versions are no longer released by KoLmafia
@@ -40,7 +42,6 @@ export declare function sinceKolmafiaRevision(revision: number): void;
  *    versions are equal but the minor version is less than `minorVersion`
  * @throws {TypeError}
  *    If either `majorVersion` or `minorVersion` are not integers
- *
  * @example
  * ```ts
  * // Throws if KoLmafia version is less than 20.7

package/dist/since.js

@@ -1,5 +1,6 @@
 /**
  * Provides functions for checking KoLmafia's version and revision.
+ *
  * @packageDocumentation
  */
 import { getRevision, getVersion } from "kolmafia";
@@ -22,6 +23,7 @@ KolmafiaVersionError.prototype.name = "KolmafiaVersionError";
 /**
  * Returns the currently executing script name, suitable for embedding in an
  * error message.
+ *
  * @returns Path of the main script wrapped in single-quotes, or `"This script"`
  *    if the path cannot be determined
  */
@@ -35,11 +37,11 @@ function getScriptName() {
  * Otherwise, does nothing.
  *
  * This behaves like the `since rXXX;` statement in ASH.
+ *
  * @param revision Revision number
  * @throws {KolmafiaVersionError}
  *    If KoLmafia's revision number is less than `revision`.
  * @throws {TypeError} If `revision` is not an integer
- *
  * @example
  * ```ts
  * // Throws if KoLmafia revision is less than r20500
@@ -62,6 +64,7 @@ export function sinceKolmafiaRevision(revision) {
  * Otherwise, does nothing.
  *
  * This behaves like the `since X.Y;` statement in ASH.
+ *
  * @param majorVersion Major version number
  * @param minorVersion Minor version number
  * @deprecated Point versions are no longer released by KoLmafia
@@ -70,7 +73,6 @@ export function sinceKolmafiaRevision(revision) {
  *    versions are equal but the minor version is less than `minorVersion`
  * @throws {TypeError}
  *    If either `majorVersion` or `minorVersion` are not integers
- *
  * @example
  * ```ts
  * // Throws if KoLmafia version is less than 20.7

package/dist/utils.d.ts

@@ -1,4 +1,16 @@
+/**
+ * Type guard against null value
+ *
+ * @param value Value that can be null
+ * @returns Whether the value is not null or... not
+ */
 export declare function notNull<T>(value: T | null): value is T;
+/**
+ * Parse string to number, stripping commas
+ *
+ * @param n Numberical string to parse
+ * @returns Numerical value of string
+ */
 export declare function parseNumber(n: string): number;
 /**
  * Clamp a number between lower and upper bounds.
@@ -6,6 +18,7 @@ export declare function parseNumber(n: string): number;
  * @param n Number to clamp.
  * @param min Lower bound.
  * @param max Upper bound.
+ * @returns Clamped value
  */
 export declare function clamp(n: number, min: number, max: number): number;
 /**
@@ -13,28 +26,58 @@ export declare function clamp(n: number, min: number, max: number): number;
  *
  * @param array Array to split
  * @param chunkSize Size of chunk
+ * @returns Split array
  */
 export declare function chunk<T>(array: T[], chunkSize: number): T[][];
+/**
+ * Count distinct values in an array
+ *
+ * @param array Array of values
+ * @returns Map of distinct values to count
+ */
 export declare function arrayToCountedMap<T>(array: T[] | Map<T, number>): Map<T, number>;
+/**
+ * Turn map of distinct values to count into array of values
+ *
+ * @param map Map to turn into array
+ * @returns Array of values
+ */
 export declare function countedMapToArray<T>(map: Map<T, number>): T[];
+/**
+ * Stringify a counted map
+ *
+ * @param map Map of counted values
+ * @returns String representing map of counted values
+ */
 export declare function countedMapToString<T>(map: Map<T, number>): string;
 /**
  * Sum an array of numbers.
+ *
  * @param addends Addends to sum.
  * @param property Property of the elements to be summing
+ * @returns Sum of numbers
  */
 export declare function sum<S extends string | number | symbol, T extends {
     [s in S]: number;
 }>(addends: T[], property: S): number;
 /**
  * Sum an array of numbers.
+ *
  * @param addends Addends to sum.
  * @param mappingFunction Mapping function to turn addends into actual numbers.
+ * @returns Sum of numbers
  */
 export declare function sum<T>(addends: T[], mappingFunction: (element: T) => number): number;
+/**
+ * Sum array of numbers
+ *
+ * @param addends Numbers to sum
+ * @returns Sum of numbers
+ */
 export declare function sumNumbers(addends: number[]): number;
 /**
  * Checks if a given item is in a readonly array, acting as a typeguard.
+ *
  * @param item Needle
  * @param array Readonly array haystack
  * @returns Whether the item is in the array, and narrows the type of the item.
@@ -42,6 +85,7 @@ export declare function sumNumbers(addends: number[]): number;
 export declare function arrayContains<T, A extends T>(item: T, array: ReadonlyArray<A>): item is A;
 /**
  * Checks if two arrays contain the same elements in the same quantity.
+ *
  * @param a First array for comparison
  * @param b Second array for comparison
  * @returns Whether the two arrays are equal, irrespective of order.
@@ -49,26 +93,58 @@ export declare function arrayContains<T, A extends T>(item: T, array: ReadonlyAr
 export declare function setEqual<T>(a: T[], b: T[]): boolean;
 /**
  * Reverses keys and values for a given map
+ *
  * @param map Map to invert
+ * @returns Inverted map
  */
 export declare function invertMap<T1, T2>(map: Map<T1, T2>): Map<T2, T1>;
 /**
  * Splits a string by commas while also respecting escaping commas with a backslash
+ *
  * @param str String to split
  * @returns List of tokens
  */
 export declare function splitByCommasWithEscapes(str: string): string[];
-/**
- * Find the best element of an array, where "best" is defined by some given criteria.
- * @param array The array to traverse and find the best element of.
- * @param optimizer Either a key on the objects we're looking at that corresponds to numerical values, or a function for mapping these objects to numbers. Essentially, some way of assigning value to the elements of the array.
- * @param reverse Make this true to find the worst element of the array, and false to find the best. Defaults to false.
- */
 export declare function maxBy<T>(array: T[] | readonly T[], optimizer: (element: T) => number, reverse?: boolean): T;
 export declare function maxBy<S extends string | number | symbol, T extends {
     [x in S]: number;
 }>(array: T[] | readonly T[], key: S, reverse?: boolean): T;
 export declare type Tuple<T, N extends number> = N extends N ? number extends N ? T[] : _tupleOf<T, N, []> : never;
 declare type _tupleOf<T, N extends number, R extends unknown[]> = R["length"] extends N ? R : _tupleOf<T, N, [T, ...R]>;
+/**
+ * Compare arrays shallowly
+ *
+ * @param left One array to compare
+ * @param right The other array to compare
+ * @returns Whether the two arrays are shallowly equal
+ */
 export declare function arrayEquals<T>(left: T[] | readonly T[], right: T[] | readonly T[]): boolean;
+/**
+ * Type that extends any non-function entity--like a string, number, or array--into a itself and a no-input function that returns it.
+ * Used to interact with objects that could either be functions or static values.
+ */
+export declare type Delayed<T> = [T] extends [(...args: any) => any] ? never : T | (() => T);
+/**
+ * Used to collapse a Delayed<T> object into an entity of type "T" as represented by the object.
+ *
+ * @param delayedObject Object of type Delayed<T> that represents either a value of type T or a function returning a value of type T.
+ * @returns The return value of the function, if delayedObject is a function. Otherwise, this returns the original element.
+ */
+export declare function undelay<T>(delayedObject: Delayed<T>): T;
+/**
+ * An object keyed by string type T, with values of S.
+ *  or contains a 'default' parameter to use as a fallback.
+ */
+export declare type Switch<T extends string, S> = Record<T, S> | (Partial<{
+    [x in T]: S;
+}> & {
+    default: S;
+});
+/**
+ * Makes a byX function, like byStat or byClass
+ *
+ * @param source A method for finding your stat, or class, or whatever X is in this context
+ * @returns A function akin to byStat or byClass; it accepts an object that either is "complete" in the sense that it has a key for every conceivable value, or contains a `default` parameter. If an inappropriate input is provided, returns undefined.
+ */
+export declare function makeByXFunction<T extends string>(source: Delayed<T>): <S>(options: Switch<T, S>) => S;
 export {};

package/dist/utils.js

@@ -1,6 +1,18 @@
+/**
+ * Type guard against null value
+ *
+ * @param value Value that can be null
+ * @returns Whether the value is not null or... not
+ */
 export function notNull(value) {
     return value !== null;
 }
+/**
+ * Parse string to number, stripping commas
+ *
+ * @param n Numberical string to parse
+ * @returns Numerical value of string
+ */
 export function parseNumber(n) {
     return Number.parseInt(n.replace(/,/g, ""));
 }
@@ -10,6 +22,7 @@ export function parseNumber(n) {
  * @param n Number to clamp.
  * @param min Lower bound.
  * @param max Upper bound.
+ * @returns Clamped value
  */
 export function clamp(n, min, max) {
     return Math.max(min, Math.min(max, n));
@@ -19,6 +32,7 @@ export function clamp(n, min, max) {
  *
  * @param array Array to split
  * @param chunkSize Size of chunk
+ * @returns Split array
  */
 export function chunk(array, chunkSize) {
     const result = [];
@@ -27,6 +41,12 @@ export function chunk(array, chunkSize) {
     }
     return result;
 }
+/**
+ * Count distinct values in an array
+ *
+ * @param array Array of values
+ * @returns Map of distinct values to count
+ */
 export function arrayToCountedMap(array) {
     if (!Array.isArray(array))
         return array;
@@ -36,20 +56,46 @@ export function arrayToCountedMap(array) {
     });
     return map;
 }
+/**
+ * Turn map of distinct values to count into array of values
+ *
+ * @param map Map to turn into array
+ * @returns Array of values
+ */
 export function countedMapToArray(map) {
     return [].concat(...[...map].map(([item, quantity]) => Array(quantity).fill(item)));
 }
+/**
+ * Stringify a counted map
+ *
+ * @param map Map of counted values
+ * @returns String representing map of counted values
+ */
 export function countedMapToString(map) {
     return [...map].map(([item, quantity]) => `${quantity} x ${item}`).join(", ");
 }
+/**
+ * Sum an array of numbers.
+ *
+ * @param addends Addends to sum.
+ * @param x Property or mapping function of addends to sum
+ * @returns Sum of numbers
+ */
 export function sum(addends, x) {
     return addends.reduce((subtotal, element) => subtotal + (typeof x === "function" ? x(element) : element[x]), 0);
 }
+/**
+ * Sum array of numbers
+ *
+ * @param addends Numbers to sum
+ * @returns Sum of numbers
+ */
 export function sumNumbers(addends) {
     return sum(addends, (x) => x);
 }
 /**
  * Checks if a given item is in a readonly array, acting as a typeguard.
+ *
  * @param item Needle
  * @param array Readonly array haystack
  * @returns Whether the item is in the array, and narrows the type of the item.
@@ -59,6 +105,7 @@ export function arrayContains(item, array) {
 }
 /**
  * Checks if two arrays contain the same elements in the same quantity.
+ *
  * @param a First array for comparison
  * @param b Second array for comparison
  * @returns Whether the two arrays are equal, irrespective of order.
@@ -71,7 +118,9 @@ export function setEqual(a, b) {
 }
 /**
  * Reverses keys and values for a given map
+ *
  * @param map Map to invert
+ * @returns Inverted map
  */
 export function invertMap(map) {
     const returnValue = new Map();
@@ -82,6 +131,7 @@ export function invertMap(map) {
 }
 /**
  * Splits a string by commas while also respecting escaping commas with a backslash
+ *
  * @param str String to split
  * @returns List of tokens
  */
@@ -107,6 +157,14 @@ export function splitByCommasWithEscapes(str) {
     returnValue.push(currentString.trim());
     return returnValue;
 }
+/**
+ * Find the best element of an array, where "best" is defined by some given criteria.
+ *
+ * @param array The array to traverse and find the best element of.
+ * @param optimizer Either a key on the objects we're looking at that corresponds to numerical values, or a function for mapping these objects to numbers. Essentially, some way of assigning value to the elements of the array.
+ * @param reverse Make this true to find the worst element of the array, and false to find the best. Defaults to false.
+ * @returns Best element by optimizer function
+ */
 export function maxBy(array, optimizer, reverse = false) {
     if (!array.length)
         throw new Error("Cannot call maxBy on an empty array!");
@@ -122,8 +180,38 @@ export function maxBy(array, optimizer, reverse = false) {
         return array.reduce((a, b) => a[optimizer] >= b[optimizer] !== reverse ? a : b);
     }
 }
+/**
+ * Compare arrays shallowly
+ *
+ * @param left One array to compare
+ * @param right The other array to compare
+ * @returns Whether the two arrays are shallowly equal
+ */
 export function arrayEquals(left, right) {
     if (left.length !== right.length)
         return false;
     return left.every((element, index) => element === right[index]);
 }
+/**
+ * Used to collapse a Delayed<T> object into an entity of type "T" as represented by the object.
+ *
+ * @param delayedObject Object of type Delayed<T> that represents either a value of type T or a function returning a value of type T.
+ * @returns The return value of the function, if delayedObject is a function. Otherwise, this returns the original element.
+ */
+export function undelay(delayedObject) {
+    return typeof delayedObject === "function" ? delayedObject() : delayedObject;
+}
+/**
+ * Makes a byX function, like byStat or byClass
+ *
+ * @param source A method for finding your stat, or class, or whatever X is in this context
+ * @returns A function akin to byStat or byClass; it accepts an object that either is "complete" in the sense that it has a key for every conceivable value, or contains a `default` parameter. If an inappropriate input is provided, returns undefined.
+ */
+export function makeByXFunction(source) {
+    return function (options) {
+        const val = undelay(source);
+        if ("default" in options)
+            return options[val] ?? options.default;
+        return options[val];
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libram",
-  "version": "0.7.11",
+  "version": "0.7.13",
   "description": "JavaScript helper library for KoLmafia",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -31,6 +31,7 @@
     "@babel/preset-env": "^7.16.11",
     "@babel/preset-typescript": "^7.15.0",
     "@tsconfig/node16": "^1.0.2",
+    "@types/array.prototype.flat": "^1.2.1",
     "@types/jest": "^27.0.1",
     "@types/lodash-es": "^4.17.4",
     "@types/node": "^16.11.11",
@@ -45,11 +46,12 @@
     "eslint-import-resolver-typescript": "^2.5.0",
     "eslint-plugin-import": "^2.25.4",
     "eslint-plugin-jest": "^25.2.3",
-    "eslint-plugin-libram": "^0.2.25",
+    "eslint-plugin-jsdoc": "^40.0.1",
+    "eslint-plugin-libram": "^0.2.29",
     "husky": "^4.3.6",
     "java-parser": "^1.4.0",
     "jest": "^27.1.0",
-    "kolmafia": "^5.27075.0",
+    "kolmafia": "^5.27260.0",
     "lint-staged": ">=10",
     "node-fetch": "^2.6.1",
     "prettier": "^2.1.2",
@@ -60,7 +62,7 @@
   },
   "dependencies": {
     "@babel/runtime-corejs3": "^7.17.2",
-    "core-js": "^3.21.0"
+    "array.prototype.flat": "^1.3.1"
   },
   "peerDependencies": {
     "kolmafia": "^5.26781.0"

package/dist/dungeons/Dreadsylvania.d.ts

@@ -1,5 +0,0 @@
-import { Item } from "kolmafia";
-export declare function close(): boolean;
-export declare function open(paymentPolicy?: "None" | "All" | "Difference"): boolean;
-export declare function distribute(idOrName?: number | string, loot?: Item | Item[] | Map<Item, number>, distributeAllOfAGivenItem?: boolean): void;
-export declare function findLoot(): Map<Item, number>;

package/dist/dungeons/Dreadsylvania.js

@@ -1,14 +0,0 @@
-import { myId } from "kolmafia";
-import { close as closeDungeon, distribute as distributeDungeon, Dreadsylvania, findLoot as findLootDungeon, open as openDungeon, } from "./Dungeon";
-export function close() {
-    return closeDungeon(Dreadsylvania);
-}
-export function open(paymentPolicy = "Difference") {
-    return openDungeon(Dreadsylvania, paymentPolicy);
-}
-export function distribute(idOrName = myId(), loot = Dreadsylvania.loot, distributeAllOfAGivenItem = true) {
-    distributeDungeon(Dreadsylvania, idOrName, loot, distributeAllOfAGivenItem);
-}
-export function findLoot() {
-    return findLootDungeon(Dreadsylvania);
-}

package/dist/dungeons/Dungeon.d.ts

@@ -1,29 +0,0 @@
-import { Item } from "kolmafia";
-export declare type Dungeon = {
-    name: string;
-    loot: Item[];
-    openAction: string;
-    closeAction: string;
-    openCost: number;
-    openImage: string;
-    closedImage: string;
-};
-/**
- * Distributes loot from given dungeon
- * @param dungeon The dungeon to distribute loot from
- * @param idOrName The player you're trying to distribute to, either as a username or a player ID. Defaults to self.
- * @param loot The loot you're looking to distribute, specific to this dungeon
- * @param distributeAllOfAGivenItem For items that you can get multiple of in a dungeon. When true, this will give everything of that ilk to your chosen player.
- */
-export declare function distribute(dungeon: Dungeon, idOrName?: number | string, loot?: Item | Item[] | Map<Item, number>, distributeAllOfAGivenItem?: boolean): void;
-export declare function close(dungeon: Dungeon): boolean;
-/**
- * Opens clan dungeon and, if relevant, pays meat to do so
- * @param dungeon The Dungeon to open
- * @param paymentPolicy "None", "All", or "Difference". Difference pays into the stash the exact amount needed to open the dungeon.
- */
-export declare function open(dungeon: Dungeon, paymentPolicy?: "None" | "All" | "Difference"): boolean;
-export declare const Dreadsylvania: Dungeon;
-export declare const Hobopolis: Dungeon;
-export declare const SlimeTube: Dungeon;
-export declare function findLoot(dungeon: Dungeon): Map<Item, number>;