@budsbox/lib-es 2.3.0 → 3.0.0

package/dist/guards/hlf.js

@@ -0,0 +1,178 @@
+/**
+ * Due to their reliance on features from several other submodules,
+ * these functions are not located in more fitting areas, such as './assert.ts' or './check.ts'.
+ *
+ * @module high-level-functions
+ */
+import { assertArray, assertFunction, assertString, callPredicate, invariantPredicate, } from './assert.js';
+import { isArray, isFunction, isString, sameValueZero } from './check.js';
+import { describeComplexPredicate, describePredicate, describeTypePredicate, getPredicateDescriptor, } from './describe.js';
+import { formatDebugValue, getPredicateConditions, joinWithConjunction, } from './format.js';
+import { assertProp, hasProp } from './prop.js';
+/**
+ * Determines whether the provided key is a valid property key of the given source object.
+ *
+ * @param key - The property key to check for existence within the source object.
+ * @param source - The object in which to check for the property key.
+ * @param checkProto - Determines whether the prototype chain should also be checked. Defaults to `false`.
+ * @returns A boolean indicating whether the key is a valid property key of the source object.
+ * @typeParam TSource - The type of the source object to inspect.
+ */
+export const isKeyOf = (key, source, checkProto = false) => {
+    return hasProp(source, key, checkProto);
+};
+/* ──────────────────────────────── Iterable ──────────────────────────────── */
+/**
+ * Determines whether the provided value is iterable.
+ *
+ * @param value - The value to be checked.
+ * @returns `true` if the value is iterable, otherwise `false`.
+ * @category Checks
+ */
+export function isIterable(value) {
+    return hasProp(value, Symbol.iterator, isFunction, true);
+}
+describePredicate(isIterable, 'to be iterable');
+/**
+ * Asserts that the provided value is iterable.
+ *
+ * @param value - The value to be checked for iterable compatibility.
+ * @param valueName - The name of the value for the error message. Defaults to 'value'.
+ * @throws {@link !TypeError} If the provided value is not iterable.
+ * @category Assertions
+ */
+export function assertIterable(value, valueName = 'value') {
+    // This assertion offers a more informative error message compared to the default one provided by assertProp.
+    assertString(valueName, 'valueName');
+    assertProp(value, Symbol.iterator, isFunction, true, valueName);
+}
+/* ──────────────────────────────── Of Type ───────────────────────────────── */
+/**
+ * Creates a type predicate that checks whether a value is an instance of the provided constructor.
+ * The returned predicate acts as a type guard for narrowing the value to the constructor's type.
+ *
+ * @param ctor - A constructor function to check against.
+ * @returns A type predicate function that narrows the value type to an instance of the constructor.
+ * @throws {@link !TypeError} If `ctor` is not a function.
+ * @typeParam T - The type of instances produced by the constructor.
+ * @category Checks
+ */
+export const ofType = (ctor) => {
+    assertFunction(ctor, 'ctor');
+    return describeTypePredicate((value) => value instanceof ctor, `instance of ${ctor.name ? ctor.name : 'anonymous class'}`);
+};
+/**
+ * Asserts that a value is an instance of the provided constructor.
+ * If the assertion succeeds, the value is narrowed to the constructor's type.
+ *
+ * @param ctor - A constructor function to check against.
+ * @param value - The value to be verified as an instance of the constructor.
+ * @param name - The name of the value for the error message. Defaults to 'value'.
+ * @throws {@link !TypeError} If `ctor` is not a function or if the value is not an instance of the constructor.
+ * @typeParam T - The type of instances produced by the constructor.
+ * @category Assertions
+ */
+export function assertOfType(ctor, value, name = 'value') {
+    assertFunction(ctor, 'ctor');
+    assertString(name, 'valueName');
+    invariantPredicate(ofType(ctor), value, name);
+}
+export function somePredicate(...predicates) {
+    assertPredicates(predicates);
+    const compositePredicate = (value) => predicates.some((predicate) => callPredicate(predicate, value));
+    return describeComplexPredicate(compositePredicate, false, ...predicates);
+}
+export function assertSome(value, ...rest) {
+    let valueName, predicates;
+    if (isString(rest[0])) {
+        [valueName, ...predicates] = rest;
+    }
+    else {
+        predicates = rest;
+    }
+    invariantPredicate(somePredicate(...predicates), value, valueName);
+}
+export function everyPredicate(...predicates) {
+    assertPredicates(predicates);
+    const compositePredicate = (value) => predicates.every((predicate) => callPredicate(predicate, value));
+    return describeComplexPredicate(compositePredicate, true, ...predicates);
+}
+export function assertEvery(value, ...rest) {
+    let valueName, predicates;
+    if (isString(rest[0])) {
+        [valueName, ...predicates] = rest;
+    }
+    else {
+        predicates = rest;
+    }
+    invariantPredicate(everyPredicate(...predicates), value, valueName);
+}
+/* ───────────────────────────────── Any Of ───────────────────────────────── */
+/**
+ * Creates a type predicate that checks if a given value matches any of the specified values.
+ *
+ * This function accepts a set of possible values and returns a predicate function
+ * that evaluates if an input value exists within the set of those specified values.
+ *
+ * @param values - The set of values to match the input against.
+ * @returns A type predicate that verifies whether a value is one of the specified values.
+ * @typeParam TValues - A tuple type of all possible values to check against.
+ * @remarks Value equality is based on the {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Equality_comparisons_and_sameness#same-value-zero_equality SameValueZero algorithm}.
+ * @example
+ * ```typescript
+ * const isColor = anyOf('red', 'green', 'blue');
+ * const test = 'red';
+ * if (isColor(test)) {
+ *   console.log("It\'s a color!");
+ * }
+ * ```
+ * @category Checks
+ */
+export const anyOf = (...values) => {
+    const testSet = new Set(values);
+    return describePredicate((value) => testSet.has(value), `to be any of: ${joinWithConjunction(values.map((v) => formatDebugValue(v, { maxDepth: 1 })), 'or')}`);
+};
+export function assertAnyOf(values, value, valueName = 'value') {
+    assertIterable(values, 'values');
+    assertString(valueName, 'valueName');
+    const debugValues = [];
+    for (const example of values) {
+        if (sameValueZero(example, value))
+            return;
+        debugValues.push(example);
+    }
+    throw new TypeError(`Expected ${valueName} to be any of: ${joinWithConjunction(debugValues.map((v) => formatDebugValue(v, { maxDepth: 1 })), 'or')}, got ${formatDebugValue(value)} instead.`);
+}
+export function isTuple(...predicates) {
+    assertPredicates(predicates);
+    return describePredicate((value) => {
+        return (isArray(value) &&
+            value.length === predicates.length &&
+            predicates.every((predicate, index) => predicate(value[index])));
+    }, `to be a tuple [${predicates
+        .map((predicate) => {
+        const descriptor = getPredicateDescriptor(predicate);
+        return hasProp(descriptor, 'type') ?
+            descriptor.type
+            : getPredicateConditions(predicate).condition;
+    })
+        .join(',')}]`);
+}
+export function assertTuple(value, ...rest) {
+    let valueName = 'value', predicates;
+    if (isString(rest[0])) {
+        valueName = rest[0];
+        predicates = rest.slice(1);
+    }
+    else {
+        predicates = rest;
+    }
+    assertPredicates(predicates);
+    invariantPredicate(isTuple(...predicates), value, valueName);
+}
+/* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ INTERNALS ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */
+function assertPredicates(predicates) {
+    assertArray(predicates, isFunction, 'predicates');
+}
+/* ───────────────────────────────── Types ────────────────────────────────── */
+//# sourceMappingURL=hlf.js.map

