@elyukai/utils 0.1.2

package/dist/maybe.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A maybe can contain a value or nothing.
+ */
+export type Maybe<T> = Just<T> | Nothing;
+/**
+ * A maybe that contains a value.
+ */
+export interface Just<T> {
+    readonly tag: "Just";
+    readonly value: T;
+}
+/**
+ * A maybe that contains nothing.
+ */
+export interface Nothing {
+    readonly tag: "Nothing";
+}
+/**
+ * Creates a maybe that contains a value.
+ */
+export declare const Just: <T>(value: T) => Maybe<T>;
+/**
+ * Checks if a maybe contains a value.
+ */
+export declare const isJust: <T>(result: Maybe<T>) => result is Just<T>;
+/**
+ * Creates a maybe that contains nothing.
+ */
+export declare const Nothing: Maybe<never>;
+/**
+ * Checks if a maybe contains nothing.
+ */
+export declare const isNothing: <T>(result: Maybe<T>) => result is Nothing;
+/**
+ * Creates a maybe from a nullable value.
+ */
+export declare const fromNullable: <T>(value: T) => Maybe<NonNullable<T>>;
+/**
+ * Reduces a maybe to a value of a common type.
+ */
+export declare const reduce: <T, R>(maybe: Maybe<T>, def: R, f: (value: T) => R) => R;
+/**
+ * Maps the value of a maybe to a new value.
+ */
+export declare const map: <T, U>(maybe: Maybe<T>, f: (value: T) => U) => Maybe<U>;
+/**
+ * Combines two maybes into one maybe. If both maybes contain a value, the
+ * values are combined using the provided function. If at least one maybe
+ * contains nothing, nothing is returned.
+ */
+export declare const combine: <T1, T2, TR>(maybe1: Maybe<T1>, maybe2: Maybe<T2>, f: (value1: T1, value2: T2) => TR) => Maybe<TR>;

package/dist/maybe.js

@@ -0,0 +1,36 @@
+/**
+ * Creates a maybe that contains a value.
+ */
+export const Just = (value) => ({ tag: "Just", value });
+/**
+ * Checks if a maybe contains a value.
+ */
+export const isJust = (result) => result.tag === "Just";
+/**
+ * Creates a maybe that contains nothing.
+ */
+export const Nothing = { tag: "Nothing" };
+/**
+ * Checks if a maybe contains nothing.
+ */
+export const isNothing = (result) => result.tag === "Nothing";
+/**
+ * Creates a maybe from a nullable value.
+ */
+export const fromNullable = (value) => value === null || value === undefined ? Nothing : Just(value);
+/**
+ * Reduces a maybe to a value of a common type.
+ */
+export const reduce = (maybe, def, f) => isJust(maybe) ? f(maybe.value) : def;
+/**
+ * Maps the value of a maybe to a new value.
+ */
+export const map = (maybe, f) => isJust(maybe) ? Just(f(maybe.value)) : Nothing;
+/**
+ * Combines two maybes into one maybe. If both maybes contain a value, the
+ * values are combined using the provided function. If at least one maybe
+ * contains nothing, nothing is returned.
+ */
+export const combine = (maybe1, maybe2, f) => isJust(maybe1) && isJust(maybe2)
+    ? Just(f(maybe1.value, maybe2.value))
+    : Nothing;

package/dist/nullable.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Extracts `null` and `undefined` from a type.
+ */
+export type Nullish<T = null | undefined> = T extends null | undefined ? T : never;
+export interface AnyNonNullish {
+}
+/**
+ * Checks if a value is `null` or `undefined`.
+ */
+export declare const isNullish: <T>(value: T) => value is Exclude<T, NonNullable<T>>;
+/**
+ * Checks if a value is not `null` or `undefined`.
+ */
+export declare const isNotNullish: <T>(value: T) => value is NonNullable<T>;
+/**
+ * Maps a value to another value if it is not `null` or `undefined`.
+ */
+export declare const mapNullable: <T, U>(value: T, map: (value: NonNullable<T>) => U) => U | Nullish<T>;
+/**
+ * Maps a value to another value if it is not `null` or `undefined`, otherwise
+ * returns a default value.
+ */
+export declare const mapNullableDefault: <T, U>(value: T, map: (value: NonNullable<T>) => U, defaultValue: U) => U;
+/**
+ * Returns an array, containing the value if it is not `null` or `undefined`.
+ *
+ * This can be useful in combination with the spread operator or
+ * `Array.prototype.flatMap`.
+ * @example
+ * nullableToArray(2) // [2]
+ * nullableToArray(undefined) // []
+ *
+ * [...nullableToArray(2)] // [2]
+ * [1, ...nullableToArray(2)] // [1, 2]
+ * [1, ...nullableToArray(undefined)] // [1]
+ */
+export declare const nullableToArray: <T>(value: T) => NonNullable<T>[];
+/**
+ * Returns the value if it matches the given predicate, otherwise `undefined`.
+ */
+export declare const ensure: {
+    /**
+     * Returns the value if it matches the given predicate, otherwise `undefined`.
+     */
+    <T, T1 extends T>(value: T, predicate: (value: T) => value is T1): T1 | undefined;
+    /**
+     * Returns the value if it matches the given predicate, otherwise `undefined`.
+     */
+    <T>(value: T, predicate: (value: T) => boolean): T | undefined;
+};

