@budsbox/lib-es 2.3.0 → 3.0.0

package/dist/guards/check.js

@@ -0,0 +1,524 @@
+/**
+ * @module
+ * This module provides type guards for various JavaScript types.
+ * @categoryDescription Checks
+ * Type guards for JavaScript primitives and common types.
+ */
+import { describePredicate, describeTypePredicate } from './describe.js';
+/* ─────────────────────────────── Nullables ──────────────────────────────── */
+/**
+ * Checks if the provided value is `undefined`.
+ *
+ * @param value - The value to check for `undefined`.
+ * @returns `true` if the value is `undefined`, otherwise `false`.
+ * @example
+ * ```typescript
+ * isUndef(undefined); // true
+ * isUndef(null); // false
+ * isUndef(0); // false
+ * ```
+ * @category Checks
+ */
+export function isUndef(value) {
+    return value === undefined;
+}
+describeTypePredicate(isUndef, 'undefined');
+/**
+ * Checks if a given value is defined (not `undefined`).
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is defined, otherwise `false`.
+ * @example
+ * ```typescript
+ * isDef(undefined); // false
+ * isDef(null); // true
+ * isDef(42); // true
+ * ```
+ * @category Checks
+ */
+export function isDef(value) {
+    return value !== undefined;
+}
+describeTypePredicate(isDef, 'not undefined');
+/**
+ * Checks if the provided value is `null` or `undefined`.
+ *
+ * @param value - The value to be checked.
+ * @returns `true` if the value is `null` or `undefined`, otherwise `false`.
+ * @example
+ * ```typescript
+ * isNil(null); // true
+ * isNil(undefined); // true
+ * isNil(false); // false
+ * isNil(''); // false
+ * ```
+ * @category Checks
+ */
+export function isNil(value) {
+    return value == null;
+}
+describeTypePredicate(isNil, 'null or undefined');
+/**
+ * {@label OVERLOAD_UNKNOWN}
+ *
+ * Checks if the provided value is not `null` or `undefined`.
+ *
+ * @param value - The value to be checked.
+ * @returns `true` if the value is not `null` or `undefined`; otherwise, `false`.
+ * @example
+ * ```typescript
+ * isNotNil(null); // false
+ * isNotNil(undefined); // false
+ * isNotNil(0); // true
+ * isNotNil(''); // true
+ * ```
+ * @category Checks
+ */
+export function isNotNil(value) {
+    return !isNil(value);
+}
+describeTypePredicate(isNotNil, 'non-nullable');
+/* ──────────────────────────────── Boolean ───────────────────────────────── */
+/**
+ * Checks if the given value is of type ``boolean``.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a `boolean`, otherwise `false`.
+ * @example
+ * ```typescript
+ * isBoolean(true); // true
+ * isBoolean(false); // true
+ * isBoolean(1); // false
+ * isBoolean('true'); // false
+ * ```
+ * @category Checks
+ */
+export function isBoolean(value) {
+    return typeof value === 'boolean';
+}
+describeTypePredicate(isBoolean, 'boolean');
+/**
+ * Checks if the provided value is strictly equal to `true`.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is strictly `true`, otherwise `false`.
+ * @example
+ * ```typescript
+ * isTrue(true); // true
+ * isTrue(1); // false
+ * isTrue('true'); // false
+ * isTrue(false); // false
+ * ```
+ * @category Checks
+ */
+export function isTrue(value) {
+    return value === true;
+}
+describeTypePredicate(isTrue, 'true');
+/**
+ * Determines if the provided value is strictly `false`.
+ *
+ * @param value - The value to be checked.
+ * @returns `true` if the value is `false`, otherwise `false`.
+ * @example
+ * ```typescript
+ * isFalse(false); // true
+ * isFalse(0); // false
+ * isFalse(''); // false
+ * isFalse(true); // false
+ * ```
+ * @category Checks
+ */
+export function isFalse(value) {
+    return value === false;
+}
+describeTypePredicate(isFalse, 'false');
+/**
+ * Determines if the given value is truthy, i.e., converts to `true` when used in a `boolean` context.
+ *
+ * @param value - The value to be tested for truthiness.
+ * @returns `true` if the value is truthy, `false` otherwise.
+ * @example
+ * ```typescript
+ * isTruly(true); // true
+ * isTruly(1); // true
+ * isTruly('hello'); // true
+ * isTruly(0); // false
+ * isTruly(''); // false
+ * isTruly(null); // false
+ * ```
+ * @category Checks
+ */
+export function isTruly(value) {
+    return Boolean(value);
+}
+describePredicate(isTruly, 'to evaluates to true when coerced to a boolean');
+/**
+ * Determines if a given value is falsy.
+ * A value is considered falsy if it evaluates to `false` when coerced to a `boolean`.
+ *
+ * @param value - The value to be tested.
+ * @returns `true` if the value is falsy, otherwise `false`.
+ * @example
+ * ```typescript
+ * isFalsy(false); // true
+ * isFalsy(0); // true
+ * isFalsy(''); // true
+ * isFalsy(null); // true
+ * isFalsy(undefined); // true
+ * isFalsy('hello'); // false
+ * ```
+ * @category Checks
+ */
+export function isFalsy(value) {
+    return !isTruly(value);
+}
+describePredicate(isFalsy, 'to evaluates to false when coerced to a boolean');
+/* ──────────────────────────────── Numeric ───────────────────────────────── */
+/**
+ * Checks if the provided value is a `number` and not {@link NaN}.
+ *
+ * @param value - The value to be checked.
+ * @returns `true` if the value is a `number` and not {@link NaN}, otherwise `false`.
+ * @example
+ * ```typescript
+ * isNumber(42); // true
+ * isNumber(3.14); // true
+ * isNumber(NaN); // false
+ * isNumber('42'); // false
+ * isNumber(null); // false
+ * ```
+ * @category Checks
+ */
+export function isNumber(value) {
+    return typeof value === 'number' && !Number.isNaN(value);
+}
+describeTypePredicate(isNumber, 'number');
+/**
+ * Checks if a given value is of type `bigint`.
+ *
+ * @param value - The value to be checked.
+ * @returns `true` if the value is a `bigint`, otherwise `false`.
+ * @example
+ * ```typescript
+ * isBigint(42n); // true
+ * isBigint(42); // false
+ * isBigint('42'); // false
+ * isBigint(BigInt(42)); // true
+ * ```
+ * @category Checks
+ */
+export function isBigint(value) {
+    return typeof value === 'bigint';
+}
+describeTypePredicate(isBigint, 'bigint');
+/**
+ * Determines whether a given number is positive.
+ *
+ * @param num - The `number` or `bigint` to check.
+ * @returns `true` if the input is greater than zero, otherwise `false`.
+ * @example
+ * ```typescript
+ * isPositive(42); // true
+ * isPositive(0); // false
+ * isPositive(-5); // false
+ * isPositive(100n); // true
+ * ```
+ * @category Checks
+ */
+export function isPositive(num) {
+    return isBigint(num) ? num > 0n : num > 0;
+}
+describePredicate(isPositive, 'to be greater than zero');
+/**
+ * Determines whether a given number is non-negative.
+ *
+ * @param num - The number to check. It can be a `bigint` or a `number`.
+ * @returns `true` if the provided number is greater than or equal to zero, otherwise `false`.
+ * @example
+ * ```typescript
+ * isNonNegative(42); // true
+ * isNonNegative(0); // true
+ * isNonNegative(-1); // false
+ * isNonNegative(0n); // true
+ * ```
+ * @category Checks
+ */
+export function isNonNegative(num) {
+    return isBigint(num) ? num >= 0n : num >= 0;
+}
+describePredicate(isNonNegative, 'to be greater than or equal to zero');
+/**
+ * Checks if the provided value is an integer.
+ *
+ * @param value - The value to check, which can be a `bigint` or `number`.
+ * @returns `true` if the value is an integer, otherwise `false`.
+ * @example
+ * ```typescript
+ * isInteger(42); // true
+ * isInteger(3.14); // false
+ * isInteger(42n); // true
+ * ```
+ * @category Checks
+ */
+export function isInteger(value) {
+    return isBigint(value) || Number.isInteger(value);
+}
+describeTypePredicate(isInteger, 'integer');
+/* ────────────────────────────────── Misc ────────────────────────────────── */
+/**
+ * Determines if the provided value is a `string`.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a `string`, otherwise `false`.
+ * @example
+ * ```typescript
+ * isString('hello'); // true
+ * isString(42); // false
+ * ```
+ * @category Checks
+ */
+export function isString(value) {
+    return typeof value === 'string';
+}
+describeTypePredicate(isString, 'string');
+/**
+ * Checks if the provided value is of type ``symbol``.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a `symbol`, otherwise `false`.
+ * @example
+ * ```typescript
+ * isSymbol(Symbol('foo')); // true
+ * isSymbol('foo'); // false
+ * ```
+ * @category Checks
+ */
+export const isSymbol = (value) => typeof value === 'symbol';
+describeTypePredicate(isSymbol, 'symbol');
+/**
+ * Determines whether the given value is a valid JavaScript property key.
+ *
+ * A property key in JavaScript can be a `string`, `symbol`, or `number`, as these are
+ * the types allowed for indexing object properties.
+ *
+ * @param value - The value to be checked as a potential property key.
+ * @returns `true` if the value is a valid property key, otherwise `false`.
+ * @example
+ * ```typescript
+ * isPropKey('foo'); // true
+ * isPropKey(123); // true
+ * isPropKey(Symbol('bar')); // true
+ * isPropKey({}); // false
+ * ```
+ * @category Checks
+ */
+export const isPropKey = (value) => isString(value) || isSymbol(value) || isNumber(value);
+describeTypePredicate(isPropKey, 'valid property key (string, symbol, or number)');
+/**
+ * Checks if a given value is a {@link Primitive} type (`null`, `undefined`, `boolean`, `string`, `number`, `symbol`, or `bigint`).
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a {@link Primitive} type, otherwise `false`.
+ * @example
+ * ```typescript
+ * isPrimitive(42); // true
+ * isPrimitive('foo'); // true
+ * isPrimitive(null); // true
+ * isPrimitive({}); // false
+ * ```
+ * @category Checks
+ */
+export const isPrimitive = (value) => isNil(value) ||
+    isBoolean(value) ||
+    isString(value) ||
+    isNumber(value) ||
+    Number.isNaN(value) ||
+    isSymbol(value) ||
+    isBigint(value);
+describeTypePredicate(isPrimitive, 'a primitive (null, undefined, boolean, string, number, symbol, or bigint)');
+/* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ OBJECT-LIKE ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */
+/**
+ * Checks if the given value is an {@link object}.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is an {@link object}, `false` otherwise.
+ * @example
+ * ```typescript
+ * isObject({}); // true
+ * isObject([]); // true
+ * isObject(null); // false
+ * ```
+ * @category Checks
+ */
+export function isObject(value) {
+    return value !== null && typeof value === 'object';
+}
+describeTypePredicate(isObject, 'object');
+/**
+ * Checks if the given value is an {@link Array}.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is an {@link Array}, otherwise `false`.
+ * @typeParam T - Type of the value to be checked.
+ * @example
+ * ```typescript
+ * isArray([1, 2, 3]); // true
+ * isArray('foo'); // false
+ * ```
+ * @category Checks
+ */
+export function isArray(value) {
+    return Array.isArray(value);
+}
+describeTypePredicate(isArray, 'array');
+/**
+ * {@label OVERLOAD_BOOLEAN}
+ *
+ * Determines if the provided value is a function.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a function, otherwise `false`.
+ * @category Checks
+ */
+export function isFunction(value) {
+    return typeof value === 'function';
+}
+describeTypePredicate(isFunction, 'function');
+/**
+ * Checks if the given value is a {@link Date} instance.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a {@link Date} instance, otherwise `false`.
+ * @example
+ * ```typescript
+ * isDate(new Date()); // true
+ * isDate('2023-01-01'); // false
+ * ```
+ * @category Checks
+ */
+export function isDate(value) {
+    return value instanceof Date;
+}
+describeTypePredicate(isDate, 'Date');
+/**
+ * Checks if the given value is a {@link RegExp} instance.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a {@link RegExp} instance, otherwise `false`.
+ * @example
+ * ```typescript
+ * isRegExp(/foo/); // true
+ * isRegExp('foo'); // false
+ * ```
+ * @category Checks
+ */
+export function isRegExp(value) {
+    return value instanceof RegExp;
+}
+describeTypePredicate(isRegExp, 'RegExp');
+/**
+ * Checks if the given value is an {@link Error} instance.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is an {@link Error} instance, otherwise `false`.
+ * @example
+ * ```typescript
+ * isError(new Error('foo')); // true
+ * isError({ message: 'foo' }); // false
+ * ```
+ * @category Checks
+ */
+export function isError(value) {
+    return value instanceof Error;
+}
+describeTypePredicate(isError, 'Error');
+/**
+ * Checks if the given value is a {@link Map} instance.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a {@link Map} instance, otherwise `false`.
+ * @example
+ * ```typescript
+ * isMap(new Map()); // true
+ * isMap({}); // false
+ * ```
+ * @category Checks
+ */
+export function isMap(value) {
+    return value instanceof Map;
+}
+describeTypePredicate(isMap, 'Map');
+/**
+ * Checks if the given value is a {@link Set} instance.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a {@link Set} instance, otherwise `false`.
+ * @example
+ * ```typescript
+ * isSet(new Set()); // true
+ * isSet([]); // false
+ * ```
+ * @category Checks
+ */
+export function isSet(value) {
+    return value instanceof Set;
+}
+describeTypePredicate(isSet, 'Set');
+/**
+ * Checks if the given value is a {@link WeakMap} or {@link Map} instance.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a {@link WeakMap} or {@link Map} instance, otherwise `false`.
+ * @example
+ * ```typescript
+ * isWeakMapLike(new WeakMap()); // true
+ * isWeakMapLike(new Map()); // true
+ * isWeakMapLike({}); // false
+ * ```
+ * @category Checks
+ */
+export function isWeakMapLike(value) {
+    return value instanceof WeakMap || isMap(value);
+}
+describeTypePredicate(isWeakMapLike, 'WeakMap or Map');
+/**
+ * Checks if the given value is a {@link WeakSet} or {@link Set} instance.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a {@link WeakSet} or {@link Set} instance, otherwise `false`.
+ * @example
+ * ```typescript
+ * isWeakSetLike(new WeakSet()); // true
+ * isWeakSetLike(new Set()); // true
+ * isWeakSetLike([]); // false
+ * ```
+ * @category Checks
+ */
+export function isWeakSetLike(value) {
+    return value instanceof WeakSet || value instanceof Set;
+}
+describeTypePredicate(isWeakSetLike, 'WeakSet or Set');
+/* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ABSTRACT ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */
+/**
+ * Determines whether two values are the same value using the
+ * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Equality_comparisons_and_sameness#same-value-zero_equality "SameValueZero" comparison algorithm}.
+ *
+ * @param x - The first value to be compared.
+ * @param y - The second value to be compared.
+ * @returns `true` if `x` and `y` are the same value according to the "SameValueZero" comparison, otherwise `false`.
+ * @remarks
+ * - It differs from strict equality (`===`) in that {@link NaN} is considered equal to itself.
+ * - It differs from {@link Object.is} in that it considers `-0` and `+0` equal.
+ * - It's the same algorithm used by {@link Set} and {@link Map} to compare elements.
+ * @typeParam TValue - The type of the first value being compared.
+ * @example
+ * ```typescript
+ * sameValueZero(0, -0); // true
+ * sameValueZero(NaN, NaN); // true
+ * sameValueZero(1, '1'); // false
+ * ```
+ * @category Checks
+ */
+export const sameValueZero = (x, y) => Object.is(x, y) || (x === 0 && y === 0);
+//# sourceMappingURL=check.js.map

