@elyukai/utils 0.1.2

package/dist/array/nonEmpty.js

@@ -0,0 +1,15 @@
+/**
+ * Types and functions to check for non-empty arrays.
+ */
+/**
+ * Checks if the array is empty.
+ */
+export const isEmpty = (arr) => arr.length === 0;
+/**
+ * Checks if the array is not empty, i.e., contains at least one element.
+ */
+export const isNotEmpty = (arr) => !isEmpty(arr);
+/**
+ * Returns `undefined` if the array is empty, otherwise the non-empty array.
+ */
+export const ensureNonEmpty = (arr) => isNotEmpty(arr) ? arr : undefined;

package/dist/array/reductions.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Reduces an array, but stops as soon as the predicate returns `true` for an
+ * accumulated value (including the initial value) and returns the last
+ * accumulated value.
+ * @param arr The array to reduce.
+ * @param fn The function to apply to each element in the array.
+ * @param pred The predicate to apply to the initial value and to every result
+ * of a call to `fn`, where if it returns `true`, the reduction stops.
+ * @param initial The initial value.
+ */
+export declare const reduceWhile: <T, U>(arr: T[], fn: (acc: U, value: T, index: number) => U, pred: (acc: U) => boolean, initial: U) => U;
+/**
+ * Returns the sum of all numbers in the given array.
+ */
+export declare const sum: (arr: number[]) => number;
+/**
+ * Returns the sum of values returned by applying the given function to each
+ * element in the array.
+ */
+export declare const sumWith: <T>(arr: T[], fn: (value: T, index: number) => number) => number;
+/**
+ * Counts the number of elements in an array that satisfy the given predicate.
+ */
+export declare const count: <T>(arr: T[], predicate: (value: T, index: number) => boolean) => number;
+/**
+ * Counts the number of elements the function returns the same value for and
+ * returns the count for all returned values as an object.
+ */
+export declare const countBy: <T, K extends string | number | symbol>(arr: T[], fn: (value: T, index: number) => K) => Partial<Record<K, number>>;
+/**
+ * Counts the number of elements the function returns the same values for and
+ * returns the count for all returned values as an object.
+ */
+export declare const countByMany: <T, K extends string | number | symbol>(arr: T[], fn: (value: T, index: number) => K[]) => Partial<Record<K, number>>;
+/**
+ * Returns `true` if the array contains at least `minCount` elements that
+ * satisfy the given predicate, `false` otherwise.
+ */
+export declare const someCount: <T>(arr: T[], predicate: (value: T) => boolean, minCount: number) => boolean;

package/dist/array/reductions.js

@@ -0,0 +1,58 @@
+import { unique } from "./filters.js";
+/**
+ * Reduces an array, but stops as soon as the predicate returns `true` for an
+ * accumulated value (including the initial value) and returns the last
+ * accumulated value.
+ * @param arr The array to reduce.
+ * @param fn The function to apply to each element in the array.
+ * @param pred The predicate to apply to the initial value and to every result
+ * of a call to `fn`, where if it returns `true`, the reduction stops.
+ * @param initial The initial value.
+ */
+export const reduceWhile = (arr, fn, pred, initial) => {
+    let acc = initial;
+    let index = 0;
+    while (index < arr.length && !pred(acc)) {
+        acc = fn(acc, arr[index], index);
+        index++;
+    }
+    return acc;
+};
+/**
+ * Returns the sum of all numbers in the given array.
+ */
+export const sum = (arr) => arr.reduce((acc, value) => acc + value, 0);
+/**
+ * Returns the sum of values returned by applying the given function to each
+ * element in the array.
+ */
+export const sumWith = (arr, fn) => arr.reduce((acc, value, index) => acc + fn(value, index), 0);
+/**
+ * Counts the number of elements in an array that satisfy the given predicate.
+ */
+export const count = (arr, predicate) => sumWith(arr, (value, index) => (predicate(value, index) ? 1 : 0));
+/**
+ * Counts the number of elements the function returns the same value for and
+ * returns the count for all returned values as an object.
+ */
+export const countBy = (arr, fn) => arr.reduce((acc, value, index) => {
+    const key = fn(value, index);
+    acc[key] = (acc[key] ?? 0) + 1;
+    return acc;
+}, {});
+/**
+ * Counts the number of elements the function returns the same values for and
+ * returns the count for all returned values as an object.
+ */
+export const countByMany = (arr, fn) => arr.reduce((acc, value, index) => {
+    const keys = fn(value, index);
+    unique(keys).forEach((key) => {
+        acc[key] = (acc[key] ?? 0) + 1;
+    });
+    return acc;
+}, {});
+/**
+ * Returns `true` if the array contains at least `minCount` elements that
+ * satisfy the given predicate, `false` otherwise.
+ */
+export const someCount = (arr, predicate, minCount) => reduceWhile(arr, (acc, value) => (predicate(value) ? acc + 1 : acc), (acc) => acc >= minCount, 0) >= minCount;