package/dist/nullable.js

@@ -0,0 +1,35 @@
+/**
+ * Checks if a value is `null` or `undefined`.
+ */
+export const isNullish = (value) => value === null || value === undefined;
+/**
+ * Checks if a value is not `null` or `undefined`.
+ */
+export const isNotNullish = (value) => !isNullish(value);
+/**
+ * Maps a value to another value if it is not `null` or `undefined`.
+ */
+export const mapNullable = (value, map) => (isNotNullish(value) ? map(value) : value);
+/**
+ * Maps a value to another value if it is not `null` or `undefined`, otherwise
+ * returns a default value.
+ */
+export const mapNullableDefault = (value, map, defaultValue) => (isNotNullish(value) ? map(value) : defaultValue);
+/**
+ * Returns an array, containing the value if it is not `null` or `undefined`.
+ *
+ * This can be useful in combination with the spread operator or
+ * `Array.prototype.flatMap`.
+ * @example
+ * nullableToArray(2) // [2]
+ * nullableToArray(undefined) // []
+ *
+ * [...nullableToArray(2)] // [2]
+ * [1, ...nullableToArray(2)] // [1, 2]
+ * [1, ...nullableToArray(undefined)] // [1]
+ */
+export const nullableToArray = (value) => isNotNullish(value) ? [value] : [];
+/**
+ * Returns the value if it matches the given predicate, otherwise `undefined`.
+ */
+export const ensure = (value, predicate) => predicate(value) ? value : undefined;

package/dist/number.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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/number.js

@@ -0,0 +1,16 @@
+/**
+ * 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;

package/dist/object.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Maps all own properties of an object to a new object. Returning `undefined`
+ * from the mapping function will omit the property from the result.
+ */
+export declare const mapObject: <T extends object, U>(object: T, map: (value: T[keyof T], key: keyof T) => U | undefined) => { [key in keyof T]: Exclude<U, undefined>; };
+/**
+ * Sorts the keys of an object based on the order of the provided keys array.
+ *
+ * Keys not present in the keys array will be placed at the end in their original order.
+ */
+export declare const sortObjectKeysByIndex: (obj: Record<string, unknown>, keys: string[]) => Record<string, unknown>;
+/**
+ * Sorts the keys of an object using the provided comparison function.
+ *
+ * By default, it sorts the keys in ascending lexicographical order.
+ */
+export declare const sortObjectKeys: (obj: Record<string, unknown>, fn?: (a: string, b: string) => number) => Record<string, unknown>;
+/**
+ * Merges two objects. In case of key conflicts, the `solveConflict` function
+ * is used to determine the value for the conflicting key.
+ */
+export declare const mergeObjects: <T>(obj1: Record<string, T>, obj2: Record<string, T>, solveConflict: (a: T, b: T) => T) => Record<string, T>;
+/**
+ * Keeps only the given keys in an object.
+ */
+export declare const onlyKeys: <T extends object, K extends keyof T>(obj: T, ...keys: K[]) => Pick<T, K>;
+/**
+ * Determines whether an object has a property with the specified name.
+ *
+ * Provides a type guard to assert the presence of the key, in contrast to the native `Object.hasOwn`.
+ */
+export declare const hasKey: <T extends object, K extends PropertyKey>(obj: T, key: K) => obj is T & Record<K, unknown>;
+/**
+ * Omits all keys with `undefined` values from an object.
+ */
+export declare const omitUndefinedKeys: <T extends object>(obj: T) => T;
+/**
+ * Omits the given keys from an object.
+ */
+export declare const omitKeys: <T extends object, K extends keyof T>(obj: T, ...keys: K[]) => Omit<T, K>;

