libram 0.8.28 → 0.8.30

package/dist/utils.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Type guard against null value
+ *
+ * @param value Value that could be null
+ * @returns Confirmation that the value is not null
+ */
+export declare function notNull<T>(value: T | null): value is T;
+/**
+ * Type guard against nullish value
+ *
+ * @param value Value that could be null or undefined
+ * @returns Confirmation that the value is not null nor undefined
+ */
+export declare function notNullish<T>(value: T | null | undefined): 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.
+ *
+ * @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;
+/**
+ * Split an {@param array} into {@param chunkSize} sized chunks
+ *
+ * @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.
+ */
+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.
+ */
+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[];
+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, S extends any[] = never[]> = [T] extends [
+    (...args: any) => any
+] ? never : T | ((...args: S) => T);
+/**
+ * Used to collapse a Delayed<T, S> object into an entity of type "T" as represented by the object.
+ *
+ * @param delayedObject Object of type Delayed<T, S> that represents either a value of type T or a function returning a value of type T.
+ * @param args The arguments to pass to the delay function
+ * @returns The return value of the function, if delayedObject is a function. Otherwise, this returns the original element.
+ */
+export declare function undelay<T, S extends any[] = never[]>(delayedObject: Delayed<T, S>, ...args: S): 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;
+/**
+ * Flattens an array. Basically replacing Array.prototype.flat for which Rhino doesn't yet have an implementation
+ *
+ * @param arr Array to flatten
+ * @param depth Number of layers to flatten by; Infinity for a fully flat array
+ * @returns Flattened array
+ */
+export declare function flat<A extends any[], D extends number = 1>(arr: A, depth?: number): FlatArray<A, D>[];
+/**
+ * @param array Array to select from
+ * @returns Random item from array
+ */
+export declare function random<T>(array: T[]): T;
+/**
+ * Title cases a single word
+ *
+ * @param word Word to transform
+ * @returns Word in title case
+ */
+export declare const tc: (word: string) => string;
+declare type Enumerate<N extends number, A extends number[] = []> = A["length"] extends N ? A[number] : Enumerate<N, [...A, A["length"]]>;
+/**
+ * Integers on the interval [A, B).
+ */
+export declare type Range<A extends number, B extends number> = Exclude<Enumerate<B>, Enumerate<A>>;
+export {};

package/dist/utils.js

@@ -0,0 +1,264 @@
+/**
+ * Type guard against null value
+ *
+ * @param value Value that could be null
+ * @returns Confirmation that the value is not null
+ */
+export function notNull(value) {
+    return value !== null;
+}
+/**
+ * Type guard against nullish value
+ *
+ * @param value Value that could be null or undefined
+ * @returns Confirmation that the value is not null nor undefined
+ */
+export function notNullish(value) {
+    return notNull(value) && value !== undefined;
+}
+/**
+ * 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, ""));
+}
+/**
+ * Clamp a number between lower and upper bounds.
+ *
+ * @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));
+}
+/**
+ * Split an {@param array} into {@param chunkSize} sized chunks
+ *
+ * @param array Array to split
+ * @param chunkSize Size of chunk
+ * @returns Split array
+ */
+export function chunk(array, chunkSize) {
+    const result = [];
+    for (let i = 0; i < array.length; i += chunkSize) {
+        result.push(array.slice(i, i + 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;
+    const map = new Map();
+    array.forEach((item) => {
+        map.set(item, (map.get(item) || 0) + 1);
+    });
+    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.
+ */
+export function arrayContains(item, array) {
+    return array.includes(item);
+}
+/**
+ * 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.
+ */
+export function setEqual(a, b) {
+    const sortedA = [...a].sort();
+    const sortedB = [...b].sort();
+    return (a.length === b.length &&
+        sortedA.every((item, index) => item === sortedB[index]));
+}
+/**
+ * Reverses keys and values for a given map
+ *
+ * @param map Map to invert
+ * @returns Inverted map
+ */
+export function invertMap(map) {
+    const returnValue = new Map();
+    for (const [key, value] of map) {
+        returnValue.set(value, key);
+    }
+    return returnValue;
+}
+/**
+ * Splits a string by commas while also respecting escaping commas with a backslash
+ *
+ * @param str String to split
+ * @returns List of tokens
+ */
+export function splitByCommasWithEscapes(str) {
+    const returnValue = [];
+    let ignoreNext = false;
+    let currentString = "";
+    for (const char of str.split("")) {
+        if (char === "\\") {
+            ignoreNext = true;
+        }
+        else {
+            if (char == "," && !ignoreNext) {
+                returnValue.push(currentString.trim());
+                currentString = "";
+            }
+            else {
+                currentString += char;
+            }
+            ignoreNext = false;
+        }
+    }
+    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!");
+    if (typeof optimizer === "function") {
+        return [...array].reduce(({ value, item }, other) => {
+            const otherValue = optimizer(other);
+            return value >= otherValue !== reverse
+                ? { value, item }
+                : { value: otherValue, item: other };
+        }, { item: array[0], value: optimizer(array[0]) }).item;
+    }
+    else {
+        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, S> object into an entity of type "T" as represented by the object.
+ *
+ * @param delayedObject Object of type Delayed<T, S> that represents either a value of type T or a function returning a value of type T.
+ * @param args The arguments to pass to the delay function
+ * @returns The return value of the function, if delayedObject is a function. Otherwise, this returns the original element.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function undelay(delayedObject, ...args) {
+    return typeof delayedObject === "function"
+        ? delayedObject(...args)
+        : 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];
+    };
+}
+/**
+ * Flattens an array. Basically replacing Array.prototype.flat for which Rhino doesn't yet have an implementation
+ *
+ * @param arr Array to flatten
+ * @param depth Number of layers to flatten by; Infinity for a fully flat array
+ * @returns Flattened array
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function flat(arr, depth = Infinity) {
+    let flatArray = [];
+    for (const item of arr) {
+        if (Array.isArray(item) && depth > 0) {
+            flatArray = flatArray.concat(flat(item, depth - 1));
+        }
+        else {
+            flatArray.push(item);
+        }
+    }
+    return flatArray;
+}
+/**
+ * @param array Array to select from
+ * @returns Random item from array
+ */
+export function random(array) {
+    return array[Math.floor(Math.random() * array.length)];
+}
+/**
+ * Title cases a single word
+ *
+ * @param word Word to transform
+ * @returns Word in title case
+ */
+export const tc = (word) => word.charAt(0).toUpperCase() + word.slice(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libram",
-  "version": "0.8.28",
+  "version": "0.8.30",
   "description": "JavaScript helper library for KoLmafia",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,7 +16,7 @@
     "format": "yarn run prettier --write .",
     "lint": "yarn run eslint src tools --ext .ts && yarn run prettier --check .",
     "test": "yarn run jest",
-    "prepublishOnly": "yarn run build",
+    "prepack": "yarn run build",
     "updateProps": "yarn run ts-node ./tools/parseDefaultProperties.ts",
     "updateOverlappingItemSkillNames": "yarn run ts-node ./tools/parseItemSkillNames.ts"
   },