package/dist/array/sets.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Calculates the difference between two arrays, including duplicated values.
+ * @param oldArr - The original array.
+ * @param newArr - The new array to compare against.
+ * @returns An object containing the added and removed elements.
+ */
+export declare const difference: <T>(oldArr: T[], newArr: T[]) => ArrayDiffResult<T>;
+export interface ArrayDiffResult<T> {
+    /**
+     * Elements in `newArr` that are not in `oldArr`.
+     */
+    added: T[];
+    /**
+     * Elements in `oldArr` that are not in `newArr`.
+     */
+    removed: T[];
+}

package/dist/array/sets.js

@@ -0,0 +1,19 @@
+import { removeAt } from "./modify.js";
+/**
+ * Calculates the difference between two arrays, including duplicated values.
+ * @param oldArr - The original array.
+ * @param newArr - The new array to compare against.
+ * @returns An object containing the added and removed elements.
+ */
+export const difference = (oldArr, newArr) => newArr.reduce((acc, item) => {
+    const oldIndex = acc.removed.indexOf(item);
+    const newIndex = acc.added.indexOf(item);
+    if (oldIndex > -1) {
+        return {
+            ...acc,
+            removed: removeAt(acc.removed, oldIndex),
+            added: removeAt(acc.added, newIndex),
+        };
+    }
+    return acc;
+}, { removed: oldArr, added: newArr });

package/dist/array.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Returns `true` if the two arrays are equal, `false` otherwise.
+ */
+export declare const arrayEqual: <T extends number | boolean | string | symbol | null | undefined>(arr1: T[], arr2: T[]) => boolean;

package/dist/array.js

@@ -0,0 +1,5 @@
+/**
+ * Returns `true` if the two arrays are equal, `false` otherwise.
+ */
+export const arrayEqual = (arr1, arr2) => arr1.length === arr2.length &&
+    arr1.every((value, index) => value === arr2[index]);

package/dist/async.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Returns a promise that resolves after a specified delay in milliseconds.
+ * @param delay The delay in milliseconds.
+ * @returns A promise that resolves after the specified delay.
+ *
+ * @example
+ * ```ts
+ * await wait(1000); // Waits for 1 second
+ * ```
+ */
+export declare const wait: (delay: number) => Promise<void>;

package/dist/async.js

@@ -0,0 +1,11 @@
+/**
+ * Returns a promise that resolves after a specified delay in milliseconds.
+ * @param delay The delay in milliseconds.
+ * @returns A promise that resolves after the specified delay.
+ *
+ * @example
+ * ```ts
+ * await wait(1000); // Waits for 1 second
+ * ```
+ */
+export const wait = (delay) => new Promise((resolve) => setTimeout(resolve, delay));

package/dist/classList.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Returns a string of class names from the given arguments. Filters out
+ * nullable values and keys with falsey values.
+ */
+export declare const classList: (...cls: (string | null | undefined | Record<string, boolean | undefined>)[]) => string;

package/dist/classList.js

@@ -0,0 +1,17 @@
+/**
+ * Returns a string of class names from the given arguments. Filters out
+ * nullable values and keys with falsey values.
+ */
+export const classList = (...cls) => cls
+    .flatMap((cl) => {
+    if (cl === null || cl === undefined) {
+        return [];
+    }
+    else if (typeof cl === "string") {
+        return [cl];
+    }
+    else {
+        return Object.entries(cl).flatMap(([k, v]) => (v === true ? [k] : []));
+    }
+})
+    .join(" ");