package/dist/guards/describe.d.ts

@@ -0,0 +1,7 @@
+import type { Predicate } from '@budsbox/lib-types';
+import type { PredicateDescriptor } from './types.js';
+export declare const describeTypePredicate: <TPredicate extends Predicate>(predicate: TPredicate, typeDescription: string) => TPredicate;
+export declare const describePredicate: <TPredicate extends Predicate>(predicate: TPredicate, conditionOrDescriptor: string | Readonly<PredicateDescriptor>) => TPredicate;
+export declare const describeComplexPredicate: <TPredicate extends Predicate>(predicate: TPredicate, and: boolean, ...subPredicates: readonly Predicate[]) => TPredicate;
+export declare const getPredicateDescriptor: (predicate: Predicate) => PredicateDescriptor | undefined;
+//# sourceMappingURL=describe.d.ts.map

package/dist/guards/describe.js

@@ -0,0 +1,34 @@
+const descriptionSymbol = Symbol.for('@budsbox/lib-es/guards#predicateDescription');
+// eslint-disable-next-line jsdoc/require-jsdoc
+export const describeTypePredicate = (predicate, typeDescription) => {
+    describePredicate(predicate, { type: typeDescription });
+    return predicate;
+};
+// eslint-disable-next-line jsdoc/require-jsdoc
+export const describePredicate = (predicate, conditionOrDescriptor) => {
+    Object.defineProperty(predicate, descriptionSymbol, {
+        configurable: true,
+        value: typeof conditionOrDescriptor === 'string' ?
+            {
+                condition: conditionOrDescriptor,
+            }
+            : conditionOrDescriptor,
+    });
+    return predicate;
+};
+// eslint-disable-next-line jsdoc/require-jsdoc
+export const describeComplexPredicate = (predicate, and, ...subPredicates) => {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    const value = {
+        [and ? 'and' : 'or']: subPredicates,
+    };
+    describePredicate(predicate, value);
+    return predicate;
+};
+// eslint-disable-next-line jsdoc/require-jsdoc
+export const getPredicateDescriptor = (predicate) => {
+    if (Object.hasOwn(predicate, descriptionSymbol))
+        return predicate[descriptionSymbol];
+    return;
+};
+//# sourceMappingURL=describe.js.map