package/dist/object.js

@@ -0,0 +1,58 @@
+/**
+ * Maps all own properties of an object to a new object. Returning `undefined`
+ * from the mapping function will omit the property from the result.
+ */
+export const mapObject = (object, map) => {
+    const result = {};
+    for (const key in object) {
+        if (Object.hasOwn(object, key)) {
+            const newValue = map(object[key], key);
+            if (newValue !== undefined) {
+                result[key] = newValue;
+            }
+        }
+    }
+    return result;
+};
+/**
+ * Sorts the keys of an object based on the order of the provided keys array.
+ *
+ * Keys not present in the keys array will be placed at the end in their original order.
+ */
+export const sortObjectKeysByIndex = (obj, keys) => Object.fromEntries([
+    ...keys.flatMap((key) => obj[key] === undefined ? [] : [[key, obj[key]]]),
+    ...Object.entries(obj).filter(([key]) => !keys.includes(key)),
+]);
+/**
+ * Sorts the keys of an object using the provided comparison function.
+ *
+ * By default, it sorts the keys in ascending lexicographical order.
+ */
+export const sortObjectKeys = (obj, fn = (a, b) => a.localeCompare(b)) => Object.fromEntries(Object.entries(obj).sort(([keyA], [keyB]) => fn(keyA, keyB)));
+/**
+ * Merges two objects. In case of key conflicts, the `solveConflict` function
+ * is used to determine the value for the conflicting key.
+ */
+export const mergeObjects = (obj1, obj2, solveConflict) => Object.entries(obj2).reduce((acc, [key, value]) => ({
+    ...acc,
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    [key]: Object.hasOwn(acc, key) ? solveConflict(acc[key], value) : value,
+}), obj1);
+/**
+ * Keeps only the given keys in an object.
+ */
+export const onlyKeys = (obj, ...keys) => Object.fromEntries(Object.entries(obj).filter(([key]) => keys.includes(key)));
+/**
+ * Determines whether an object has a property with the specified name.
+ *
+ * Provides a type guard to assert the presence of the key, in contrast to the native `Object.hasOwn`.
+ */
+export const hasKey = (obj, key) => Object.hasOwn(obj, key);
+/**
+ * Omits all keys with `undefined` values from an object.
+ */
+export const omitUndefinedKeys = (obj) => Object.fromEntries(Object.entries(obj).filter(([, value]) => value !== undefined));
+/**
+ * Omits the given keys from an object.
+ */
+export const omitKeys = (obj, ...keys) => Object.fromEntries(Object.entries(obj).filter(([key]) => !keys.includes(key)));

package/dist/ordering.d.ts

@@ -0,0 +1,30 @@
+import { type AnyNonNullish } from "./nullable.js";
+/**
+ * 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 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 compareNumber: Compare<number>;
+/**
+ * Compare function for {@link Date} objects in ascending order.
+ */
+export declare const compareDate: Compare<Date>;
+/**
+ * Higher-order compare function that extends a compare function to also handle
+ * `null` and `undefined` values. Nullish values are always sorted last.
+ */
+export declare const compareNullish: <T extends AnyNonNullish>(compare: Compare<T>) => (a: T | null | undefined, b: T | null | undefined) => number;
+/**
+ * A function that reverses the order of a compare function.
+ */
+export declare const reverse: <T>(compare: Compare<T>) => Compare<T>;

package/dist/ordering.js

@@ -0,0 +1,46 @@
+import { isNullish } from "./nullable.js";
+/**
+ * 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 compareNumber = (a, b) => a - b;
+/**
+ * Compare function for {@link Date} objects in ascending order.
+ */
+export const compareDate = (a, b) => a.getTime() - b.getTime();
+/**
+ * Higher-order compare function that extends a compare function to also handle
+ * `null` and `undefined` values. Nullish values are always sorted last.
+ */
+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);
+};
+/**
+ * A function that reverses the order of a compare function.
+ */
+export const reverse = (compare) => (a, b) => {
+    const res = compare(a, b);
+    return res === 0 ? 0 : -res;
+};