package/dist/compare.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The type of a compare function that can be used to sort values.
+ * @returns A negative number if `a` should be sorted before `b`, a positive
+ * number if `a` should be sorted after `b`, or zero if `a` and `b` are equal.
+ */
+export type Compare<T> = (a: T, b: T) => number;
+/**
+ * Build a compare function for values that are nested inside other values. The
+ * nested value is getting extracted by the provided accessor function and then
+ * compared using the provided compare function. An optional `reverse` parameter
+ * can be used to reverse the sort order.
+ */
+export declare const compareAt: <T, U>(accessor: (value: T) => U, compare: (a: U, b: U) => number, reverse?: boolean) => Compare<T>;
+/**
+ * Build a compare function that nests multiple compare functions. The functions
+ * are applied in order, so the first function is the primary sort key, the
+ * second function is the secondary sort key, and so on.
+ */
+export declare const reduceCompare: <T>(...compares: Compare<T>[]) => Compare<T>;
+/**
+ * Compare function for numbers that sorts them in ascending order.
+ */
+export declare const numAsc: Compare<number>;
+/**
+ * Higher-order compare function that extends a compare function to also handle
+ * `null` and `undefined` values. Nullish values are always sorted first.
+ */
+export declare const compareNullish: <T extends NonNullable<unknown>>(compare: Compare<T>) => (a: T | null | undefined, b: T | null | undefined) => number;
+/**
+ * A function that compares two values for equality.
+ */
+export type Equality<T> = (a: T, b: T) => boolean;
+/**
+ * Build an equality function for values that are nested inside other values.
+ * The nested value is getting extracted by the provided accessor function and
+ * then compared using the provided equality function.
+ */
+export declare const equalityAt: <T, U>(accessor: (value: T) => U, equality: Equality<U>) => Equality<T>;
+/**
+ * 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/compare.js

@@ -0,0 +1,73 @@
+import { isNullish } from "./nullable.js";
+/**
+ * Build a compare function for values that are nested inside other values. The
+ * nested value is getting extracted by the provided accessor function and then
+ * compared using the provided compare function. An optional `reverse` parameter
+ * can be used to reverse the sort order.
+ */
+export const compareAt = (accessor, compare, reverse = false) => (a, b) => {
+    const result = compare(accessor(a), accessor(b));
+    return reverse ? -result : result;
+};
+/**
+ * Build a compare function that nests multiple compare functions. The functions
+ * are applied in order, so the first function is the primary sort key, the
+ * second function is the secondary sort key, and so on.
+ */
+export const reduceCompare = (...compares) => (a, b) => {
+    for (const compare of compares) {
+        const result = compare(a, b);
+        if (result !== 0) {
+            return result;
+        }
+    }
+    return 0;
+};
+/**
+ * Compare function for numbers that sorts them in ascending order.
+ */
+export const numAsc = (a, b) => a - b;
+/**
+ * Higher-order compare function that extends a compare function to also handle
+ * `null` and `undefined` values. Nullish values are always sorted first.
+ */
+export const compareNullish = (compare) => (a, b) => {
+    if (isNullish(a) && isNullish(b)) {
+        return 0;
+    }
+    if (isNullish(a)) {
+        return -1;
+    }
+    if (isNullish(b)) {
+        return 1;
+    }
+    return compare(a, b);
+};
+/**
+ * Build an equality function for values that are nested inside other values.
+ * The nested value is getting extracted by the provided accessor function and
+ * then compared using the provided equality function.
+ */
+export const equalityAt = (accessor, equality) => (a, b) => equality(accessor(a), accessor(b));
+/**
+ * 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 (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/date.d.ts

@@ -0,0 +1,5 @@
+import { Compare } from "./compare.js";
+/**
+ * A comparator function for {@link Date} objects in ascending order.
+ */
+export declare const compareDate: Compare<Date>;

package/dist/date.js