package/dist/guards/format.d.ts

@@ -0,0 +1,109 @@
+/**
+ * This module provides utilities for formatting error messages and values related to predicate checks.
+ *
+ * @module
+ * @categoryDescription Formatting
+ * Utilities for formatting error messages and values related to predicate checks.
+ */
+import type { Predicate } from '@budsbox/lib-types';
+import type { FormatDebugValueFn, FormatErrorFn, FormatPredicateExpectedMessageFn } from './types.js';
+/**
+ * {@link FormatPredicateExpectedMessageFn} implementation.
+ *
+ * @inheritDoc {@link FormatPredicateExpectedMessageFn}
+ * @ignore
+ */
+export declare const formatPredicateExpectedMessage: FormatPredicateExpectedMessageFn;
+/**
+ * Generates a description of the conditions associated with a given predicate.
+ * The description includes whether the predicate is a type guard, a value check, or both.
+ *
+ * @internal
+ * @param predicate - The predicate whose conditions are to be analyzed and described.
+ * @param nested - A flag indicating if the predicate is part of a nested structure. Defaults to `false`.
+ * @returns An object comprising:
+ * - `condition`: A string describing the predicate's conditions.
+ * - `isType`: A boolean indicating whether the predicate is a type guard.
+ * - `isValue`: A boolean indicating whether the predicate checks a value.
+ * @typeParam Predicate - The expected type of the predicate parameter.
+ * @category Formatting
+ */
+export declare const getPredicateConditions: (predicate: Predicate, nested?: boolean) => {
+    condition: string;
+    isType: boolean;
+    isValue: boolean;
+};
+/**
+ * Provides a human-readable description of a value's type.
+ *
+ * - If the value is `null`, `undefined`, or a `Symbol`, it will return the string representation.
+ * - If the value is a primitive type (e.g., `number`, `string`, `boolean`), it will return the result of `typeof value`.
+ * - If the value is a function, it will return `'function'`.
+ * - If the value is an array, it will return `'array'`.
+ * - For objects, it will return the `Symbol.toStringTag` or the internal `[[Class]]` property of the object.
+ *
+ * @param value - The value whose type needs to be determined.
+ * @returns A string representation of the value's type.
+ * @category Formatting
+ */
+export declare const formatDebugType: (value: unknown) => string;
+/**
+ * {@link FormatDebugValueFn} implementation.
+ *
+ * @inheritDoc {@link FormatDebugValueFn}
+ * @category Formatting
+ */
+export declare const formatDebugValue: FormatDebugValueFn;
+/**
+ * {@link FormatErrorFn} implementation.
+ *
+ * @inheritDoc {@link FormatErrorFn}
+ * @category Formatting
+ */
+export declare const formatError: FormatErrorFn;
+/**
+ * Constructs a dot-notation or bracket-notation string representation
+ * for accessing nested properties of an object based on the provided keys.
+ *
+ * @internal
+ * @param sourceName - The base name of the object or source from which properties are being accessed.
+ * @param keys - A variadic list of property keys representing the nested path.
+ *               Each key will be used to generate the accessor string.
+ * @returns A string representing the accessor path in dot-notation for valid identifiers
+ *          or bracket-notation for non-identifier keys.
+ * @remarks The function is intended to be used for generating error messages.
+ */
+export declare const formatAccessString: (sourceName: string, ...keys: readonly PropertyKey[]) => string;
+/**
+ * Extracts and returns the `Symbol.toStringTag` or internal `[[Class]]` property of a given object as a string.
+ *
+ * The method utilizes `Object.prototype.toString` to determine the object type
+ * and removes the surrounding `[object ...]` syntax to provide the type name.
+ *
+ * @param value - The input value from which the object tag will be extracted.
+ * @returns The name of the internal `[[Class]]` corresponding to the input value.
+ * @category Formatting
+ */
+export declare const shortObjectTag: (value: unknown) => string;
+/**
+ * Returns a descriptive tag string for a given value based on its constructor
+ * and `Symbol.toStringTag`.
+ *
+ * For objects, combine the constructor name with the `Symbol.toStringTag` if they differ
+ * (e.g., `"Map"` or `"CustomClass[Tag]"`). For non-objects, falls back to {@link shortObjectTag}.
+ *
+ * @param value - The value to extract the tag from.
+ * @returns A string describing the object's type and tag.
+ * @category Formatting
+ */
+export declare const objectTag: (value: unknown) => string;
+/**
+ * Joins an array of strings into a single formatted string using the specified conjunction.
+ *
+ * @param items - An array of strings to be joined. If the array is empty, an empty string is returned.
+ * @param conjunction - A word or phrase to be used as the conjunction between the last two items.
+ * @returns A formatted string where the items are separated by commas and the conjunction is added before the final item.
+ * @category Formatting
+ */
+export declare const joinWithConjunction: (items: readonly string[], conjunction: string) => string;
+//# sourceMappingURL=format.d.ts.map