package/dist/range.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A pair that specifies the lower (including) and upper (including) bounds of a
+ * contiguous subrange of integer values.
+ */
+export type RangeBounds = [lowerBound: number, upperBound: number];
+/**
+ * The list of values in the subrange defined by a bounding pair.
+ * @throws {RangeError} If the upper bound is lower than the lower bound.
+ */
+export declare const range: {
+    (...args: RangeBounds): number[];
+    (bounds: RangeBounds): number[];
+};
+/**
+ * Returns a range of numbers between and including two numbers. The order of
+ * the arguments does not matter.
+ * @param start The first number in the range.
+ * @param end The last number in the range.
+ */
+export declare const rangeSafe: {
+    (...args: RangeBounds): number[];
+    (bounds: RangeBounds): number[];
+};
+/**
+ * Checks whether the passed `value` is within the range specified by the passed
+ * `bounds`.
+ */
+export declare const isInRange: (bounds: RangeBounds, value: number) => boolean;
+/**
+ * Returns the index of a value in a range.
+ * @throws {RangeError} If the passed `value` is not within the range specified.
+ */
+export declare const indexInRange: (bounds: RangeBounds, value: number) => number;
+/**
+ * Returns the size of the range defined by the passed bounds.
+ */
+export declare const rangeSize: (bounds: RangeBounds) => number;

package/dist/range.js

@@ -0,0 +1,41 @@
+const normalizeBounds = (bounds) => bounds.length === 1 ? bounds[0] : bounds;
+/**
+ * The list of values in the subrange defined by a bounding pair.
+ * @throws {RangeError} If the upper bound is lower than the lower bound.
+ */
+export const range = (...args) => {
+    const [start, end] = normalizeBounds(args);
+    if (start > end) {
+        throw new RangeError("The upper bound must be greater than or equal to the lower bound.");
+    }
+    return Array.from({ length: end - start + 1 }, (_, i) => i + start);
+};
+/**
+ * Returns a range of numbers between and including two numbers. The order of
+ * the arguments does not matter.
+ * @param start The first number in the range.
+ * @param end The last number in the range.
+ */
+export const rangeSafe = (...args) => {
+    const [start, end] = normalizeBounds(args);
+    return start > end ? range(end, start) : range(start, end);
+};
+/**
+ * Checks whether the passed `value` is within the range specified by the passed
+ * `bounds`.
+ */
+export const isInRange = (bounds, value) => value >= bounds[0] && value <= bounds[1];
+/**
+ * Returns the index of a value in a range.
+ * @throws {RangeError} If the passed `value` is not within the range specified.
+ */
+export const indexInRange = (bounds, value) => {
+    if (!isInRange(bounds, value)) {
+        throw new RangeError(`indexInRange: index for ${value.toString()} is out of range (${bounds[0].toString()}...${bounds[1].toString()})`);
+    }
+    return value - bounds[0];
+};
+/**
+ * Returns the size of the range defined by the passed bounds.
+ */
+export const rangeSize = (bounds) => bounds[0] <= bounds[1] ? bounds[1] - bounds[0] + 1 : 0;

package/dist/regex.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Checks if the provided string is a string representation of a natural number.
+ * @param test The string to test.
+ */
+export declare const isNaturalNumber: (test: string) => boolean;
+/**
+ * Checks if the provided string is a string representation of an integer.
+ * @param test The string to test.
+ */
+export declare const isInteger: (test: string) => boolean;
+/**
+ * Checks if the provided string is a string representation of a floating-point
+ * number. Both `.` and `,` are accepted as decimal separators.
+ * @param test The string to test.
+ */
+export declare const isFloat: (test: string) => boolean;
+/**
+ * Checks if the provided string either is an empty string or passes the given
+ * test function.
+ * @param check The test function to apply if the string is not empty.
+ * @param test The string to test.
+ */
+export declare const isEmptyOr: (check: (test: string) => boolean, test: string) => boolean;
+/**
+ * Checks if the provided string is a valid URL.
+ * @param test The string to test.
+ */
+export declare const isUrl: (test: string) => boolean;

package/dist/regex.js