package/dist/guards/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * This module provides type guards, assertions, and related utilities for JavaScript types.
+ *
+ * @module
+ * @showCategories
+ * @importTarget ./guards
+ */
+import type { DescribePredicateFn, DescribeTypePredicateFn, FormatDebugValueFn, FormatErrorFn, FormatPredicateExpectedMessageFn, GetPredicateDescriptorFn, InvariantFn, InvariantPredicateFn } from './types.js';
+import { objectTag, shortObjectTag } from './format.js';
+export type * from './types.js';
+export { assertArray, assertBoolean, assertDate, assertDef, assertError, assertFunction, assertMap, assertNotNil, assertNumber, assertObject, assertPrimitive, assertPropKey, assertRegExp, assertSet, assertString, assertSymbol, assertWeakMapLike, assertWeakSetLike, callPredicate, } from './assert.js';
+export * from './check.js';
+export { formatDebugType } from './format.js';
+export * from './hlf.js';
+export * from './prop.js';
+export { objectTag, shortObjectTag };
+/**
+ * {@link InvariantFn} implementation.
+ *
+ * @inheritDoc {@link InvariantFn}
+ * @category Assertions
+ */
+export declare const invariant: InvariantFn;
+/**
+ * {@link InvariantPredicateFn} implementation.
+ *
+ * @inheritDoc {@link InvariantPredicateFn}
+ * @category Assertions
+ */
+export declare const invariantPredicate: InvariantPredicateFn;
+/**
+ * {@link DescribeTypePredicateFn} implementation.
+ *
+ * @inheritDoc {@link DescribeTypePredicateFn}
+ * @category Describing
+ */
+export declare const describeTypePredicate: DescribeTypePredicateFn;
+/**
+ * {@link DescribePredicateFn} implementation.
+ *
+ * @inheritDoc {@link DescribePredicateFn}
+ * @category Describing
+ */
+export declare const describePredicate: DescribePredicateFn;
+/**
+ * {@link GetPredicateDescriptorFn} implementation.
+ *
+ * @inheritDoc {@link GetPredicateDescriptorFn}
+ * @category Describing
+ */
+export declare const getPredicateDescriptor: GetPredicateDescriptorFn;
+/**
+ * {@link FormatPredicateExpectedMessageFn} implementation.
+ *
+ * @inheritDoc {@link FormatPredicateExpectedMessageFn}
+ * @category Formatting
+ */
+export declare const formatPredicateExpectedMessage: FormatPredicateExpectedMessageFn;
+/**
+ * {@link FormatErrorFn} implementation.
+ *
+ * @inheritDoc {@link FormatErrorFn}
+ * @category Formatting
+ */
+export declare const formatError: FormatErrorFn;
+/**
+ * {@link FormatDebugValueFn} implementation.
+ *
+ * @inheritDoc {@link FormatDebugValueFn}
+ * @category Formatting
+ */
+export declare const formatDebugValue: FormatDebugValueFn;
+//# sourceMappingURL=index.d.ts.map

