@budsbox/lib-es 2.2.0 → 3.0.0

package/dist/guards/types.d.ts

@@ -0,0 +1,256 @@
+import type { Predicate, TypePredicate } from '@budsbox/lib-types';
+/**
+ * Extracts the narrowed types from a list of predicates into a corresponding tuple.
+ *
+ * This helper type recursively processes a tuple of predicates and extracts the second type parameter
+ * (the narrowed type) from each predicate. The result is a new tuple where each element represents
+ * what the input type would be narrowed to if that predicate's type guard succeeds.
+ *
+ * When used with {@link TypePredicate} types, this is particularly useful for functions like
+ * {@link everyPredicate} that need to intersect all narrowed types, or {@link somePredicate}
+ * that need to union them.
+ *
+ * @typeParam TPredicates - A readonly tuple of {@link Predicate} types to extract narrow types from.
+ * @example
+ * ```typescript
+ * type Guard1 = (v: unknown) => v is string;
+ * type Guard2 = (v: unknown) => v is { name: string };
+ * type Narrowed = PredicatesListNarrowType<[Guard1, Guard2]>;
+ * // Narrowed = [string, { name: string }]
+ * ```
+ * @example
+ * ```typescript
+ * // Used in practice with everyPredicate
+ * const isString = (v: unknown): v is string => typeof v === 'string';
+ * const hasLength = (v: unknown): v is { length: number } => 'length' in (v as any);
+ * const predicate = everyPredicate(isString, hasLength);
+ * // The type system narrows to: string & { length: number }
+ * ```
+ */
+export type PredicatesListNarrowed<TPredicates extends readonly Predicate[]> = TPredicates extends [infer TLeft, ...infer TRight] ? [
+    TLeft extends Predicate<infer _, infer TNarrow> ? TNarrow : never,
+    ...PredicatesListNarrowed<TRight extends readonly Predicate[] ? TRight : never>
+] : TPredicates extends readonly [infer TLeft, ...infer TRight] ? [
+    TLeft extends Predicate<infer _, infer TNarrow> ? TNarrow : never,
+    ...PredicatesListNarrowed<TRight extends readonly Predicate[] ? TRight : never>
+] : TPredicates extends readonly [] ? [] : TPredicates extends ReadonlyArray<Predicate<infer _, infer TNarrow>> ? TNarrow[] : never;
+/**
+ * Extracts the input argument types from a list of predicates into a corresponding tuple.
+ *
+ * This helper type recursively processes a tuple of predicates and extracts the first type parameter
+ * (the input type) from each predicate. The result is a new tuple where each element represents
+ * the type that the predicate expects as input.
+ *
+ * @typeParam TPredicates - A readonly tuple of {@link Predicate} types to extract argument types from.
+ * @example
+ * ```typescript
+ * type Guard1 = (v: string) => boolean;
+ * type Guard2 = (v: string) => boolean;
+ * type Args = PredicatesListArg<[Guard1, Guard2]>;
+ * // Args = [string, string]
+ * ```
+ * @example
+ * ```typescript
+ * // Used in practice with everyPredicate
+ * const isLongerThan5 = (v: string) => v.length > 5;
+ * const isUpperCase = (v: string) => v === v.toUpperCase();
+ * const predicate = everyPredicate(isLongerThan5, isUpperCase);
+ * // Both predicates require string input, so the value must be a string
+ * ```
+ */
+export type PredicatesListArg<TPredicates extends readonly Predicate[]> = TPredicates extends [infer TLeft, ...infer TRight] ? [
+    TLeft extends Predicate<infer TArg, infer _> ? TArg : never,
+    ...PredicatesListArg<TRight extends readonly Predicate[] ? TRight : never>
+] : TPredicates extends readonly [] ? [] : TPredicates extends ReadonlyArray<Predicate<infer TArg>> ? TArg[] : never;
+/**
+ * Transforms a list of predicates' narrowed types into a tuple where each element is optional.
+ *
+ * This type extracts the narrowed types from each predicate using {@link PredicatesListNarrowed},
+ * then makes each type in the resulting tuple optional by unioning it with undefined.
+ * Useful for cases where partial satisfaction of predicates is acceptable.
+ *
+ * @typeParam TPredicates - A readonly tuple of {@link Predicate} types to normalize.
+ * @example
+ * ```typescript
+ * type Guard1 = (v: unknown) => v is string;
+ * type Guard2 = (v: unknown) => v is number;
+ * type Normalized = NormalizedOptionalRest<[Guard1, Guard2]>;
+ * // Normalized = [string | undefined, number | undefined]
+ * ```
+ * @example
+ * ```typescript
+ * // Applied to type predicates with different narrowed types
+ * type Predicates = [
+ *   (v: unknown) => v is boolean,
+ *   (v: unknown) => v is { id: string }
+ * ];
+ * type Result = NormalizedOptionalRest<Predicates>;
+ * // Result = [boolean | undefined, { id: string } | undefined]
+ * ```
+ */
+export type NormalizedOptionalRest<TPredicates extends readonly Predicate[]> = OptionalsTuple<PredicatesListNarrowed<TPredicates>>;
+type OptionalsTuple<TTuple extends readonly unknown[]> = TTuple extends readonly [] ? [] : TTuple extends readonly [infer THead, ...infer TRest] ? [
+    THead | undefined,
+    ...OptionalsTuple<TRest>
+] : never;
+/**
+ * Asserts that a given condition is true. Throws an error if the condition is false.
+ * The error message can be a string or a lazily evaluated function that returns a string.
+ *
+ * @param condition - A boolean expression that is expected to evaluate to true.
+ * @param message - An optional error message or a function that generates the error message
+ *                if the condition evaluates to false. Defaults to 'Expected condition to be true'.
+ * @throws {@link !TypeError} in the following cases:
+ * - if the condition evaluates to false
+ * - if the condition is not a boolean
+ * - if the message is not a string or a function that returns a string
+ * @inline
+ * @category Assertions
+ */
+export type InvariantFn = (condition: boolean, message?: string | (() => string)) => asserts condition is true;
+/**
+ * Asserts that the given value satisfies the specified predicate function. If the value
+ * does not satisfy the predicate, an error will be thrown. If the predicate is a type guard,
+ * the value will be narrowed accordingly.
+ *
+ * @internal
+ * @param predicate - A predicate function used to validate the value. Optionally, the predicate
+ * may act as a type guard and narrow the type of the value.
+ * @param value - The value to be verified against the predicate.
+ * @param valueName - The name of the value for the error message. Defaults to 'value'.
+ * @throws {@link !TypeError} - if the value does not meet the requirements defined by the predicate.
+ * @typeParam TValue - The type of the value being checked.
+ * @typeParam TGuardInput - The type of the input to the predicate.
+ * @typeParam TNarrowed - The narrowed type of the value if the predicate is a type guard.
+ * @category Assertions
+ */
+export interface InvariantPredicateFn {
+    <TNarrowed>(predicate: TypePredicate<unknown, TNarrowed>, value: unknown, valueName?: string): asserts value is TNarrowed;
+    <TValue extends TGuardInput, TGuardInput, TNarrowed extends TGuardInput>(predicate: TypePredicate<TGuardInput, TNarrowed>, value: TValue, valueName?: string): asserts value is TValue extends TNarrowed ? TValue : TValue & TNarrowed;
+    <TValue>(predicate: Predicate<TValue>, value: TValue, valueName?: string): void;
+    (predicate: Predicate, value: unknown, valueName?: string): void;
+}
+/**
+ * Represents a descriptor for a predicate.
+ *
+ * @category Describing
+ */
+export type PredicateDescriptor = {
+    and: readonly Predicate[];
+} | {
+    condition: string;
+} | {
+    or: readonly Predicate[];
+} | {
+    type: string;
+};
+/**
+ * Adds a human-readable description to a given type guard function, enhancing its metadata.
+ * This metadata can later be used for debugging, logging, or explanatory purposes.
+ *
+ * @internal
+ * @param predicate - A predicate responsible for evaluating whether a value satisfies
+ * a specific type.
+ * @param typeDescription - A string description of the type that the `predicate` validates.
+ * @returns The original predicate, with the description attached.
+ * @throws {@link !TypeError} If `typeGuard` is not a function or `typeDescription` is not a string.
+ * @category Describing
+ */
+export type DescribeTypePredicateFn = <TPredicate extends Predicate>(predicate: TPredicate, typeDescription: string) => TPredicate;
+/**
+ * Adds a human-readable description to a given predicate function, enhancing its metadata.
+ * This metadata can later be used for debugging, logging, or explanatory purposes.
+ *
+ * @param predicate - The predicate function to associate with a description. Must be a valid function.
+ * @param conditionDescription - A description explaining the condition represented by the predicate. Must be a string.
+ * @returns The original predicate function, with the description attached.
+ * @throws {@link !TypeError} If `predicate` is not a function or `conditionDescription` is not a string.
+ * @category Describing
+ */
+export type DescribePredicateFn = <TPredicate extends Predicate>(predicate: TPredicate, conditionDescription: string) => TPredicate;
+/**
+ * Retrieves the descriptor associated with a given predicate function, if available.
+ *
+ * @internal
+ * @param predicate - A predicate function to retrieve the descriptor from.
+ * @returns The `PredicateDescriptor` associated with the predicate, or `undefined` if not present.
+ * @throws {@link !TypeError} If the provided `predicate` is not a function.
+ * @category Describing
+ */
+export type GetPredicateDescriptorFn = (predicate: Predicate) => PredicateDescriptor | undefined;
+/**
+ * Formats an error message indicating the expected condition for a predicate function.
+ *
+ * @param predicate - The predicate function to generate an error message for.
+ * @param value - The value that failed to satisfy the predicate.
+ * @param valueName - The name of the value for the error message. Defaults to 'value'.
+ * @returns A formatted error message describing what was expected.
+ * @throws {@link !TypeError} If `predicate` is not a function or `valueName` is not a string.
+ * @category Formatting
+ */
+export type FormatPredicateExpectedMessageFn = (predicate: Predicate, value: unknown, valueName?: string) => string;
+/**
+ * Formats an {@link Error} object into a concise debug string.
+ *
+ * Includes the error's name, message, optional `code` and `cause` properties,
+ * and a truncated stack trace. Nested values are formatted using {@link formatDebugValue}.
+ *
+ * @param error - The error to format.
+ * @param options - Optional formatting configuration via {@link FormatOptions}.
+ * @returns A formatted string representation of the error.
+ * @throws {@link !TypeError} If `error` is not an instance of {@link Error}.
+ * @category Formatting
+ */
+export type FormatErrorFn = (error: Error, options?: FormatOptions) => string;
+/**
+ * Formats a value into a human-readable debug string representation.
+ *
+ * Handles primitives, arrays, objects, functions, dates, errors, maps, sets,
+ * and objects with custom `toString` methods. Circular references are detected
+ * and marked as `[Circular]` for arrays or `{Circular}` for objects.
+ *
+ * @param value - The value to format for debugging purposes.
+ * @param options - Optional formatting configuration via {@link FormatOptions}.
+ * @returns A string representation suitable for debug output.
+ * @throws {@link !TypeError} in the following cases:
+ * - `options` is not an object or `undefined`.
+ * - `options` has a `maxDepth` property that is not a positive integer.
+ * - `options` has a `maxArrayLength` property that is not a positive integer.
+ * - `options` has a `maxStringLength` property that is not a positive integer.
+ * @category Formatting
+ */
+export type FormatDebugValueFn = (value: unknown, options?: FormatOptions) => string;
+/**
+ * Configuration options for debug formatting functions.
+ *
+ * @category Formatting
+ */
+export interface FormatOptions {
+    /**
+     * Maximum recursion depth for nested structures.
+     *
+     * @defaultValue `2`
+     */
+    readonly maxDepth?: number;
+    /**
+     * Maximum number of items to display in arrays.
+     *
+     * @defaultValue `5`
+     */
+    readonly maxItems?: number;
+    /**
+     * Maximum string length before truncation.
+     *
+     * @defaultValue `15`
+     */
+    readonly maxLength?: number;
+    /**
+     * Set of already-seen objects for circular reference detection.
+     *
+     * @internal
+     * @defaultValue `new WeakSet()`
+     */
+    readonly seen?: WeakSet<object>;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/guards/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/logical.d.ts

@@ -1,53 +1,61 @@
-import type { FValueFalse, FValueTrue, TestFn } from './types.js';
+/**
+ * This module provides functional logical operations and utilities.
+ *
+ * @module
+ * @importTarget ./logical
+ */
+import type { Predicate } from '@budsbox/lib-types';
+import type { FValueFalse, FValueTrue } from './types.js';
 import { isNotNil, isTrue } from '#guards';
+export type { FValueFalse, FValueTrue };
 /**
  * Functional If
  *
  * Evaluates a value with a given test and returns a value (or executes a function and returns its result) based on the result.
  *
- * @typeParam TValue - The type of the value to be tested.
- * @typeParam TTestFn - The type of the test function that takes the value as a parameter and returns a boolean.
- * @typeParam TTrue - The type of the value or the return type of the function if the test's result is true.
- * @typeParam TFalse - The type of the value or the return type of the function if the test's result is true.
  * @param value - The value to test against the provided test function.
  * @param test - A function to evaluate the provided value.
  * @param onTrue - A function or value to execute or return if the test evaluates to true.
  * @param onFalse - A function or value to execute or return if the test evaluates to false.
  * @returns The value or the result of the function based on the test result
+ * @typeParam TValue - The type of the value to be tested.
+ * @typeParam TTestFn - The type of the test function that takes the value as a parameter and returns a boolean.
+ * @typeParam TTrue - The type of the value or the return type of the function if the test's result is true.
+ * @typeParam TFalse - The type of the value or the return type of the function if the test's result is true.
  * @example
  * ```ts
  * const result1 = fif(10, (n) => n > 5, 'Greater', 'Smaller');
  * // result1 is 'Greater'
  *
- * const result2 = fif(3, (n) => n > 5, (n) => `Above ${n}`, (n) => `Below ${n}`);
- * // result2 is 'Below 3'
+ * const result2 = fif(3, (n) => n > 5, (n) => `${n} greater than 5`, (n) => `${n} below 5`);
+ * // result2 is '3 below 5'
  * ```
  */
-export declare function fif<TValue, TTestFn extends TestFn<TValue>, TTrue, TFalse = undefined>(value: TValue, test: TTestFn, onTrue: FValueTrue<TValue, TTestFn, TTrue>, onFalse?: FValueFalse<TValue, TTestFn, TFalse>): TTrue | TFalse;
+export declare function fif<TValue, TTestFn extends Predicate<TValue>, TTrue, TFalse = undefined>(value: TValue, test: TTestFn, onTrue: FValueTrue<TValue, TTestFn, TTrue>, onFalse?: FValueFalse<TValue, TTestFn, TFalse>): TFalse | TTrue;
 /**
  * Functional If (Static)
  *
  * Evaluates a condition and returns a value or executes a function based on the result.
  *
- * @typeParam TTrue - The type of the value or the return type of the function if the condition is true.
- * @typeParam TFalse - The type of the value or the return type of the function if condition is true.
  * @param condition - The condition to evaluate.
  * @param onTrue - The value or function to return/execute if the condition is true. If it's a function, it receives `true` as an argument.
  * @param onFalse - The value or function to return/execute if the condition is false. If it's a function, it receives `false` as an argument.
  * @returns The value or the result of the function based on the evaluated condition.
+ * @typeParam TTrue - The type of the value or the return type of the function if the condition is true.
+ * @typeParam TFalse - The type of the value or the return type of the function if condition is true.
  */
-export declare function fifs<TTrue, TFalse = undefined>(condition: boolean, onTrue: FValueTrue<boolean, typeof isTrue, TTrue>, onFalse?: FValueFalse<boolean, typeof isTrue, TFalse>): TTrue | TFalse;
+export declare function fifs<TTrue, TFalse = undefined>(condition: boolean, onTrue: FValueTrue<boolean, typeof isTrue, TTrue>, onFalse?: FValueFalse<boolean, typeof isTrue, TFalse>): TFalse | TTrue;
 /**
  * Ensures that the provided value is not null or undefined
  * and returns a value (or executes a function and returns it's result) based on the result.
  *
- * @typeParam TValue - The type of the value to be checked.
- * @typeParam TTrue - The type of the value or the return type of the function if the value is not null or undefined.
- * @typeParam TFalse - The type of the value or the return type of the function if the value is null or undefined.
  * @param value - The value to be checked.
  * @param onTrue - Callback function to be executed if the value is not null or undefined.
  * @param onFalse - (Optional) Callback function to be executed if the value is null or undefined.
  * @returns The result of the appropriate callback function based on the evaluation of the value.
+ * @typeParam TValue - The type of the value to be checked.
+ * @typeParam TTrue - The type of the value or the return type of the function if the value is not null or undefined.
+ * @typeParam TFalse - The type of the value or the return type of the function if the value is null or undefined.
  */
-export declare function sure<TValue, TTrue, TFalse = undefined>(value: TValue, onTrue: FValueTrue<TValue, typeof isNotNil, TTrue>, onFalse?: FValueFalse<TValue, typeof isNotNil, TFalse>): TTrue | TFalse;
+export declare function sure<TValue, TTrue, TFalse = undefined>(value: TValue, onTrue: FValueTrue<TValue, typeof isNotNil, TTrue>, onFalse?: FValueFalse<TValue, typeof isNotNil, TFalse>): TFalse | TTrue;
 //# sourceMappingURL=logical.d.ts.map

package/dist/logical.js

@@ -1,49 +1,28 @@
-import { isFunction, isNotNil, isTrue } from '#guards';
 /**
- * Functional If
+ * This module provides functional logical operations and utilities.
  *
- * Evaluates a value with a given test and returns a value (or executes a function and returns its result) based on the result.
- *
- * @typeParam TValue - The type of the value to be tested.
- * @typeParam TTestFn - The type of the test function that takes the value as a parameter and returns a boolean.
- * @typeParam TTrue - The type of the value or the return type of the function if the test's result is true.
- * @typeParam TFalse - The type of the value or the return type of the function if the test's result is true.
- * @param value - The value to test against the provided test function.
- * @param test - A function to evaluate the provided value.
- * @param onTrue - A function or value to execute or return if the test evaluates to true.
- * @param onFalse - A function or value to execute or return if the test evaluates to false.
- * @returns The value or the result of the function based on the test result
- * @example
- * ```ts
- * const result1 = fif(10, (n) => n > 5, 'Greater', 'Smaller');
- * // result1 is 'Greater'
- *
- * const result2 = fif(3, (n) => n > 5, (n) => `Above ${n}`, (n) => `Below ${n}`);
- * // result2 is 'Below 3'
- * ```
+ * @module
+ * @importTarget ./logical
  */
+import { callPredicate, isFunction, isNotNil, isTrue } from '#guards';
 export function fif(value, test, onTrue, onFalse) {
-    if (test(value)) {
-        return isFunction(onTrue) ?
-            onTrue(value)
-            : onTrue;
-    }
-    if (isFunction(onFalse)) {
-        return onFalse(value);
-    }
-    return onFalse;
+    return (callPredicate(test, value, 'test') ?
+        isFunction(onTrue) ? onTrue(value)
+            : onTrue
+        : isFunction(onFalse) ? onFalse(value)
+            : onFalse);
 }
 /**
  * Functional If (Static)
  *
  * Evaluates a condition and returns a value or executes a function based on the result.
  *
- * @typeParam TTrue - The type of the value or the return type of the function if the condition is true.
- * @typeParam TFalse - The type of the value or the return type of the function if condition is true.
  * @param condition - The condition to evaluate.
  * @param onTrue - The value or function to return/execute if the condition is true. If it's a function, it receives `true` as an argument.
  * @param onFalse - The value or function to return/execute if the condition is false. If it's a function, it receives `false` as an argument.
  * @returns The value or the result of the function based on the evaluated condition.
+ * @typeParam TTrue - The type of the value or the return type of the function if the condition is true.
+ * @typeParam TFalse - The type of the value or the return type of the function if condition is true.
  */
 export function fifs(condition, onTrue, onFalse) {
     return fif(condition, isTrue, onTrue, onFalse);
@@ -52,13 +31,13 @@ export function fifs(condition, onTrue, onFalse) {
  * Ensures that the provided value is not null or undefined
  * and returns a value (or executes a function and returns it's result) based on the result.
  *
- * @typeParam TValue - The type of the value to be checked.
- * @typeParam TTrue - The type of the value or the return type of the function if the value is not null or undefined.
- * @typeParam TFalse - The type of the value or the return type of the function if the value is null or undefined.
  * @param value - The value to be checked.
  * @param onTrue - Callback function to be executed if the value is not null or undefined.
  * @param onFalse - (Optional) Callback function to be executed if the value is null or undefined.
  * @returns The result of the appropriate callback function based on the evaluation of the value.
+ * @typeParam TValue - The type of the value to be checked.
+ * @typeParam TTrue - The type of the value or the return type of the function if the value is not null or undefined.
+ * @typeParam TFalse - The type of the value or the return type of the function if the value is null or undefined.
  */
 export function sure(value, onTrue, onFalse) {
     return fif(value, isNotNil, onTrue, onFalse);

package/dist/map.d.ts

@@ -0,0 +1,48 @@
+/**
+ * This module provides Map-related utilities, including a read-only Map implementation.
+ *
+ * @module
+ * @importTarget ./map
+ */
+import type { Nil } from '@budsbox/lib-types';
+/**
+ * A read-only Map implementation that conforms to the `ReadonlyMap` interface.
+ * This class provides a wrapper around `Map` to enforce immutability.
+ *
+ * @typeParam K - The type of keys maintained by this map.
+ * @typeParam V - The type of mapped values.
+ */
+export declare class ROMap<K, V> extends Map<K, V> implements ReadonlyMap<K, V> {
+    /**
+     * Constructs a new instance of the class with an optional collection of entries.
+     *
+     * @param entries - An optional iterable object containing key-value pairs (tuples) to initialize the map.
+     * If not provided or set to `Nil`, the map will be empty.
+     * @typeParam K - The type of the keys in the map.
+     * @typeParam V - The type of the values in the map.
+     */
+    constructor(entries?: Iterable<readonly [K, V]> | Nil);
+    /**
+     * Throws a `TypeError` exception because the map is read-only.
+     *
+     * @param args - The arguments to be passed to the `Map.set` method.
+     * @returns This method does not return a value.
+     * @throws {@link !TypeError} Indeed: map is read-only.
+     * @privateRemarks It works as original `Map#set` when invoked from the constructor.
+     */
+    set(...args: readonly [key: K, value: V]): never;
+    /**
+     * Throws a `TypeError` exception because the map is read-only.
+     *
+     * @param key - The key of the element to remove from the map.
+     * @throws {@link !TypeError} Indeed: map is read-only.
+     */
+    delete(key: K): never;
+    /**
+     * Throws a `TypeError` exception because the map is read-only.
+     *
+     * @throws {@link !TypeError} Indeed: map is read-only.
+     */
+    clear(): never;
+}
+//# sourceMappingURL=map.d.ts.map

package/dist/map.js

@@ -0,0 +1,74 @@
+/**
+ * This module provides Map-related utilities, including a read-only Map implementation.
+ *
+ * @module
+ * @importTarget ./map
+ */
+/**
+ * A read-only Map implementation that conforms to the `ReadonlyMap` interface.
+ * This class provides a wrapper around `Map` to enforce immutability.
+ *
+ * @typeParam K - The type of keys maintained by this map.
+ * @typeParam V - The type of mapped values.
+ */
+export class ROMap extends Map {
+    /**
+     * Constructs a new instance of the class with an optional collection of entries.
+     *
+     * @param entries - An optional iterable object containing key-value pairs (tuples) to initialize the map.
+     * If not provided or set to `Nil`, the map will be empty.
+     * @typeParam K - The type of the keys in the map.
+     * @typeParam V - The type of the values in the map.
+     */
+    constructor(entries) {
+        super(entries);
+        createdMaps.add(this);
+    }
+    /**
+     * Throws a `TypeError` exception because the map is read-only.
+     *
+     * @param args - The arguments to be passed to the `Map.set` method.
+     * @returns This method does not return a value.
+     * @throws {@link !TypeError} Indeed: map is read-only.
+     * @privateRemarks It works as original `Map#set` when invoked from the constructor.
+     */
+    set(...args) {
+        if (createdMaps.has(this)) {
+            throw new TypeError(`Cannot set key ${String(args[0])}: map is read-only`);
+        }
+        // reachable from constructor only
+        return super.set(...args);
+    }
+    /**
+     * Throws a `TypeError` exception because the map is read-only.
+     *
+     * @param key - The key of the element to remove from the map.
+     * @throws {@link !TypeError} Indeed: map is read-only.
+     */
+    delete(key) {
+        throw new TypeError(`Cannot delete key ${String(key)}: map is read-only`);
+    }
+    /**
+     * Throws a `TypeError` exception because the map is read-only.
+     *
+     * @throws {@link !TypeError} Indeed: map is read-only.
+     */
+    clear() {
+        throw new TypeError('Cannot clear map: map is read-only');
+    }
+}
+const createdMaps = new WeakSet();
+/*
+ * This approach is slightly unconventional, but it allows the class to serve as
+ * a transparent implementation of the `ReadonlyMap` type.
+ */
+[
+    [ROMap, 'name'],
+    [ROMap.prototype, Symbol.toStringTag],
+].forEach(([obj, prop]) => {
+    Object.defineProperty(obj, prop, {
+        value: 'ReadonlyMap',
+        configurable: true,
+    });
+});
+//# sourceMappingURL=map.js.map

package/dist/object.d.ts

@@ -1,21 +1,100 @@
-import type { ConditionalExcept } from 'type-fest';
-import type { OmitNilProps, Value } from '@budsbox/lib-types/object';
-export declare function pick<T extends object, Keys extends PropertyKey = keyof T>(source: T, ...keys: readonly Keys[]): Pick<T, Keys & keyof T>;
-export declare const pickStrict: <T extends object, Keys extends keyof T = keyof T>(source: T, ...keys: readonly Keys[]) => Pick<T, Keys>;
+/**
+ * Object utility functions for selecting, omitting, filtering, reducing, and
+ * strongly-typing common object operations.
+ *
+ * @module
+ * @importTarget ./object
+ */
+import type { ValueOf } from 'type-fest';
+import type { AnyRecord, EntryUnion, OmitNilProps } from '@budsbox/lib-types';
+/**
+ * Creates an object composed of the picked `source` properties.
+ *
+ * @param source - The source object.
+ * @param keys - The property keys to pick.
+ * @returns A new object with the picked properties.
+ * @typeParam TSource - The type of the source object.
+ * @typeParam TKeys - The type of the keys to pick.
+ */
+export declare function pick<TSource extends object, TKeys extends PropertyKey = keyof TSource>(source: TSource, ...keys: readonly TKeys[]): Pick<TSource, TKeys & keyof TSource>;
+/**
+ * A strict version of {@link pick} that restricts keys to those present in `TSource`.
+ *
+ * @param source - The source object.
+ * @param keys - The property keys to pick.
+ * @returns A new object with the picked properties.
+ * @typeParam TSource - The type of the source object.
+ * @typeParam Keys - The type of the keys to pick, restricted to keys of `TSource`.
+ */
+export declare const pickStrict: <TSource extends object, Keys extends keyof TSource = keyof TSource>(source: TSource, ...keys: readonly Keys[]) => Pick<TSource, Keys>;
+/**
+ * The opposite of {@link pick}; this method creates an object
+ * composed of the own enumerable string keyed properties of `source` that are not omitted.
+ *
+ * @param source - The source object.
+ * @param keys - The property keys to omit.
+ * @returns A new object without the omitted properties.
+ * @typeParam T - The type of the source object.
+ * @typeParam K - The type of the keys to omit.
+ */
 export declare function omit<T extends object, K extends PropertyKey>(source: T, ...keys: readonly K[]): Omit<T, K>;
+/**
+ * A strict version of {@link omit} that restricts keys to those present in `TSource`.
+ *
+ * @param source - The source object.
+ * @param keys - The property keys to omit.
+ * @returns A new object without the omitted properties.
+ * @typeParam TSource - The type of the source object.
+ * @typeParam TKey - The type of the keys to omit, restricted to keys of `TSource`.
+ */
 export declare const omitStrict: <TSource extends object, TKey extends keyof TSource>(source: TSource, ...keys: readonly TKey[]) => Omit<TSource, TKey>;
-export declare function filterBy<T, K extends string, R extends T>(value: Partial<Record<K, T>>, test: (value: T) => value is R): ConditionalExcept<Record<K, T>, R>;
-export declare function filterBy<T, K extends string, R extends T>(value: Partial<Record<K, T>> | Record<K, T>, test: (value: T) => value is R): ConditionalExcept<Record<K, T>, R>;
-export declare function filterBy<V extends object>(obj: V, filter: (value: V[keyof V], key: keyof V, obj: V) => boolean): Partial<V>;
+/**
+ * Iterates over own enumerable string keyed properties of an object and returns a new object
+ * with all properties that pass `test`.
+ *
+ * @param obj - The object to filter.
+ * @param test - The function invoked per iteration.
+ * @returns A new object containing properties that satisfy the predicate.
+ * @typeParam TSource - The type of the source object.
+ */
+export declare function filter<TSource extends object>(obj: TSource, test: (value: ValueOf<TSource>, key: keyof TSource, obj: TSource) => boolean): Partial<TSource>;
+/**
+ * Returns a new object with all `null` or `undefined` properties removed using {@link filter} and {@link isNotNil}.
+ *
+ * @param object - The object to strip of nils.
+ * @returns A new object without nil properties.
+ * @typeParam T - The type of the source object.
+ */
 export declare function omitNils<T extends object>(object: T): OmitNilProps<T>;
-export declare function reduce<U>(obj: Readonly<Record<string, unknown>>, callback: (previousValue: U, currentValue: Value<typeof obj>, currentKey: keyof typeof obj, object: typeof obj) => U, initialValue: Partial<U>): U;
 /**
- * Returns the first key of the given object.
- * Useful when working with objects that have only one key.
+ * Transforms the values of an object using the provided callback function.
+ *
+ * @param object - The source object whose values are to be transformed.
+ * @param callback - A function that is called for each key-value pair in the source object.
+ * It receives the value, key, and the original object as arguments and returns the transformed value.
+ * @returns A new object with the same keys as the source object but with values transformed by the callback function.
+ * @typeParam TSource - The type of the source object.
+ * @typeParam TValue - The type of the transformed values in the resulting object.
+ */
+export declare const map: <TSource extends AnyRecord, TValue>(object: TSource, callback: (value: ValueOf<TSource>, key: keyof TSource, object: TSource) => TValue) => Record<keyof TSource, TValue>;
+/**
+ * Reduces `obj` to a value which is the accumulated result of running each element in `obj`
+ * through `callback`.
+ *
+ * @param obj - The object to iterate over.
+ * @param callback - The function invoked per iteration.
+ * @param initialValue - The initial value of the accumulation.
+ * @returns The accumulated value.
+ * @typeParam TSource - The type of the source object.
+ * @typeParam TResult - The type of the accumulated result.
+ */
+export declare function reduce<TSource extends object, TResult>(obj: TSource, callback: (previousValue: TResult, currentValue: ValueOf<TSource>, currentKey: keyof TSource, object: TSource) => TResult, initialValue: Partial<TResult>): TResult;
+/**
+ * Returns an array of a given object's own enumerable string-keyed property [key, value] pairs, typed as {@link EntryUnion}.
  *
- * @param value
+ * @param source - The object whose entries are to be returned.
+ * @returns An array of entry tuples.
+ * @typeParam T - The type of the source object.
  */
-export declare function getKey<T extends string>(value: Record<T, unknown>): T;
-export declare function getKey<T extends string>(value: Partial<Record<T, unknown>>): T | undefined;
-export declare function getKey<T extends object>(value: T): keyof T;
+export declare const entries: <T extends object>(source: T) => Array<EntryUnion<T>>;
 //# sourceMappingURL=object.d.ts.map