@@ -0,0 +1,35 @@
+/**
+ * Checks if the provided string is a string representation of a natural number.
+ * @param test The string to test.
+ */
+export const isNaturalNumber = (test) => /^(?:0|[1-9][0-9]*)$/u.test(test);
+/**
+ * Checks if the provided string is a string representation of an integer.
+ * @param test The string to test.
+ */
+export const isInteger = (test) => /^(?:0|-?[1-9][0-9]*)$/u.test(test);
+/**
+ * Checks if the provided string is a string representation of a floating-point
+ * number. Both `.` and `,` are accepted as decimal separators.
+ * @param test The string to test.
+ */
+export const isFloat = (test) => /^(?:(?:0|-?[1-9][0-9]*)(?:[.,][0-9]+)?)$/u.test(test);
+/**
+ * Checks if the provided string either is an empty string or passes the given
+ * test function.
+ * @param check The test function to apply if the string is not empty.
+ * @param test The string to test.
+ */
+export const isEmptyOr = (check, test) => test === "" || check(test);
+/**
+ * Checks if the provided string is a valid URL.
+ * @param test The string to test.
+ */
+export const isUrl = (test) => {
+    try {
+        return typeof new URL(test) === "object";
+    }
+    catch {
+        return false;
+    }
+};

package/dist/result.d.ts

@@ -0,0 +1,54 @@
+/**
+ * A result is either a value or an error.
+ */
+export type Result<T, E> = Ok<T> | Error<E>;
+/**
+ * A result that contains a value.
+ */
+export interface Ok<T> {
+    readonly tag: "Ok";
+    readonly value: T;
+}
+/**
+ * A result that contains an error.
+ */
+export interface Error<E> {
+    readonly tag: "Error";
+    readonly error: E;
+}
+/**
+ * Creates a result that contains a value.
+ */
+export declare const ok: <T>(value: T) => Result<T, never>;
+/**
+ * Checks if a result contains a value.
+ */
+export declare const isOk: <T, E>(result: Result<T, E>) => result is Ok<T>;
+/**
+ * Creates a result that contains an error.
+ */
+export declare const error: <E>(error: E) => Result<never, E>;
+/**
+ * Checks if a result contains an error.
+ */
+export declare const isError: <T, E>(result: Result<T, E>) => result is Error<E>;
+/**
+ * Reduces a result to a value of a common type.
+ */
+export declare const reduce: <T, E, R>(result: Result<T, E>, fok: (value: T) => R, ferror: (error: E) => R) => R;
+/**
+ * Maps the value of a result to a new value.
+ */
+export declare const map: <T, U, E>(result: Result<T, E>, f: (value: T) => U) => Result<U, E>;
+/**
+ * Maps an error to a new error.
+ */
+export declare const mapError: <T, E, F>(result: Result<T, E>, f: (value: E) => F) => Result<T, F>;
+/**
+ * Combines two results into one.
+ *
+ * If both results are Ok, applies `fok` to their values and returns an Ok result.
+ * If both results are Error, applies `ferror` to their errors and returns an Error result.
+ * If one result is Ok and the other is Error, returns the Error result.
+ */
+export declare const combine: <T1, T2, TR, E1, E2, ER>(result1: Result<T1, E1>, result2: Result<T2, E2>, fok: (value1: T1, value2: T2) => TR, ferror: (error1: E1, error2: E2) => ER) => Result<TR, E1 | E2 | ER>;

package/dist/result.js

@@ -0,0 +1,45 @@
+/**
+ * Creates a result that contains a value.
+ */
+export const ok = (value) => ({ tag: "Ok", value });
+/**
+ * Checks if a result contains a value.
+ */
+export const isOk = (result) => result.tag === "Ok";
+/**
+ * Creates a result that contains an error.
+ */
+export const error = (error) => ({
+    tag: "Error",
+    error,
+});
+/**
+ * Checks if a result contains an error.
+ */
+export const isError = (result) => result.tag === "Error";
+/**
+ * Reduces a result to a value of a common type.
+ */
+export const reduce = (result, fok, ferror) => (isOk(result) ? fok(result.value) : ferror(result.error));
+/**
+ * Maps the value of a result to a new value.
+ */
+export const map = (result, f) => (isOk(result) ? ok(f(result.value)) : result);
+/**
+ * Maps an error to a new error.
+ */
+export const mapError = (result, f) => (isError(result) ? error(f(result.error)) : result);
+/**
+ * Combines two results into one.
+ *
+ * If both results are Ok, applies `fok` to their values and returns an Ok result.
+ * If both results are Error, applies `ferror` to their errors and returns an Error result.
+ * If one result is Ok and the other is Error, returns the Error result.
+ */
+export const combine = (result1, result2, fok, ferror) => isOk(result1)
+    ? isOk(result2)
+        ? ok(fok(result1.value, result2.value))
+        : result2
+    : isOk(result2)
+        ? result1
+        : error(ferror(result1.error, result2.error));

package/dist/roman.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Converts a number to a roman numeral.
+ */
+export declare const romanize: (num: number) => string;