@@ -0,0 +1,5 @@
+import { Compare } from "./compare.js";
+/**
+ * A comparator function for {@link Date} objects in ascending order.
+ */
+export const compareDate = (a, b) => a.getTime() - b.getTime();

package/dist/dictionary/native.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Introduces helper functions for a native dictionary, which is an index object.
+ */
+import type { AnyNonNullish } from "../nullable.js";
+/**
+ * An alias for a native dictionary.
+ */
+export type Dictionary<T extends AnyNonNullish | null> = Readonly<Record<string, T>>;
+/**
+ * An empty dictionary.
+ */
+export declare const empty: Dictionary<never>;
+/**
+ * Constructs a dictionary from an array of key-value pairs.
+ */
+export declare const 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.
+ */
+export declare const get: <T extends AnyNonNullish | null>(dict: Dictionary<T>, 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.
+ */
+export declare const getMap: <T extends AnyNonNullish | null, U>(dict: Dictionary<T>, key: string, mapFn: (value: T) => U) => U | undefined;
+/**
+ * Checks if the dictionary has the given key.
+ */
+export declare const has: <T extends AnyNonNullish | null>(dict: Dictionary<T>, key: string) => boolean;
+/**
+ * Sets the given key to the given value.
+ *
+ * If the key already exists, its value will be overwritten.
+ */
+export declare const set: <T extends AnyNonNullish | null>(dict: Dictionary<T>, 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.
+ */
+export declare const remove: <T extends AnyNonNullish | null>(dict: Dictionary<T>, key: string) => Dictionary<T>;
+/**
+ * Returns the number of entries in the dictionary.
+ */
+export declare const size: (dict: Dictionary<AnyNonNullish | null>) => number;
+/**
+ * Returns an array of key-value pairs in the dictionary.
+ */
+export declare const entries: <T extends AnyNonNullish | null>(dict: Dictionary<T>) => [string, T][];
+/**
+ * Returns an array of values in the dictionary.
+ */
+export declare const values: <T extends AnyNonNullish | null>(dict: Dictionary<T>) => T[];
+/**
+ * Returns an array of keys in the dictionary.
+ */
+export declare const keys: (dict: Dictionary<AnyNonNullish | null>) => string[];
+/**
+ * Calls the given function for each key-value pair in the dictionary.
+ */
+export declare const forEach: <T extends AnyNonNullish | null>(dict: Dictionary<T>, 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.
+ */
+export declare const forEachAsync: <T extends AnyNonNullish | null>(dict: Dictionary<T>, 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`.
+ */
+export declare const modify: <T extends AnyNonNullish | null>(dict: Dictionary<T>, 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.
+ */
+export declare const find: {
+    /**
+     * Returns the first value that matches the given predicate, or `undefined` if no such value exists.
+     */
+    <T extends AnyNonNullish | null, U extends T>(dict: Dictionary<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.
+     */
+    <T extends AnyNonNullish | null>(dict: Dictionary<T>, predicate: (value: T, key: string) => boolean): T | undefined;
+};
+/**
+ * Returns the first key that matches the given predicate, or `undefined` if no such key exists.
+ */
+export declare const findKey: <T extends AnyNonNullish | null>(dict: Dictionary<T>, 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.
+ */
+export declare const findEntry: {
+    /**
+     * Returns the first key-value pair that matches the given predicate, or `undefined` if no such key-value pair exists.
+     */
+    <T extends AnyNonNullish | null, U extends T>(dict: Dictionary<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.
+     */
+    <T extends AnyNonNullish | null>(dict: Dictionary<T>, 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.
+ */
+export declare const mapFirst: <T extends AnyNonNullish | null, U>(dict: Dictionary<T>, mapFn: (value: T, key: string) => U | undefined) => U | undefined;
+/**
+ * Applies a function to every key-value pair in the dictionary.
+ */
+export declare const map: <T extends AnyNonNullish | null, U extends AnyNonNullish | null>(dict: Dictionary<T>, 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.
+ */
+export declare const reduce: <T extends AnyNonNullish | null, U>(dict: Dictionary<T>, reducer: (acc: U, value: T, key: string) => U, initialValue: U) => U;

package/dist/dictionary/native.js

@@ -0,0 +1,142 @@
+/**
+ * Introduces helper functions for a native dictionary, which is an index object.
+ */
+import { omitKeys } from "../object.js";
+/**
+ * An empty dictionary.
+ */
+export const empty = {};
+/**
+ * Constructs a dictionary from an array of key-value pairs.
+ */
+export const fromEntries = (entries) => Object.fromEntries(entries);
+/**
+ * Returns the value associated with the given key, or `undefined` if the key does not exist.
+ */
+export const get = (dict, key) => dict[key];
+/**
+ * Returns the value associated with the given key mapped through the given function, or `undefined` if the key does not exist.
+ */
+export const getMap = (dict, key, mapFn) => {
+    const value = get(dict, key);
+    return value === undefined ? undefined : mapFn(value);
+};
+/**
+ * Checks if the dictionary has the given key.
+ */
+export const has = (dict, key) => Object.prototype.hasOwnProperty.call(dict, key);
+/**
+ * Sets the given key to the given value.
+ *
+ * If the key already exists, its value will be overwritten.
+ */
+export const set = (dict, key, value) => ({ ...dict, [key]: value });
+/**
+ * Removes the given key from the dictionary.
+ *
+ * If the key does not exist, the same dictionary instance is returned.
+ */
+export const remove = (dict, key) => {
+    if (has(dict, key)) {
+        return omitKeys(dict, key);
+    }
+    else {
+        return dict;
+    }
+};
+/**
+ * Returns the number of entries in the dictionary.
+ */
+export const size = (dict) => Object.keys(dict).length;
+/**
+ * Returns an array of key-value pairs in the dictionary.
+ */
+export const entries = (dict) => Object.entries(dict);
+/**
+ * Returns an array of values in the dictionary.
+ */
+export const values = (dict) => Object.values(dict);
+/**
+ * Returns an array of keys in the dictionary.
+ */
+export const keys = (dict) => Object.keys(dict);
+/**
+ * Calls the given function for each key-value pair in the dictionary.
+ */
+export const forEach = (dict, fn) => {
+    for (const [key, value] of Object.entries(dict)) {
+        fn(value, key);
+    }
+};
+/**
+ * Calls the given async function for each key-value pair in the dictionary.
+ *
+ * The calls are made sequentially.
+ */
+export const forEachAsync = async (dict, fn) => {
+    for (const [key, value] of Object.entries(dict)) {
+        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`.
+ */
+export const modify = (dict, key, modifyFn) => {
+    const currentValue = get(dict, key);
+    const newValue = modifyFn(currentValue);
+    if (newValue === undefined) {
+        return remove(dict, key);
+    }
+    else {
+        return set(dict, key, newValue);
+    }
+};
+/**
+ * Returns the first value that matches the given predicate, or `undefined` if no such value exists.
+ */
+export const find = (dict, predicate) => findEntry(dict, predicate)?.[1];
+/**
+ * Returns the first key that matches the given predicate, or `undefined` if no such key exists.
+ */
+export const findKey = (dict, predicate) => findEntry(dict, predicate)?.[0];
+/**
+ * Returns the first key-value pair that matches the given predicate, or `undefined` if no such key-value pair exists.
+ */
+export const findEntry = (dict, predicate) => {
+    for (const [key, value] of Object.entries(dict)) {
+        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.
+ */
+export const mapFirst = (dict, mapFn) => {
+    for (const [key, value] of Object.entries(dict)) {
+        const mapped = mapFn(value, key);
+        if (mapped !== undefined) {
+            return mapped;
+        }
+    }
+    return undefined;
+};
+/**
+ * Applies a function to every key-value pair in the dictionary.
+ */
+export const map = (dict, mapFn) => {
+    const newRecord = {};
+    for (const [key, value] of Object.entries(dict)) {
+        newRecord[key] = mapFn(value, key);
+    }
+    return 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.
+ */
+export const reduce = (dict, reducer, initialValue) => Object.entries(dict).reduce((acc, [key, item]) => reducer(acc, item, key), initialValue);