@elyukai/utils 0.1.2

package/dist/dictionary.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Introduces a Dictionary class that represents an immutable mapping from
+ * strings to values.
+ */
+import type { AnyNonNullish } from "./nullable.js";
+/**
+ * An immutable dictionary mapping strings to values.
+ */
+export declare class Dictionary<T extends AnyNonNullish | null> {
+    private record;
+    /**
+     * Creates a new dictionary from an indexed object.
+     */
+    constructor(record: Record<string, T>);
+    /**
+     * An empty dictionary.
+     */
+    static empty: Dictionary<never>;
+    /**
+     * Constructs a dictionary from an array of key-value pairs.
+     */
+    static fromEntries<T extends AnyNonNullish | null>(entries: [string, T][]): Dictionary<T>;
+    /**
+     * Returns the value associated with the given key, or `undefined` if the key does not exist.
+     */
+    get(key: string): T | undefined;
+    /**
+     * Returns the value associated with the given key mapped through the given function, or `undefined` if the key does not exist.
+     */
+    getMap<U>(key: string, mapFn: (value: T) => U): U | undefined;
+    /**
+     * Checks if the dictionary has the given key.
+     */
+    has(key: string): boolean;
+    /**
+     * Sets the given key to the given value.
+     *
+     * If the key already exists, its value will be overwritten.
+     */
+    set(key: string, value: T): Dictionary<T>;
+    /**
+     * Removes the given key from the dictionary.
+     *
+     * If the key does not exist, the same dictionary instance is returned.
+     */
+    remove(key: string): Dictionary<T>;
+    /**
+     * The number of entries in the dictionary.
+     */
+    get size(): number;
+    /**
+     * Returns an array of key-value pairs in the dictionary.
+     */
+    entries(): [string, T][];
+    /**
+     * Returns an array of values in the dictionary.
+     */
+    values(): T[];
+    /**
+     * Returns an array of keys in the dictionary.
+     */
+    keys(): string[];
+    /**
+     * Calls the given function for each key-value pair in the dictionary.
+     */
+    forEach(fn: (value: T, key: string) => void): void;
+    /**
+     * Calls the given async function for each key-value pair in the dictionary.
+     *
+     * The calls are made sequentially.
+     */
+    forEachAsync(fn: (value: T, key: string) => Promise<void>): Promise<void>;
+    /**
+     * Create, modify, or remove the value for the given key based on its current value.
+     *
+     * The value passed to `modifyFn` will be `undefined` if the key does not exist.
+     * If the `modifyFn` returns `undefined`, the key will be removed from the dictionary.
+     * Otherwise, the key will be set to the new value returned by `modifyFn`.
+     */
+    modify(key: string, modifyFn: (currentValue: T | undefined) => T | undefined): Dictionary<T>;
+    /**
+     * Returns the first value that matches the given predicate, or `undefined` if
+     * no such value exists.
+     */
+    find<U extends T>(predicate: (value: T, key: string) => value is U): U | undefined;
+    /**
+     * Returns the first value that matches the given predicate, or `undefined` if
+     * no such value exists.
+     */
+    find(predicate: (value: T, key: string) => boolean): T | undefined;
+    /**
+     * Returns the first key that matches the given predicate, or `undefined` if no such key exists.
+     */
+    findKey(predicate: (value: T, key: string) => boolean): string | undefined;
+    /**
+     * Returns the first key-value pair that matches the given predicate, or `undefined` if no such key-value pair exists.
+     */
+    findEntry<U extends T>(predicate: (value: T, key: string) => value is U): [key: string, value: U] | undefined;
+    /**
+     * Returns the first key-value pair that matches the given predicate, or `undefined` if no such key-value pair exists.
+     */
+    findEntry(predicate: (value: T, key: string) => boolean): [key: string, value: T] | undefined;
+    /**
+     * Applies the given mapping function to each key-value pair in the dictionary and returns the first non-`undefined` result, or `undefined` if no such result exists.
+     */
+    mapFirst<U extends AnyNonNullish | null>(mapFn: (value: T, key: string) => U | undefined): U | undefined;
+    /**
+     * Applies a function to every key-value pair in the dictionary.
+     */
+    map<U extends AnyNonNullish | null>(mapFn: (value: T, key: string) => U): Dictionary<U>;
+    /**
+     * Calls the specified callback function for all the elements in an array. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.
+     */
+    reduce<U>(reducer: (acc: U, value: T, key: string) => U, initialValue: U): U;
+}