package/dist/guards/index.js

@@ -0,0 +1,124 @@
+/**
+ * This module provides type guards, assertions, and related utilities for JavaScript types.
+ *
+ * @module
+ * @showCategories
+ * @importTarget ./guards
+ */
+import { invariant as _invariant, invariantPredicate as _invariantPredicate, assertBoolean, assertError, assertFunction, assertString, } from './assert.js';
+import { isFunction, isInteger, isNonNegative, isNumber, isObject, isString, isTrue, isUndef, isWeakSetLike, } from './check.js';
+import { describePredicate as _describePredicate, describeTypePredicate as _describeTypePredicate, getPredicateDescriptor as _getPredicateDescriptor, } from './describe.js';
+import { formatDebugValue as _formatDebugValue, formatError as _formatError, formatPredicateExpectedMessage as _formatPredicateExpectedMessage, objectTag, shortObjectTag, } from './format.js';
+import { assertSome, everyPredicate } from './hlf.js';
+import { assertOptionalProp } from './prop.js';
+// Value exports
+export { assertArray, assertBoolean, assertDate, assertDef, assertError, assertFunction, assertMap, assertNotNil, assertNumber, assertObject, assertPrimitive, assertPropKey, assertRegExp, assertSet, assertString, assertSymbol, assertWeakMapLike, assertWeakSetLike, callPredicate, } from './assert.js';
+export * from './check.js';
+export { formatDebugType } from './format.js';
+export * from './hlf.js';
+export * from './prop.js';
+export { objectTag, shortObjectTag };
+/* ~~~~~~~~~~~~~~~~~~~~~~~~~~~ TYPE-SAFE WRAPPERS ~~~~~~~~~~~~~~~~~~~~~~~~~~~ */
+/* ─────────────────────────────── assert.ts ──────────────────────────────── */
+/**
+ * {@link InvariantFn} implementation.
+ *
+ * @inheritDoc {@link InvariantFn}
+ * @category Assertions
+ */
+export const invariant = (condition, message = formatPredicateExpectedMessage(isTrue, false, 'condition')) => {
+    assertBoolean(condition, 'condition');
+    assertSome(message, 'message', isString, isFunction);
+    _invariant(condition, isString(message) ? message : (() => {
+        const result = message();
+        assertString(result, 'message function result');
+        return result;
+    }));
+};
+/**
+ * {@link InvariantPredicateFn} implementation.
+ *
+ * @inheritDoc {@link InvariantPredicateFn}
+ * @category Assertions
+ */
+export const invariantPredicate = (predicate, value, valueName = 'value') => {
+    assertFunction(predicate);
+    assertString(valueName);
+    _invariantPredicate(predicate, value, valueName);
+};
+/* ────────────────────────────── describe.ts ─────────────────────────────── */
+/**
+ * {@link DescribeTypePredicateFn} implementation.
+ *
+ * @inheritDoc {@link DescribeTypePredicateFn}
+ * @category Describing
+ */
+export const describeTypePredicate = (typeGuard, typeDescription) => {
+    assertFunction(typeGuard, 'typeGuard');
+    assertString(typeDescription, 'typeDescription');
+    return _describeTypePredicate(typeGuard, typeDescription);
+};
+/**
+ * {@link DescribePredicateFn} implementation.
+ *
+ * @inheritDoc {@link DescribePredicateFn}
+ * @category Describing
+ */
+export const describePredicate = (predicate, conditionDescription) => {
+    assertFunction(predicate, 'predicate');
+    assertString(conditionDescription, 'conditionDescription');
+    return _describePredicate(predicate, conditionDescription);
+};
+/**
+ * {@link GetPredicateDescriptorFn} implementation.
+ *
+ * @inheritDoc {@link GetPredicateDescriptorFn}
+ * @category Describing
+ */
+export const getPredicateDescriptor = (predicate) => {
+    assertFunction(predicate, 'predicate');
+    return _getPredicateDescriptor(predicate);
+};
+/* ─────────────────────────────── format.ts ──────────────────────────────── */
+/**
+ * {@link FormatPredicateExpectedMessageFn} implementation.
+ *
+ * @inheritDoc {@link FormatPredicateExpectedMessageFn}
+ * @category Formatting
+ */
+export const formatPredicateExpectedMessage = (predicate, value, valueName = 'value') => {
+    assertFunction(predicate);
+    assertString(valueName, 'valueName');
+    return _formatPredicateExpectedMessage(predicate, value, valueName);
+};
+/**
+ * {@link FormatErrorFn} implementation.
+ *
+ * @inheritDoc {@link FormatErrorFn}
+ * @category Formatting
+ */
+export const formatError = (error, options) => {
+    assertError(error);
+    assertFormatOptions(options);
+    return _formatError(error, options);
+};
+/**
+ * {@link FormatDebugValueFn} implementation.
+ *
+ * @inheritDoc {@link FormatDebugValueFn}
+ * @category Formatting
+ */
+export const formatDebugValue = (value, options) => {
+    assertFormatOptions(options);
+    return _formatDebugValue(value, options);
+};
+/* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ INTERNALS ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */
+/* ─────────────────────────────── Utilities ──────────────────────────────── */
+function assertFormatOptions(options) {
+    assertSome(options, 'options', isObject, isUndef);
+    const numberKeys = ['maxDepth', 'maxLength', 'maxItems'];
+    for (const key of numberKeys)
+        assertOptionalProp(options, key, everyPredicate(isNumber, isNonNegative, isInteger));
+    assertOptionalProp(options, 'seen', isWeakSetLike, 'options');
+}
+//# sourceMappingURL=index.js.map

