@elyukai/utils 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
+## [0.1.3](https://github.com/elyukai/ts-utils/compare/v0.1.2...v0.1.3) (2026-01-24)
+
 ## [0.1.2](https://github.com/elyukai/ts-utils/compare/v0.1.1...v0.1.2) (2026-01-24)
 
 

package/README.md

@@ -1 +1,15 @@
 # General TypeScript Helpers
+
+This package provides a range of utility functions that I personally often need, which is why I bundled them in a package.
+
+```ts
+import { isNotEmpty } from "@elyukai/utils/array/nonEmpty"
+
+const extractFirstNumberDoubled = (arr: number[]): number | undefined => {
+  if (isNotEmpty(arr)) {
+    return arr[0] * 2 // accessing index 0 is safe!
+  }
+
+  return undefined
+}
+```

package/dist/array/filters.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for filtering arrays.
+ * @module
+ */
 /**
  * Filters out duplicate values from an array. Objects are not supported, since
  * they don’t provide value equality semantics.

package/dist/array/filters.js

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for filtering arrays.
+ * @module
+ */
 /**
  * Filters out duplicate values from an array. Objects are not supported, since
  * they don’t provide value equality semantics.

package/dist/array/generators.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for generating new arrays.
+ * @module
+ */
 /**
  * Returns the possibilities of all the combinations of nested array values.
  *

package/dist/array/generators.js

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for generating new arrays.
+ * @module
+ */
 /**
  * Returns the possibilities of all the combinations of nested array values.
  *

package/dist/array/groups.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for grouping values in arrays.
+ * @module
+ */
 import type { Equality } from "../equality.ts";
 /**
  * Partitions an array into two arrays based on a predicate.

package/dist/array/groups.js

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for grouping values in arrays.
+ * @module
+ */
 /**
  * Partitions an array into two arrays based on a predicate.
  * @param arr The array to split.

package/dist/array/modify.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for modifying arrays.
+ * @module
+ */
 /**
  * Moves an element from one position to another within the array.
  */

package/dist/array/modify.js

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for modifying arrays.
+ * @module
+ */
 /**
  * Moves an element from one position to another within the array.
  */

package/dist/array/nonEmpty.d.ts

@@ -1,5 +1,6 @@
 /**
  * Types and functions to check for non-empty arrays.
+ * @module
  */
 /**
  * The empty array type.

package/dist/array/nonEmpty.js

@@ -1,5 +1,6 @@
 /**
  * Types and functions to check for non-empty arrays.
+ * @module
  */
 /**
  * Checks if the array is empty.

package/dist/array/reductions.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for building a single value from an array.
+ * @module
+ */
 /**
  * Reduces an array, but stops as soon as the predicate returns `true` for an
  * accumulated value (including the initial value) and returns the last

package/dist/array/reductions.js

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for building a single value from an array.
+ * @module
+ */
 import { unique } from "./filters.js";
 /**
  * Reduces an array, but stops as soon as the predicate returns `true` for an

package/dist/array/sets.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for set-like operations on arrays.
+ * @module
+ */
 /**
  * Calculates the difference between two arrays, including duplicated values.
  * @param oldArr - The original array.

package/dist/array/sets.js

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for set-like operations on arrays.
+ * @module
+ */
 import { removeAt } from "./modify.js";
 /**
  * Calculates the difference between two arrays, including duplicated values.

package/dist/async.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for asynchronous operations.
+ * @module
+ */
 /**
  * Returns a promise that resolves after a specified delay in milliseconds.
  * @param delay The delay in milliseconds.

package/dist/async.js

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for asynchronous operations.
+ * @module
+ */
 /**
  * Returns a promise that resolves after a specified delay in milliseconds.
  * @param delay The delay in milliseconds.

package/dist/classList.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for HTML classes.
+ * @module
+ */
 /**
  * Returns a string of class names from the given arguments. Filters out
  * nullable values and keys with falsey values.

package/dist/classList.js

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for HTML classes.
+ * @module
+ */
 /**
  * Returns a string of class names from the given arguments. Filters out
  * nullable values and keys with falsey values.

package/dist/dictionary/native.d.ts

@@ -1,5 +1,6 @@
 /**
  * Introduces helper functions for a native dictionary, which is an index object.
+ * @module
  */
 import type { AnyNonNullish } from "../nullable.js";
 /**

package/dist/dictionary/native.js

@@ -1,5 +1,6 @@
 /**
  * Introduces helper functions for a native dictionary, which is an index object.
+ * @module
  */
 import { omitKeys } from "../object.js";
 /**

package/dist/dictionary.d.ts

@@ -1,6 +1,6 @@
 /**
- * Introduces a Dictionary class that represents an immutable mapping from
- * strings to values.
+ * Introduces a Dictionary class that represents an immutable mapping from strings to values.
+ * @module
  */
 import type { AnyNonNullish } from "./nullable.js";
 /**

package/dist/dictionary.js

@@ -1,6 +1,6 @@
 /**
- * Introduces a Dictionary class that represents an immutable mapping from
- * strings to values.
+ * Introduces a Dictionary class that represents an immutable mapping from strings to values.
+ * @module
  */
 import { omitKeys } from "./object.js";
 /**

package/dist/equality.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for testing for equality.
+ * @module
+ */
 /**
  * A function that compares two values for equality.
  */

package/dist/equality.js

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for testing for equality.
+ * @module
+ */
 /**
  * Checks if the first number is less than the second number.
  */

package/dist/function.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for combining functions.
+ * @module
+ */
 /**
  * Returns a function that always returns the given value.
  * @param value The value to return from the new function.

package/dist/function.js

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for combining functions.
+ * @module
+ */
 /**
  * Returns a function that always returns the given value.
  * @param value The value to return from the new function.

package/dist/lazy.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Implementation of lazy-evaluated values.
+ * @module
+ */
 /**
  * A lazy value that is only evaluated when it is needed.
  */