package/dist/dictionary.js

@@ -0,0 +1,178 @@
+/**
+ * Introduces a Dictionary class that represents an immutable mapping from
+ * strings to values.
+ */
+import { omitKeys } from "./object.js";
+/**
+ * An immutable dictionary mapping strings to values.
+ */
+export class Dictionary {
+    record;
+    /**
+     * Creates a new dictionary from an indexed object.
+     */
+    constructor(record) {
+        this.record = record;
+    }
+    /**
+     * An empty dictionary.
+     */
+    static empty = new Dictionary({});
+    /**
+     * Constructs a dictionary from an array of key-value pairs.
+     */
+    static fromEntries(entries) {
+        return new Dictionary(Object.fromEntries(entries));
+    }
+    /**
+     * Returns the value associated with the given key, or `undefined` if the key does not exist.
+     */
+    get(key) {
+        return this.record[key];
+    }
+    /**
+     * Returns the value associated with the given key mapped through the given function, or `undefined` if the key does not exist.
+     */
+    getMap(key, mapFn) {
+        const value = this.get(key);
+        return value === undefined ? undefined : mapFn(value);
+    }
+    /**
+     * Checks if the dictionary has the given key.
+     */
+    has(key) {
+        return Object.prototype.hasOwnProperty.call(this.record, key);
+    }
+    /**
+     * Sets the given key to the given value.
+     *
+     * If the key already exists, its value will be overwritten.
+     */
+    set(key, value) {
+        return new Dictionary({ ...this.record, [key]: value });
+    }
+    /**
+     * Removes the given key from the dictionary.
+     *
+     * If the key does not exist, the same dictionary instance is returned.
+     */
+    remove(key) {
+        if (this.has(key)) {
+            return new Dictionary(omitKeys(this.record, key));
+        }
+        else {
+            return this;
+        }
+    }
+    /**
+     * The number of entries in the dictionary.
+     */
+    get size() {
+        return Object.keys(this.record).length;
+    }
+    /**
+     * Returns an array of key-value pairs in the dictionary.
+     */
+    entries() {
+        return Object.entries(this.record);
+    }
+    /**
+     * Returns an array of values in the dictionary.
+     */
+    values() {
+        return Object.values(this.record);
+    }
+    /**
+     * Returns an array of keys in the dictionary.
+     */
+    keys() {
+        return Object.keys(this.record);
+    }
+    /**
+     * Calls the given function for each key-value pair in the dictionary.
+     */
+    forEach(fn) {
+        for (const [key, value] of Object.entries(this.record)) {
+            fn(value, key);
+        }
+    }
+    /**
+     * Calls the given async function for each key-value pair in the dictionary.
+     *
+     * The calls are made sequentially.
+     */
+    async forEachAsync(fn) {
+        for (const [key, value] of Object.entries(this.record)) {
+            await fn(value, key);
+        }
+    }
+    /**
+     * Create, modify, or remove the value for the given key based on its current value.
+     *
+     * The value passed to `modifyFn` will be `undefined` if the key does not exist.
+     * If the `modifyFn` returns `undefined`, the key will be removed from the dictionary.
+     * Otherwise, the key will be set to the new value returned by `modifyFn`.
+     */
+    modify(key, modifyFn) {
+        const currentValue = this.get(key);
+        const newValue = modifyFn(currentValue);
+        if (newValue === undefined) {
+            return this.remove(key);
+        }
+        else {
+            return this.set(key, newValue);
+        }
+    }
+    /**
+     * Returns the first value that matches the given predicate, or `undefined` if
+     * no such value exists.
+     */
+    find(predicate) {
+        return this.findEntry(predicate)?.[1];
+    }
+    /**
+     * Returns the first key that matches the given predicate, or `undefined` if no such key exists.
+     */
+    findKey(predicate) {
+        return this.findEntry(predicate)?.[0];
+    }
+    /**
+     * Returns the first key-value pair that matches the given predicate, or `undefined` if no such key-value pair exists.
+     */
+    findEntry(predicate) {
+        for (const [key, value] of Object.entries(this.record)) {
+            if (predicate(value, key)) {
+                return [key, value];
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Applies the given mapping function to each key-value pair in the dictionary and returns the first non-`undefined` result, or `undefined` if no such result exists.
+     */
+    mapFirst(mapFn) {
+        for (const [key, value] of Object.entries(this.record)) {
+            const mapped = mapFn(value, key);
+            if (mapped !== undefined) {
+                return mapped;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Applies a function to every key-value pair in the dictionary.
+     */
+    map(mapFn) {
+        const newRecord = {};
+        for (const [key, value] of Object.entries(this.record)) {
+            newRecord[key] = mapFn(value, key);
+        }
+        return new Dictionary(newRecord);
+    }
+    /**
+     * Calls the specified callback function for all the elements in an array. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.
+     */
+    reduce(reducer, initialValue) {
+        return Object.entries(this.record).reduce((acc, [key, item]) => reducer(acc, item, key), initialValue);
+    }
+}

package/dist/equality.d.ts

@@ -0,0 +1,44 @@
+/**
+ * A function that compares two values for equality.
+ */
+export type Equality<T> = (a: T, b: T) => boolean;
+/**
+ * A function that compares two numbers for equality.
+ */
+export type NumberEquality = Equality<number>;
+/**
+ * Checks if the first number is less than the second number.
+ */
+export declare const lt: NumberEquality;
+/**
+ * Checks if the first number is less than or equal to the second number.
+ */
+export declare const lte: NumberEquality;
+/**
+ * Checks if the first number is greater than the second number.
+ */
+export declare const gt: NumberEquality;
+/**
+ * Checks if the first number is greater than or equal to the second number.
+ */
+export declare const gte: NumberEquality;
+/**
+ * Checks if two values are (shallowly) equal.
+ */
+export declare const equal: <T>(a: T, b: T) => boolean;
+/**
+ * Checks if two numbers are not (shallowly) equal.
+ */
+export declare const notEqual: <T>(a: T, b: T) => boolean;
+/**
+ * Checks if two arrays are equal. The values are compared shallowly.
+ *
+ * Use {@link deepEqual} for a deep equality check.
+ */
+export declare const arrayEqual: <T extends number | boolean | string | symbol | null | undefined>(arr1: T[], arr2: T[]) => boolean;
+/**
+ * Checks two values for value equality. This is a deep equality check that
+ * works for all types, including objects and arrays. For objects, it only
+ * compares all enumerable keys, no other properties or the prototype chain.
+ */
+export declare const deepEqual: <T>(a: T, b: T) => boolean;

package/dist/equality.js

@@ -0,0 +1,53 @@
+/**
+ * Checks if the first number is less than the second number.
+ */
+export const lt = (a, b) => a < b;
+/**
+ * Checks if the first number is less than or equal to the second number.
+ */
+export const lte = (a, b) => a <= b;
+/**
+ * Checks if the first number is greater than the second number.
+ */
+export const gt = (a, b) => a > b;
+/**
+ * Checks if the first number is greater than or equal to the second number.
+ */
+export const gte = (a, b) => a >= b;
+/**
+ * Checks if two values are (shallowly) equal.
+ */
+export const equal = (a, b) => Object.is(a, b);
+/**
+ * Checks if two numbers are not (shallowly) equal.
+ */
+export const notEqual = (a, b) => !Object.is(a, b);
+/**
+ * Checks if two arrays are equal. The values are compared shallowly.
+ *
+ * Use {@link deepEqual} for a deep equality check.
+ */
+export const arrayEqual = (arr1, arr2) => arr1.length === arr2.length &&
+    arr1.every((value, index) => equal(value, arr2[index]));
+/**
+ * Checks two values for value equality. This is a deep equality check that
+ * works for all types, including objects and arrays. For objects, it only
+ * compares all enumerable keys, no other properties or the prototype chain.
+ */
+export const deepEqual = (a, b) => {
+    if (equal(a, b)) {
+        return true;
+    }
+    if (typeof a === "object" &&
+        typeof b === "object" &&
+        a !== null &&
+        b !== null) {
+        const keys = Object.keys(a);
+        if (keys.length !== Object.keys(b).length) {
+            return false;
+        }
+        return keys.every((key) => key in b &&
+            deepEqual(a[key], b[key]));
+    }
+    return false;
+};

package/dist/function.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Returns a function that always returns the given value.
+ * @param value The value to return from the new function.
+ * @returns A new function that always returns the given value.
+ */
+export declare const constant: <T>(value: T) => () => T;
+/**
+ * Returns a function that applies the given predicates to the given value and
+ * returns `true` if all predicates return `true`.
+ */
+export declare const andEvery: <T>(...predicates: ((value: T) => boolean)[]) => (value: T) => boolean;
+export declare function orSome<T, U extends T, V extends T>(f: (value: T) => value is U, g: (value: T) => value is V): (value: T) => value is U | V;
+export declare function orSome<T>(...fns: ((value: T) => boolean)[]): (value: T) => boolean;
+/**
+ * Returns a function that applies the given predicate to the given value and
+ * returns the negated result.
+ */
+export declare const not: <T>(predicate: (value: T) => boolean) => (value: T) => boolean;
+/**
+ * Combines two values while applying an accessor to each value before combining them.
+ *
+ * This is useful for scenarios where you want to combine complex objects based on a specific property or derived value.
+ *
+ * @param accessor A function that extracts the value to be used for combination from each input.
+ * @param combinator A function that combines the two extracted values.
+ * @returns A new function that takes two inputs, applies the accessor to each, and combines the results using the combinator.
+ *
+ * @example
+ * ```ts
+ * interface Person {
+ *   name: string;
+ *   age: number;
+ * }
+ *
+ * const alice: Person = { name: "Alice", age: 30 };
+ * const bob: Person = { name: "Bob", age: 25 };
+ * const people: Person[] = [alice, bob];
+ *
+ * const compareByAge = on(
+ *   (person: Person) => person.age,
+ *   (age1, age2) => age1 - age2
+ * );
+ *
+ * const sortedPeople = people.sort(compareByAge);
+ * // Result: [{ name: "Bob", age: 25 }, { name: "Alice", age: 30 }]
+ * ```
+ */
+export declare const on: <T, U, V>(accessor: (value: T) => U, combinator: (a: U, b: U) => V) => ((a: T, b: T) => V);

package/dist/function.js

@@ -0,0 +1,52 @@
+/**
+ * Returns a function that always returns the given value.
+ * @param value The value to return from the new function.
+ * @returns A new function that always returns the given value.
+ */
+export const constant = (value) => () => value;
+/**
+ * Returns a function that applies the given predicates to the given value and
+ * returns `true` if all predicates return `true`.
+ */
+export const andEvery = (...predicates) => (value) => predicates.every((predicate) => predicate(value));
+/**
+ * Returns a function that combines predicate functions disjunctionally.
+ */
+export function orSome(...predicates) {
+    return (value) => predicates.some((predicate) => predicate(value));
+}
+/**
+ * Returns a function that applies the given predicate to the given value and
+ * returns the negated result.
+ */
+export const not = (predicate) => (value) => !predicate(value);
+/**
+ * Combines two values while applying an accessor to each value before combining them.
+ *
+ * This is useful for scenarios where you want to combine complex objects based on a specific property or derived value.
+ *
+ * @param accessor A function that extracts the value to be used for combination from each input.
+ * @param combinator A function that combines the two extracted values.
+ * @returns A new function that takes two inputs, applies the accessor to each, and combines the results using the combinator.
+ *
+ * @example
+ * ```ts
+ * interface Person {
+ *   name: string;
+ *   age: number;
+ * }
+ *
+ * const alice: Person = { name: "Alice", age: 30 };
+ * const bob: Person = { name: "Bob", age: 25 };
+ * const people: Person[] = [alice, bob];
+ *
+ * const compareByAge = on(
+ *   (person: Person) => person.age,
+ *   (age1, age2) => age1 - age2
+ * );
+ *
+ * const sortedPeople = people.sort(compareByAge);
+ * // Result: [{ name: "Bob", age: 25 }, { name: "Alice", age: 30 }]
+ * ```
+ */
+export const on = (accessor, combinator) => (a, b) => combinator(accessor(a), accessor(b));

package/dist/lazy.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A lazy value that is only evaluated when it is needed.
+ */
+export declare class Lazy<T> {
+    #private;
+    private constructor();
+    /**
+     * Creates a new lazy value.
+     */
+    static of<T>(f: () => T): Lazy<T>;
+    /**
+     * The value of the lazy value. If the value has not been evaluated
+     * yet, it will be evaluated and cached.
+     */
+    get value(): T;
+}

package/dist/lazy.js

@@ -0,0 +1,32 @@
+import { assertExhaustive } from "./typeSafety.js";
+/**
+ * A lazy value that is only evaluated when it is needed.
+ */
+export class Lazy {
+    #state;
+    constructor(f) {
+        this.#state = { kind: "unevaluated", f };
+    }
+    /**
+     * Creates a new lazy value.
+     */
+    static of(f) {
+        return new Lazy(f);
+    }
+    /**
+     * The value of the lazy value. If the value has not been evaluated
+     * yet, it will be evaluated and cached.
+     */
+    get value() {
+        switch (this.#state.kind) {
+            case "unevaluated": {
+                this.#state = { kind: "evaluated", value: this.#state.f() };
+                return this.#state.value;
+            }
+            case "evaluated":
+                return this.#state.value;
+            default:
+                return assertExhaustive(this.#state);
+        }
+    }
+}

package/dist/math.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The minus sign.
+ */
+export declare const minus = "\u2212";
+/**
+ * The plus/minus sign.
+ */
+export declare const plusMinus = "\u00B1";
+/**
+ * Forces signing on the given number, returning `undefined` on zero.
+ */
+export declare const signIgnoreZero: (x: number) => string | undefined;
+/**
+ * Forces signing on the given number.
+ */
+export declare const sign: (x: number) => string;
+/**
+ * Returns the sign of the given number. Returns `undefined` if the number is
+ * zero.
+ */
+export declare const signStr: (x: number) => string | undefined;
+/**
+ * Converts a string to an integer. If the string is not a valid integer, it
+ * returns `undefined`.
+ */
+export declare const parseInt: (str: string) => number | undefined;
+/**
+ * Converts a string to a natural number. If the string is not a valid natural
+ * number, it returns `undefined`.
+ */
+export declare const parseNat: (str: string) => number | undefined;
+/**
+ * Returns a random integer between `0` and `max` (inclusive).
+ */
+export declare const randomInt: (max: number) => number;
+/**
+ * Returns a random integer between `min` and `max` (inclusive).
+ */
+export declare const randomIntRange: (min: number, max: number) => number;
+/**
+ * Returns if the given number is even.
+ */
+export declare const even: (x: number) => boolean;
+/**
+ * Returns if the given number is odd.
+ */
+export declare const odd: (x: number) => boolean;

package/dist/math.js

@@ -0,0 +1,56 @@
+import { isInteger, isNaturalNumber } from "./regex.js";
+/**
+ * The minus sign.
+ */
+export const minus = "−";
+/**
+ * The plus/minus sign.
+ */
+export const plusMinus = "\xB1";
+/**
+ * Forces signing on the given number, returning `undefined` on zero.
+ */
+export const signIgnoreZero = (x) => x > 0
+    ? `+${x.toString()}`
+    : x < 0
+        ? `${minus}\u2060${Math.abs(x).toString()}`
+        : undefined;
+/**
+ * Forces signing on the given number.
+ */
+export const sign = (x) => x > 0
+    ? `+${x.toString()}`
+    : x < 0
+        ? `${minus}\u2060${Math.abs(x).toString()}`
+        : "0";
+/**
+ * Returns the sign of the given number. Returns `undefined` if the number is
+ * zero.
+ */
+export const signStr = (x) => x > 0 ? "+" : x < 0 ? minus : undefined;
+/**
+ * Converts a string to an integer. If the string is not a valid integer, it
+ * returns `undefined`.
+ */
+export const parseInt = (str) => str.length > 0 && isInteger(str) ? Number.parseInt(str, 10) : undefined;
+/**
+ * Converts a string to a natural number. If the string is not a valid natural
+ * number, it returns `undefined`.
+ */
+export const parseNat = (str) => str.length > 0 && isNaturalNumber(str) ? Number.parseInt(str, 10) : undefined;
+/**
+ * Returns a random integer between `0` and `max` (inclusive).
+ */
+export const randomInt = (max) => Math.floor(Math.random() * (max + 1));
+/**
+ * Returns a random integer between `min` and `max` (inclusive).
+ */
+export const randomIntRange = (min, max) => Math.floor(Math.random() * (max + 1 - min)) + min;
+/**
+ * Returns if the given number is even.
+ */
+export const even = (x) => x % 2 === 0;
+/**
+ * Returns if the given number is odd.
+ */
+export const odd = (x) => x % 2 !== 0;