package/dist/guards/message.d.ts

@@ -0,0 +1,102 @@
+import type { Predicate } from '@budsbox/lib-types';
+/**
+ * Creates an expected message string for a given predicate, value, and value name.
+ *
+ * This function validates that the predicate is a valid function and constructs
+ * an informative error message describing what was expected of the `value` in
+ * terms of the `predicate`'s description or descriptor. This message integrates
+ * details about the provided `value` to aid debugging.
+ *
+ * @internal
+ * @param predicate - The predicate function used to test the value. Must be a valid function.
+ * @param value - The value being evaluated against the predicate.
+ * @param valueName - The name of the value being tested. Defaults to `'value'`.
+ * @returns A formatted string message describing the expected value and its type.
+ * @throws {TypeError} if the `predicate` is not a function.
+ */
+export declare const formatPredicateExpectedMessage: (predicate: Predicate, value: unknown, valueName?: string) => string;
+/**
+ * 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.
+ */
+export declare const getPredicateConditions: (predicate: Predicate, nested?: boolean) => {
+    condition: string;
+    isType: boolean;
+    isValue: boolean;
+};
+/**
+ * Determines the type description of a given value in a human-readable format.
+ *
+ * - 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.
+ */
+export declare const debugValueType: (value: unknown) => string;
+/**
+ * Generates a string representation of a given value for debugging purposes.
+ *
+ * The function handles various data types and outputs an appropriate string representation:
+ * - Strings are truncated to 15 characters and represented in JSON format.
+ * - Primitives are converted to their string form.
+ * - Functions are represented by their name or identified as anonymous.
+ * - Arrays are truncated to a preview of up to 5 elements, followed by `...` if there are more.
+ * - Objects attempt to serialize to JSON, truncating lengthy results, or falling back to custom fallback logic.
+ *
+ * @param value - A value of any type to be represented as a debug string.
+ * @param options
+ * @returns A debug-friendly string representation of the provided value.
+ */
+export declare const debugValueString: (value: unknown, { maxLength, maxDepth, maxItems, seen, }?: {
+    maxLength?: number | undefined;
+    maxDepth?: number | undefined;
+    maxItems?: number | undefined;
+    seen?: WeakSet<unknown> | undefined;
+}) => string;
+/**
+ *
+ * @param value
+ */
+export declare const formatError: (value: Error) => string;
+/**
+ * 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.
+ */
+export declare const shortObjectTag: (value: unknown) => string;
+/**
+ *
+ * @param value
+ */
+export declare const objectTag: (value: unknown) => string;
+//# sourceMappingURL=message.d.ts.map