shelving 1.236.0 → 1.236.2

package/util/random.js

@@ -1,9 +1,37 @@
 import { requireDefined } from "./undefined.js";
-/** Generate a random integer between two numbers. */
+/**
+ * Generate a random integer between two numbers (inclusive).
+ *
+ * @param min Lowest possible integer to return — defaults to `Number.MIN_SAFE_INTEGER`.
+ * @param max Highest possible integer to return — defaults to `Number.MAX_SAFE_INTEGER`.
+ * @returns Random integer in the range `min` to `max` (inclusive).
+ *
+ * @example
+ * ```ts
+ * const dice = getRandom(1, 6); // e.g. `4`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/random/getRandom
+ */
 export function getRandom(min = Number.MIN_SAFE_INTEGER, max = Number.MAX_SAFE_INTEGER) {
     return Math.round(Math.random() * (max - min) + min);
 }
-/** Get a random number that is anything except an existing number. */
+/**
+ * Get a random integer that is anything except an existing number.
+ * - Repeatedly draws a random integer until it differs from `existing`.
+ *
+ * @param existing Number that must not be returned.
+ * @param min Lowest possible integer to return — defaults to `Number.MIN_SAFE_INTEGER`.
+ * @param max Highest possible integer to return — defaults to `Number.MAX_SAFE_INTEGER`.
+ * @returns Random integer in the range `min` to `max` that is not equal to `existing`.
+ *
+ * @example
+ * ```ts
+ * const next = getRandomExcept(current, 1, 6); // any of `1`–`6` except `current`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/random/getRandomExcept
+ */
 export function getRandomExcept(existing, min, max) {
     let num;
     do
@@ -16,6 +44,16 @@ export function getRandomExcept(existing, min, max) {
  * - Not designed to be cryptographically random!
  * - Will probably clash — if you're making a random ID, check for existence of the record before saving.
  * - Designed to be semi-readable, doesn't use capital letters or `i` or `o` or `l` or `u`
+ *
+ * @param length Number of characters in the returned key — defaults to `12`.
+ * @returns Random string of `length` lowercase alphanumeric characters.
+ *
+ * @example
+ * ```ts
+ * const id = getRandomKey(); // e.g. `xs23r34hhsdx`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/random/getRandomKey
  */
 export function getRandomKey(length = 12) {
     return Array.from({ length }, getRandomKeyCharacter).join("");
@@ -24,11 +62,36 @@ const KEY_CHARS = "0123456789abcdefghjkmnpqrstvwxyz";
 function getRandomKeyCharacter() {
     return getRandomCharacter(KEY_CHARS);
 }
-/** Get a random character from a string. */
+/**
+ * Get a random character from a string.
+ *
+ * @param str String to pick a character from.
+ * @returns Single character chosen at random from `str`.
+ *
+ * @example
+ * ```ts
+ * const letter = getRandomCharacter("abcde"); // e.g. `"c"`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/random/getRandomCharacter
+ */
 export function getRandomCharacter(str) {
     return str[getRandom(0, str.length - 1)];
 }
-/** Get a random item from an array or random character from a string string. */
+/**
+ * Get a random item from an array.
+ *
+ * @param arr Array to pick an item from.
+ * @returns Single item chosen at random from `arr`.
+ * @throws RequiredError If the chosen item is undefined (e.g. the array is empty).
+ *
+ * @example
+ * ```ts
+ * const item = getRandomItem(["a", "b", "c"]); // e.g. `"b"`
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/util/random/getRandomItem
+ */
 export function getRandomItem(arr) {
     return requireDefined(arr[getRandom(0, arr.length - 1)]);
 }

package/util/regexp.d.ts

@@ -1,48 +1,150 @@
 import { type ImmutableArray } from "./array.js";
 import { type Nullish } from "./null.js";
 import type { NotString } from "./string.js";
-/** A thing that a string can be matched against. */
+/**
+ * A thing that a string can be matched against.
+ * - Either a `RegExp` instance, or a `string` that is matched using `===` equality.
+ *
+ * @see https://dhoulb.github.io/shelving/util/regexp/Matchable
+ */
 export type Matchable = string | RegExp;
-/** A list of things that strings can be matched against. */
+/**
+ * A list of things that strings can be matched against.
+ *
+ * @see https://dhoulb.github.io/shelving/util/regexp/Matchables
+ */
 export type Matchables = ImmutableArray<Nullish<Matchable>>;
-/** Regular expression that always matches everything. */
+/**
+ * Regular expression that always matches everything.
+ *
+ * @see https://dhoulb.github.io/shelving/util/regexp/ALWAYS_REGEXP
+ */
 export declare const ALWAYS_REGEXP: RegExp;
-/** Regular expression that never matches anything. */
+/**
+ * Regular expression that never matches anything.
+ *
+ * @see https://dhoulb.github.io/shelving/util/regexp/NEVER_REGEXP
+ */
 export declare const NEVER_REGEXP: RegExp;
-/** Things that can be convert to a regular expression. */
+/**
+ * Things that can be converted to a regular expression.
+ * - Either a `RegExp` instance, or a `string` source for a regular expression.
+ *
+ * @see https://dhoulb.github.io/shelving/util/regexp/PossibleRegExp
+ */
 export type PossibleRegExp = string | RegExp;
-/** Is an unknown value a `RegExp` instance? */
+/**
+ * Is an unknown value a `RegExp` instance?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is a `RegExp` instance, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/regexp/isRegExp
+ */
 export declare function isRegExp(value: unknown): value is RegExp;
-/** Assert that an unknown value is a `RegExp` instance. */
+/**
+ * Assert that an unknown value is a `RegExp` instance.
+ *
+ * @param value The value to assert.
+ * @throws {RequiredError} If `value` is not a `RegExp` instance.
+ * @see https://dhoulb.github.io/shelving/util/regexp/assertRegExp
+ */
 export declare function assertRegExp(value: unknown): asserts value is RegExp;
-/** Convert a string to a regular expression that matches that string. */
+/**
+ * Convert a possible regular expression into a `RegExp` instance.
+ * - If `pattern` is a `string` a new `RegExp` is created from it, otherwise it is returned as-is.
+ *
+ * @param pattern The regular expression or string source to convert.
+ * @param flags The flags to use when creating a `RegExp` from a string source.
+ * @returns The corresponding `RegExp` instance.
+ * @example
+ * getRegExp("abc", "i"); // /abc/i
+ * @see https://dhoulb.github.io/shelving/util/regexp/getRegExp
+ */
 export declare function getRegExp<T extends NamedRegExpData>(pattern: NamedRegExp<T>, flags?: string): T extends NamedRegExpData ? NamedRegExp<T> : RegExp;
 export declare function getRegExp<T extends NamedRegExpData | undefined = undefined>(pattern: PossibleRegExp, flags?: string): T extends NamedRegExpData ? NamedRegExp<T> : RegExp;
-/** Convert a regular expression to its string source. */
+/**
+ * Convert a regular expression to its string source.
+ * - If `regexp` is a `string` it is returned as-is, otherwise its `.source` is returned.
+ *
+ * @param regexp The regular expression or string source to read.
+ * @returns The string source of the regular expression.
+ * @example
+ * getRegExpSource(/abc/); // "abc"
+ * @see https://dhoulb.github.io/shelving/util/regexp/getRegExpSource
+ */
 export declare function getRegExpSource(regexp: PossibleRegExp): string;
-/** Escape special characters in a string regular expression. */
+/**
+ * Escape special characters in a string regular expression.
+ * - Escapes any characters that have special meaning in a regular expression so the string matches literally.
+ *
+ * @param pattern The string to escape.
+ * @returns The escaped string, safe to use as a literal regular expression source.
+ * @example
+ * escapeRegExp("a.b"); // "a\\.b"
+ * @see https://dhoulb.github.io/shelving/util/regexp/escapeRegExp
+ */
 export declare function escapeRegExp(pattern: string): string;
-/** Create regular expression that matches any of a list of other expressions. */
+/**
+ * Create a regular expression that matches any one of a list of other expressions.
+ * - If the list is empty the returned expression matches nothing (`NEVER_REGEXP`).
+ *
+ * @param patterns The regular expressions or string sources to combine.
+ * @param flags The flags to use when creating the combined `RegExp`.
+ * @returns A `RegExp` that matches if any of the provided expressions match.
+ * @example
+ * createRegExpAny(["abc", "def"]); // /(?:abc)|(?:def)/
+ * @see https://dhoulb.github.io/shelving/util/regexp/createRegExpAny
+ */
 export declare function createRegExpAny(patterns: Iterable<PossibleRegExp> & NotString, flags?: string): RegExp;
-/** Create regular expression that matches all of a list of other expressions. */
+/**
+ * Create a regular expression that matches all of a list of other expressions.
+ * - If the list is empty the returned expression matches everything (`ALWAYS_REGEXP`).
+ *
+ * @param patterns The regular expressions or string sources to combine.
+ * @param flags The flags to use when creating the combined `RegExp`.
+ * @returns A `RegExp` that matches only if all of the provided expressions match.
+ * @example
+ * createRegExpAll(["abc", "def"]); // /^(?=.*?(?:abc))(?=.*?(?:def))/
+ * @see https://dhoulb.github.io/shelving/util/regexp/createRegExpAll
+ */
 export declare function createRegExpAll(patterns: Iterable<PossibleRegExp> & NotString, flags?: string): RegExp;
-/** Regular expression match array that matches a specific string format. */
+/**
+ * Regular expression match array whose full match is a specific string format.
+ *
+ * @see https://dhoulb.github.io/shelving/util/regexp/TypedRegExpExecArray
+ */
 export interface TypedRegExpExecArray<T extends string = string> extends RegExpExecArray {
     0: T;
 }
-/** Regular expression that matches a specific string format. */
+/**
+ * Regular expression that matches a specific string format.
+ *
+ * @see https://dhoulb.github.io/shelving/util/regexp/TypedRegExp
+ */
 export interface TypedRegExp<T extends string = string> extends RegExp {
     exec(input: string): TypedRegExpExecArray<T> | null;
 }
-/** Set of named match groups from a regular expression. */
+/**
+ * Set of named match groups from a regular expression.
+ *
+ * @see https://dhoulb.github.io/shelving/util/regexp/NamedRegExpData
+ */
 export type NamedRegExpData = {
     [named: string]: string;
 };
-/** Regular expression match array that contains the specified named groups. */
+/**
+ * Regular expression match array that contains the specified named groups.
+ *
+ * @see https://dhoulb.github.io/shelving/util/regexp/NamedRegExpExecArray
+ */
 export interface NamedRegExpExecArray<T extends NamedRegExpData = NamedRegExpData> extends RegExpExecArray {
     groups: T;
 }
-/** Regular expression that contains the specified named capture groups. */
+/**
+ * Regular expression that contains the specified named capture groups.
+ *
+ * @see https://dhoulb.github.io/shelving/util/regexp/NamedRegExp
+ */
 export interface NamedRegExp<T extends NamedRegExpData = NamedRegExpData> extends RegExp {
     exec(input: string): NamedRegExpExecArray<T> | null;
 }
@@ -55,6 +157,9 @@ export interface NamedRegExp<T extends NamedRegExpData = NamedRegExpData> extend
  * - If `regexp` is a `RegExp` it is tested against the string using `RegExp.test()`.
  * - If `regexp` is a `string` it is simply tested against the string using `===` equality.
  * @returns `true` if the string matches the regular expression, otherwise `false`.
+ * @example
+ * isMatch("abc", /b/); // true
+ * @see https://dhoulb.github.io/shelving/util/regexp/isMatch
  */
 export declare function isMatch(str: string, regexp: Matchable): boolean;
 /**
@@ -65,34 +170,106 @@ export declare function isMatch(str: string, regexp: Matchable): boolean;
  * @param regexp Regular expression to test against the string.
  * - If `regexp` is a `RegExp` it is tested against the string using `RegExp.test()`.
  * - If `regexp` is a `string` it is simply tested against the string using `!==` equality.
- * @returns `true` if the string matches the regular expression, otherwise `false`.
+ * @returns `true` if the string does not match the regular expression, otherwise `false`.
+ * @example
+ * notMatch("abc", /z/); // true
+ * @see https://dhoulb.github.io/shelving/util/regexp/notMatch
  */
 export declare function notMatch(str: string, regexp: Matchable): boolean;
 /**
  * All of the provided regular expressions match the string.
  *
+ * @param str String to test against the regular expressions.
  * @param regexps - Regular expressions to match against the string.
  * - If empty the function returns `true` (since all zero of the provided regexps match everything).
  * - If a `RegExp` it is tested against the string using `RegExp.test()`.
  * - If a `string` it is simply tested against the string using `===` equality.
  * - If `null` or `undefined` it is ignored.
+ * @returns `true` if every provided regular expression matches the string, otherwise `false`.
+ * @example
+ * allMatch("abc", /a/, /b/); // true
+ * @see https://dhoulb.github.io/shelving/util/regexp/allMatch
  */
 export declare function allMatch(str: string, ...regexps: Matchables): boolean;
-/** At least one of the provided regular expressions matches the string. */
+/**
+ * At least one of the provided regular expressions matches the string.
+ *
+ * @param str String to test against the regular expressions.
+ * @param regexps - Regular expressions to match against the string.
+ * - If empty the function returns `false` (since none of zero provided regexps can match).
+ * - If a `RegExp` it is tested against the string using `RegExp.test()`.
+ * - If a `string` it is simply tested against the string using `===` equality.
+ * - If `null` or `undefined` it is ignored.
+ * @returns `true` if at least one provided regular expression matches the string, otherwise `false`.
+ * @example
+ * anyMatch("abc", /z/, /b/); // true
+ * @see https://dhoulb.github.io/shelving/util/regexp/anyMatch
+ */
 export declare function anyMatch(str: string, ...regexps: Matchables): boolean;
-/** None of the provided regular expressions match the string. */
+/**
+ * None of the provided regular expressions match the string.
+ *
+ * @param str String to test against the regular expressions.
+ * @param regexps - Regular expressions to match against the string.
+ * - If empty the function returns `false` (since the empty list of regexps matches everything).
+ * - If a `RegExp` it is tested against the string using `RegExp.test()`.
+ * - If a `string` it is simply tested against the string using `===` equality.
+ * - If `null` or `undefined` it is ignored.
+ * @returns `true` if none of the provided regular expressions match the string, otherwise `false`.
+ * @example
+ * noneMatch("abc", /x/, /y/); // true
+ * @see https://dhoulb.github.io/shelving/util/regexp/noneMatch
+ */
 export declare function noneMatch(str: string, ...regexps: Matchables): boolean;
-/** Get an optional regular expression match, or `undefined` if no match could be made. */
+/**
+ * Get an optional regular expression match, or `undefined` if no match could be made.
+ *
+ * @param str String to match against the regular expression.
+ * @param regexp Regular expression to match against the string.
+ * @returns The match array, or `undefined` if the string did not match.
+ * @example
+ * getMatch("abc", /b/); // ["b"]
+ * @see https://dhoulb.github.io/shelving/util/regexp/getMatch
+ */
 export declare function getMatch<T extends NamedRegExpData>(str: string, regexp: NamedRegExp<T>): NamedRegExpExecArray<T> | undefined;
 export declare function getMatch<T extends string>(str: string, regexp: TypedRegExp<T>): TypedRegExpExecArray<T> | undefined;
 export declare function getMatch(str: string, regexp: RegExp): RegExpExecArray | undefined;
-/** Get a required regular expression match, or throw `ValueError` if no match could be made. */
+/**
+ * Get a required regular expression match, or throw `ValueError` if no match could be made.
+ *
+ * @param str String to match against the regular expression.
+ * @param regexp Regular expression to match against the string.
+ * @returns The match array.
+ * @throws {ValueError} If the string did not match the regular expression.
+ * @example
+ * requireMatch("abc", /b/); // ["b"]
+ * @see https://dhoulb.github.io/shelving/util/regexp/requireMatch
+ */
 export declare function requireMatch<T extends NamedRegExpData>(str: string, regexp: NamedRegExp<T>): NamedRegExpExecArray<T>;
 export declare function requireMatch<T extends string>(str: string, regexp: TypedRegExp<T>): TypedRegExpExecArray<T>;
 export declare function requireMatch(str: string, regexp: RegExp): RegExpExecArray;
-/** Get an optional regular expression match, or `undefined` if no match could be made. */
+/**
+ * Get the named groups of an optional regular expression match, or `undefined` if no match could be made.
+ *
+ * @param str String to match against the regular expression.
+ * @param regexp Regular expression to match against the string.
+ * @returns The set of named match groups, or `undefined` if the string did not match.
+ * @example
+ * getMatchGroups("abc", /(?<first>a)/); // { first: "a" }
+ * @see https://dhoulb.github.io/shelving/util/regexp/getMatchGroups
+ */
 export declare function getMatchGroups<T extends NamedRegExpData>(str: string, regexp: NamedRegExp<T>): T | undefined;
 export declare function getMatchGroups(str: string, regexp: RegExp): NamedRegExpData | undefined;
-/** Get a required regular expression match, or throw `ValueError` if no match could be made. */
+/**
+ * Get the named groups of a required regular expression match, or throw `ValueError` if no match could be made.
+ *
+ * @param str String to match against the regular expression.
+ * @param regexp Regular expression to match against the string.
+ * @returns The set of named match groups.
+ * @throws {ValueError} If the string did not match the regular expression.
+ * @example
+ * requireMatchGroups("abc", /(?<first>a)/); // { first: "a" }
+ * @see https://dhoulb.github.io/shelving/util/regexp/requireMatchGroups
+ */
 export declare function requireMatchGroups<T extends NamedRegExpData>(str: string, regexp: NamedRegExp<T>): T;
 export declare function requireMatchGroups(str: string, regexp: RegExp): NamedRegExpData;

package/util/regexp.js

@@ -2,15 +2,35 @@ import { RequiredError } from "../error/RequiredError.js";
 import { ValueError } from "../error/ValueError.js";
 import { requireArray } from "./array.js";
 import { isNullish } from "./null.js";
-/** Regular expression that always matches everything. */
+/**
+ * Regular expression that always matches everything.
+ *
+ * @see https://dhoulb.github.io/shelving/util/regexp/ALWAYS_REGEXP
+ */
 export const ALWAYS_REGEXP = /^.*$/;
-/** Regular expression that never matches anything. */
+/**
+ * Regular expression that never matches anything.
+ *
+ * @see https://dhoulb.github.io/shelving/util/regexp/NEVER_REGEXP
+ */
 export const NEVER_REGEXP = /^(?=a)a/;
-/** Is an unknown value a `RegExp` instance? */
+/**
+ * Is an unknown value a `RegExp` instance?
+ *
+ * @param value The value to test.
+ * @returns `true` if `value` is a `RegExp` instance, narrowing its type.
+ * @see https://dhoulb.github.io/shelving/util/regexp/isRegExp
+ */
 export function isRegExp(value) {
     return value instanceof RegExp;
 }
-/** Assert that an unknown value is a `RegExp` instance. */
+/**
+ * Assert that an unknown value is a `RegExp` instance.
+ *
+ * @param value The value to assert.
+ * @throws {RequiredError} If `value` is not a `RegExp` instance.
+ * @see https://dhoulb.github.io/shelving/util/regexp/assertRegExp
+ */
 export function assertRegExp(value) {
     if (!(value instanceof RegExp))
         throw new RequiredError("Must be regular expression", { received: value, caller: assertRegExp });
@@ -18,16 +38,44 @@ export function assertRegExp(value) {
 export function getRegExp(pattern, flags) {
     return typeof pattern === "string" ? new RegExp(pattern, flags) : pattern;
 }
-/** Convert a regular expression to its string source. */
+/**
+ * Convert a regular expression to its string source.
+ * - If `regexp` is a `string` it is returned as-is, otherwise its `.source` is returned.
+ *
+ * @param regexp The regular expression or string source to read.
+ * @returns The string source of the regular expression.
+ * @example
+ * getRegExpSource(/abc/); // "abc"
+ * @see https://dhoulb.github.io/shelving/util/regexp/getRegExpSource
+ */
 export function getRegExpSource(regexp) {
     return typeof regexp === "string" ? regexp : regexp.source;
 }
-/** Escape special characters in a string regular expression. */
+/**
+ * Escape special characters in a string regular expression.
+ * - Escapes any characters that have special meaning in a regular expression so the string matches literally.
+ *
+ * @param pattern The string to escape.
+ * @returns The escaped string, safe to use as a literal regular expression source.
+ * @example
+ * escapeRegExp("a.b"); // "a\\.b"
+ * @see https://dhoulb.github.io/shelving/util/regexp/escapeRegExp
+ */
 export function escapeRegExp(pattern) {
     return pattern.replace(REPLACE_ESCAPED, "\\$&");
 }
 const REPLACE_ESCAPED = /[-[\]/{}()*+?.\\^$|]/g;
-/** Create regular expression that matches any of a list of other expressions. */
+/**
+ * Create a regular expression that matches any one of a list of other expressions.
+ * - If the list is empty the returned expression matches nothing (`NEVER_REGEXP`).
+ *
+ * @param patterns The regular expressions or string sources to combine.
+ * @param flags The flags to use when creating the combined `RegExp`.
+ * @returns A `RegExp` that matches if any of the provided expressions match.
+ * @example
+ * createRegExpAny(["abc", "def"]); // /(?:abc)|(?:def)/
+ * @see https://dhoulb.github.io/shelving/util/regexp/createRegExpAny
+ */
 export function createRegExpAny(patterns, flags) {
     const arr = requireArray(patterns).filter(Boolean);
     // If there are no patterns to match against then _no_ string can ever match against any of nothing.
@@ -36,7 +84,17 @@ export function createRegExpAny(patterns, flags) {
     // Create RegExp using multiple joined matches like `(?:AAA)|(?:BBB)`
     return new RegExp(`(?:${requireArray(patterns).map(getRegExpSource).join(")|(?:")})`, flags);
 }
-/** Create regular expression that matches all of a list of other expressions. */
+/**
+ * Create a regular expression that matches all of a list of other expressions.
+ * - If the list is empty the returned expression matches everything (`ALWAYS_REGEXP`).
+ *
+ * @param patterns The regular expressions or string sources to combine.
+ * @param flags The flags to use when creating the combined `RegExp`.
+ * @returns A `RegExp` that matches only if all of the provided expressions match.
+ * @example
+ * createRegExpAll(["abc", "def"]); // /^(?=.*?(?:abc))(?=.*?(?:def))/
+ * @see https://dhoulb.github.io/shelving/util/regexp/createRegExpAll
+ */
 export function createRegExpAll(patterns, flags) {
     const arr = requireArray(patterns).filter(Boolean);
     // If there are no patterns to match against then _every_ string will match against the entire list of nothing.
@@ -54,6 +112,9 @@ export function createRegExpAll(patterns, flags) {
  * - If `regexp` is a `RegExp` it is tested against the string using `RegExp.test()`.
  * - If `regexp` is a `string` it is simply tested against the string using `===` equality.
  * @returns `true` if the string matches the regular expression, otherwise `false`.
+ * @example
+ * isMatch("abc", /b/); // true
+ * @see https://dhoulb.github.io/shelving/util/regexp/isMatch
  */
 export function isMatch(str, regexp) {
     return typeof regexp === "string" ? regexp === str : regexp.test(str);
@@ -66,7 +127,10 @@ export function isMatch(str, regexp) {
  * @param regexp Regular expression to test against the string.
  * - If `regexp` is a `RegExp` it is tested against the string using `RegExp.test()`.
  * - If `regexp` is a `string` it is simply tested against the string using `!==` equality.
- * @returns `true` if the string matches the regular expression, otherwise `false`.
+ * @returns `true` if the string does not match the regular expression, otherwise `false`.
+ * @example
+ * notMatch("abc", /z/); // true
+ * @see https://dhoulb.github.io/shelving/util/regexp/notMatch
  */
 export function notMatch(str, regexp) {
     return !isMatch(str, regexp);
@@ -74,11 +138,16 @@ export function notMatch(str, regexp) {
 /**
  * All of the provided regular expressions match the string.
  *
+ * @param str String to test against the regular expressions.
  * @param regexps - Regular expressions to match against the string.
  * - If empty the function returns `true` (since all zero of the provided regexps match everything).
  * - If a `RegExp` it is tested against the string using `RegExp.test()`.
  * - If a `string` it is simply tested against the string using `===` equality.
  * - If `null` or `undefined` it is ignored.
+ * @returns `true` if every provided regular expression matches the string, otherwise `false`.
+ * @example
+ * allMatch("abc", /a/, /b/); // true
+ * @see https://dhoulb.github.io/shelving/util/regexp/allMatch
  */
 export function allMatch(str, ...regexps) {
     for (const x of regexps) {
@@ -89,7 +158,20 @@ export function allMatch(str, ...regexps) {
     }
     return true;
 }
-/** At least one of the provided regular expressions matches the string. */
+/**
+ * At least one of the provided regular expressions matches the string.
+ *
+ * @param str String to test against the regular expressions.
+ * @param regexps - Regular expressions to match against the string.
+ * - If empty the function returns `false` (since none of zero provided regexps can match).
+ * - If a `RegExp` it is tested against the string using `RegExp.test()`.
+ * - If a `string` it is simply tested against the string using `===` equality.
+ * - If `null` or `undefined` it is ignored.
+ * @returns `true` if at least one provided regular expression matches the string, otherwise `false`.
+ * @example
+ * anyMatch("abc", /z/, /b/); // true
+ * @see https://dhoulb.github.io/shelving/util/regexp/anyMatch
+ */
 export function anyMatch(str, ...regexps) {
     for (const x of regexps) {
         if (isNullish(x))
@@ -99,7 +181,20 @@ export function anyMatch(str, ...regexps) {
     }
     return false;
 }
-/** None of the provided regular expressions match the string. */
+/**
+ * None of the provided regular expressions match the string.
+ *
+ * @param str String to test against the regular expressions.
+ * @param regexps - Regular expressions to match against the string.
+ * - If empty the function returns `false` (since the empty list of regexps matches everything).
+ * - If a `RegExp` it is tested against the string using `RegExp.test()`.
+ * - If a `string` it is simply tested against the string using `===` equality.
+ * - If `null` or `undefined` it is ignored.
+ * @returns `true` if none of the provided regular expressions match the string, otherwise `false`.
+ * @example
+ * noneMatch("abc", /x/, /y/); // true
+ * @see https://dhoulb.github.io/shelving/util/regexp/noneMatch
+ */
 export function noneMatch(str, ...regexps) {
     return !allMatch(str, ...regexps);
 }