package/dist/lazy.js

@@ -1,3 +1,7 @@
+/**
+ * Implementation of lazy-evaluated values.
+ * @module
+ */
 import { assertExhaustive } from "./typeSafety.js";
 /**
  * A lazy value that is only evaluated when it is needed.

package/dist/maybe.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Nullable values as a structure.
+ * @module
+ */
 /**
  * A maybe can contain a value or nothing.
  */

package/dist/maybe.js

@@ -1,3 +1,7 @@
+/**
+ * Nullable values as a structure.
+ * @module
+ */
 /**
  * Creates a maybe that contains a value.
  */

package/dist/nullable.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for working with values that might be `null` or `undefined`.
+ * @module
+ */
 /**
  * Extracts `null` and `undefined` from a type.
  */

package/dist/nullable.js

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for working with values that might be `null` or `undefined`.
+ * @module
+ */
 /**
  * Checks if a value is `null` or `undefined`.
  */

package/dist/number.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for numbers.
+ * @module
+ */
 /**
  * Returns a random integer between `0` and `max` (inclusive).
  */

package/dist/number.js

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for numbers.
+ * @module
+ */
 /**
  * Returns a random integer between `0` and `max` (inclusive).
  */

package/dist/object.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for objects.
+ * @module
+ */
 /**
  * Maps all own properties of an object to a new object. Returning `undefined`
  * from the mapping function will omit the property from the result.

package/dist/object.js

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for objects.
+ * @module
+ */
 /**
  * Maps all own properties of an object to a new object. Returning `undefined`
  * from the mapping function will omit the property from the result.

package/dist/ordering.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for ordering values.
+ * @module
+ */
 import { type AnyNonNullish } from "./nullable.js";
 /**
  * The type of a compare function that can be used to sort values.

package/dist/ordering.js

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for ordering values.
+ * @module
+ */
 import { isNullish } from "./nullable.js";
 /**
  * Build a compare function that nests multiple compare functions. The functions

package/dist/range.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for generating ranges and working with them.
+ * @module
+ */
 /**
  * A pair that specifies the lower (including) and upper (including) bounds of a
  * contiguous subrange of integer values.

package/dist/range.js

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for generating ranges and working with them.
+ * @module
+ */
 const normalizeBounds = (bounds) => bounds.length === 1 ? bounds[0] : bounds;
 /**
  * The list of values in the subrange defined by a bounding pair.

package/dist/result.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Implementation of a `Result` type that can structurally represent success or failure.
+ * @module
+ */
 /**
  * A result is either a value or an error.
  */

package/dist/result.js

@@ -1,3 +1,7 @@
+/**
+ * Implementation of a `Result` type that can structurally represent success or failure.
+ * @module
+ */
 /**
  * Creates a result that contains a value.
  */

package/dist/roman.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for roman numerals.
+ * @module
+ */
 /**
  * Converts a number to a roman numeral.
  */

package/dist/roman.js

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for roman numerals.
+ * @module
+ */
 import { minus } from "./string/number.js";
 const signPairs = [
     ["I", "V"],

package/dist/string/number.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for converting numbers to and from strings.
+ * @module
+ */
 /**
  * The minus sign.
  */

package/dist/string/number.js

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for converting numbers to and from strings.
+ * @module
+ */
 import { isInteger, isNaturalNumber } from "./regex.js";
 /**
  * The minus sign.

package/dist/string/regex.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Checks if strings match certain regular expressions.
+ * @module
+ */
 /**
  * Checks if the provided string is a string representation of a natural number.
  * @param test The string to test.

package/dist/string/regex.js

@@ -1,3 +1,7 @@
+/**
+ * Checks if strings match certain regular expressions.
+ * @module
+ */
 const naturalNumberPattern = /^(?:0|[1-9][0-9]*)$/u;
 const integerPattern = /^(?:0|-?[1-9][0-9]*)$/u;
 const floatPattern = /^(?:(?:0|-?[1-9][0-9]*)(?:[.,][0-9]+)?)$/u;

package/dist/string.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for strings.
+ * @module
+ */
 /**
  * Checks if a value is a non-empty string.
  */

package/dist/string.js

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for strings.
+ * @module
+ */
 /**
  * Checks if a value is a non-empty string.
  */

package/dist/typeSafety.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for enhancing type-safety.
+ * @module
+ */
 /**
  * This function is used to make sure that the `switch` is exhaustive. Place it
  * in the `default` case of the `switch`.

package/dist/typeSafety.js

@@ -1,3 +1,7 @@
+/**
+ * Utility functions for enhancing type-safety.
+ * @module
+ */
 /**
  * This function is used to make sure that the `switch` is exhaustive. Place it
  * in the `default` case of the `switch`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elyukai/utils",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "A set of JavaScript helper functions.",
   "files": [
     "dist",
@@ -36,6 +36,7 @@
     "@types/node": "^25.0.10",
     "commit-and-tag-version": "^12.6.1",
     "eslint": "^9.39.2",
+    "eslint-plugin-jsdoc": "^62.4.1",
     "glob": "^13.0.0",
     "prettier": "^3.8.1",
     "tsx": "^4.21.0",

package/dist/array.d.ts

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

@@ -1,5 +0,0 @@
-/**
- * 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/compare.d.ts

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

@@ -1,73 +0,0 @@
-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

@@ -1,5 +0,0 @@
-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

@@ -1,5 +0,0 @@
-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/math.d.ts

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

@@ -1,56 +0,0 @@
-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;

package/dist/regex.d.ts

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

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