@dereekb/util 13.0.7 → 13.2.0

package/src/lib/boolean.d.ts

@@ -30,6 +30,14 @@ export declare function invertMaybeBoolean(x: Maybe<boolean>): Maybe<boolean>;
  * @param array - Array of boolean values to reduce.
  * @param emptyArrayValue - Value to return if the array is empty. If not provided and the array is empty, a TypeError will be thrown.
  * @returns The result of ANDing all boolean values in the array.
+ * @throws {TypeError} If the array is empty and no emptyArrayValue is provided.
+ *
+ * @example
+ * ```ts
+ * reduceBooleansWithAnd([true, true, true]);   // true
+ * reduceBooleansWithAnd([true, false, true]);   // false
+ * reduceBooleansWithAnd([], true);              // true (emptyArrayValue)
+ * ```
  */
 export declare function reduceBooleansWithAnd(array: boolean[], emptyArrayValue?: boolean): boolean;
 /**
@@ -38,6 +46,7 @@ export declare function reduceBooleansWithAnd(array: boolean[], emptyArrayValue?
  * @param array - Array of boolean values to reduce.
  * @param emptyArrayValue - Value to return if the array is empty. If not provided and the array is empty, a TypeError will be thrown.
  * @returns The result of ORing all boolean values in the array.
+ * @throws {TypeError} If the array is empty and no emptyArrayValue is provided.
  */
 export declare function reduceBooleansWithOr(array: boolean[], emptyArrayValue?: boolean): boolean;
 /**
@@ -45,6 +54,14 @@ export declare function reduceBooleansWithOr(array: boolean[], emptyArrayValue?:
  *
  * @param emptyArrayValue - Value to return if the array is empty. If not provided and the array is empty, the returned function will throw a TypeError.
  * @returns A function that takes an array of booleans and returns the result of ANDing them.
+ *
+ * @example
+ * ```ts
+ * const reduceAnd = reduceBooleansWithAndFn(true);
+ * reduceAnd([true, true]);  // true
+ * reduceAnd([true, false]); // false
+ * reduceAnd([]);            // true (emptyArrayValue)
+ * ```
  */
 export declare function reduceBooleansWithAndFn(emptyArrayValue?: boolean): (array: boolean[]) => boolean;
 /**
@@ -52,6 +69,14 @@ export declare function reduceBooleansWithAndFn(emptyArrayValue?: boolean): (arr
  *
  * @param emptyArrayValue - Value to return if the array is empty. If not provided and the array is empty, the returned function will throw a TypeError.
  * @returns A function that takes an array of booleans and returns the result of ORing them.
+ *
+ * @example
+ * ```ts
+ * const reduceOr = reduceBooleansWithOrFn(false);
+ * reduceOr([false, true]);  // true
+ * reduceOr([false, false]); // false
+ * reduceOr([]);             // false (emptyArrayValue)
+ * ```
  */
 export declare function reduceBooleansWithOrFn(emptyArrayValue?: boolean): (array: boolean[]) => boolean;
 /**
@@ -60,6 +85,13 @@ export declare function reduceBooleansWithOrFn(emptyArrayValue?: boolean): (arra
  * @param reduceFn - Function that takes two boolean values and returns a single boolean.
  * @param emptyArrayValue - Value to return if the array is empty. If not provided and the array is empty, the returned function will throw a TypeError because `Array.prototype.reduce` on an empty array without an initial value throws.
  * @returns A function that takes an array of booleans and returns the result of reducing them.
+ *
+ * @example
+ * ```ts
+ * const xorReduce = reduceBooleansFn((a, b) => a !== b, false);
+ * xorReduce([true, false]); // true
+ * xorReduce([]);            // false (emptyArrayValue)
+ * ```
  */
 export declare function reduceBooleansFn(reduceFn: (a: boolean, b: boolean) => boolean, emptyArrayValue?: boolean): (array: boolean[]) => boolean;
 /**
@@ -85,6 +117,15 @@ export interface BooleanFactoryConfig {
  *
  * @param config - Configuration for the boolean factory, including the chance of returning true.
  * @returns A factory function (`BooleanFactory`) that generates random boolean values based on the configured chance.
+ *
+ * @example
+ * ```ts
+ * const alwaysTrue = booleanFactory({ chance: 100 });
+ * alwaysTrue(); // true
+ *
+ * const coinFlip = booleanFactory({ chance: 50 });
+ * coinFlip(); // true or false with equal probability
+ * ```
  */
 export declare function booleanFactory(config: BooleanFactoryConfig): BooleanFactory;
 /**
@@ -102,12 +143,24 @@ export declare function randomBoolean(chance?: BooleanTrueChance): boolean;
  * @param value - The string to convert to a boolean.
  * @param defaultValue - The default value to return if the string cannot be converted to a boolean (default: undefined).
  * @returns The boolean value corresponding to the string, or the default value if the string cannot be converted.
+ *
+ * @example
+ * ```ts
+ * stringToBoolean('yes');          // true
+ * stringToBoolean('FALSE');        // false
+ * stringToBoolean('maybe');        // undefined
+ * stringToBoolean('maybe', true);  // true (defaultValue)
+ * ```
  */
 export declare function stringToBoolean(value: Maybe<string | boolean>): Maybe<boolean>;
 export declare function stringToBoolean(value: Maybe<string>, defaultValue: boolean): boolean;
 export declare function stringToBoolean(value: Maybe<string>, defaultValue?: Maybe<boolean>): Maybe<boolean>;
 /**
- * Converts the input value to a boolean, or null if the value is nullish.
+ * Converts a boolean to its `'true'` or `'false'` string representation.
+ * Returns null/undefined if the input is nullish.
+ *
+ * @param value - The boolean value to convert.
+ * @returns The string `'true'` or `'false'`, or the nullish input unchanged.
  */
 export declare function trueOrFalseString(value: boolean): TrueOrFalseString;
 export declare function trueOrFalseString(value?: MaybeNot): MaybeNot;

package/src/lib/contact/domain.d.ts

@@ -1,16 +1,34 @@
 import { type EmailAddress } from './email';
+/**
+ * Domain name portion of an email address (e.g., "example.com").
+ */
 export type EmailAddressDomain = string;
+/**
+ * Extracts unique domain names from a list of email addresses (case-insensitive).
+ *
+ * @param addresses - Array of email addresses to extract domains from
+ * @returns Array of unique lowercase domain strings
+ */
 export declare function readDomainsFromEmailAddresses(addresses: EmailAddress[]): EmailAddressDomain[];
+/**
+ * Extracts the domain portion from a single email address.
+ *
+ * @param address - The email address to extract the domain from
+ * @returns The lowercase domain string
+ */
 export declare function readDomainFromEmailAddress(address: EmailAddress): EmailAddressDomain;
 /**
- * Reads a domain from the input that can be formatted as
+ * Reads a domain from various input formats including URLs, email addresses, and raw domains.
  *
- * - A url: www.test.com,
+ * Supported formats:
+ * - A url: www.test.com
  * - A url with the protocol (://): https://www.test.com
  * - An email address: test@test.com
  * - A domain: test.com
  *
- * @param urlLikeInput
- * @returns The domain
+ * The "www." prefix is stripped from URL-style inputs since emails typically don't use it.
+ *
+ * @param urlLikeInput - A URL, email address, or domain string
+ * @returns The extracted domain
  */
 export declare function readEmailDomainFromUrlOrEmailAddress(urlLikeInput: string | EmailAddress | EmailAddressDomain): EmailAddressDomain;

package/src/lib/contact/random.d.ts

@@ -4,6 +4,9 @@ import { type EmailAddressDomain } from './domain';
 import { type EmailAddress } from './email';
 import { type Factory } from '../getter';
 import { type NumberFactory } from '../number/factory';
+/**
+ * Configuration for generating random email addresses.
+ */
 export interface RandomEmailFactoryConfig {
     /**
      * Set of email prefixes to use
@@ -18,9 +21,21 @@ export interface RandomEmailFactoryConfig {
      */
     numberFactory?: NumberFactory;
 }
+/**
+ * Default configuration that uses incrementing numbers and a test domain for safety in tests.
+ */
 export declare const DEFAULT_RANDOM_EMAIL_FACTORY_CONFIG: RandomEmailFactoryConfig;
 export type RandomEmailFactory = Factory<EmailAddress>;
+/**
+ * Creates a factory that generates random email addresses using configurable prefixes, domains, and number generators.
+ *
+ * @param inputConfig - Optional configuration overrides
+ * @returns A factory function that produces random email address strings
+ */
 export declare function randomEmailFactory(inputConfig?: RandomEmailFactoryConfig): RandomEmailFactory;
+/**
+ * Configuration for generating random E.164 phone numbers.
+ */
 export interface RandomPhoneNumberFactoryConfig {
     /**
      * Set of interntional numbers to use.
@@ -31,6 +46,15 @@ export interface RandomPhoneNumberFactoryConfig {
      */
     numberFactory?: NumberFactory;
 }
+/**
+ * Default configuration using US area codes and random 7-digit number generation.
+ */
 export declare const DEFAULT_RANDOM_PHONE_NUMBER_FACTORY_CONFIG: RandomPhoneNumberFactoryConfig;
 export type RandomPhoneNumberFactory = Factory<E164PhoneNumber>;
+/**
+ * Creates a factory that generates random E.164 phone numbers using configurable area codes and number generators.
+ *
+ * @param inputConfig - Optional configuration overrides
+ * @returns A factory function that produces random E.164 phone number strings
+ */
 export declare function randomPhoneNumberFactory(inputConfig?: RandomPhoneNumberFactoryConfig): RandomPhoneNumberFactory;

package/src/lib/date/date.d.ts

@@ -136,31 +136,26 @@ export declare const ISO8601_DAY_STRING_START_REGEX: RegExp;
  *
  * I.E. 2022-01-02T04:00:00.000Z in GMT-6 returns 2022-01-02
  *
- * @param date
- * @returns
+ * @param date - The date to get the start of day for
+ * @returns A new Date set to midnight UTC of the input date's UTC day
  */
 export declare function startOfDayForUTCDateInUTC(date: Date): Date;
 /**
- * Returns the system's date in UTC.
+ * Returns the start of the system's local date in UTC.
  *
  * I.E. 2022-01-02T04:00:00.000Z in GMT-6 (10PM Jan 1st CST) returns 2022-01-01
  *
- * @param date
- * @returns
+ * @param date - The date to get the start of local day for
+ * @returns A new Date set to midnight UTC of the input date's local day
  */
 export declare function startOfDayForSystemDateInUTC(date: Date): Date;
 /**
- * Parses a ISO8601DayString to a Date.
+ * Parses an ISO8601DayString (YYYY-MM-DD) to a UTC Date at midnight.
  *
- * @param inputDateString
- * @returns
+ * @param inputDateString - The ISO8601 day string to parse (e.g., '2022-01-15')
+ * @returns A Date object set to midnight UTC on the specified day
  */
 export declare function parseISO8601DayStringToUTCDate(inputDateString: ISO8601DayString): Date;
-/**
- * Returns true if the input date is strictly a
- * @param input
- * @returns
- */
 /**
  * Determines if a string is a valid ISO8601 day string (YYYY-MM-DD format).
  *

package/src/lib/date/hour.d.ts

@@ -13,28 +13,47 @@ import { type Hours, type Minutes } from './date';
  * - 15 minutes : 0.25
  */
 export type FractionalHour = number;
+/**
+ * Precision function that rounds fractional hour values to 3 decimal places.
+ */
 export declare const FRACTIONAL_HOURS_PRECISION_FUNCTION: import("..").CutValueToPrecisionFunction;
 /**
- * Converts the number of minnutes to a fractional hour.
+ * Converts the number of minutes to a fractional hour.
+ *
+ * Minutes are rounded down before conversion.
  *
- * Minutes are rounded down.
+ * @param minutes - Number of minutes to convert
+ * @returns The equivalent fractional hour value
  */
 export declare function minutesToFractionalHours(minutes: Minutes): FractionalHour;
 /**
- * Converts the fractional hour to a minute.
+ * Converts a fractional hour value to the equivalent number of minutes.
+ *
+ * @param hours - Fractional hour value to convert
+ * @returns The equivalent number of minutes (rounded)
  */
 export declare function fractionalHoursToMinutes(hours: FractionalHour): Minutes;
 /**
- * Rounds the input hour to the nearest FractionalHour.
+ * Rounds the input hour to the nearest FractionalHour precision (3 decimal places).
  *
- * @param hour
- * @returns
+ * @param hour - The hour value to round
+ * @returns The rounded fractional hour
  */
 export declare function hourToFractionalHour(hour: Hours): FractionalHour;
+/**
+ * Input for computing the next fractional hour by adding minutes and/or hours.
+ */
 export interface ComputeFractionalHour {
     readonly minutes?: Maybe<Minutes>;
     readonly hours?: Maybe<Hours>;
 }
+/**
+ * Computes the next fractional hour by adding the specified hours and minutes to the input value.
+ *
+ * @param input - The starting fractional hour value
+ * @param change - The hours and/or minutes to add
+ * @returns The resulting fractional hour
+ */
 export declare function computeNextFractionalHour(input: FractionalHour, change: ComputeFractionalHour): FractionalHour;
 /**
  * The minute of the day.
@@ -45,10 +64,10 @@ export type MinuteOfDay = number;
 export declare const MINUTE_OF_DAY_MINIUMUM = 0;
 export declare const MINUTE_OF_DAY_MAXMIMUM: number;
 /**
- * Returns true if the input valuer is a MinuteOfDay.
+ * Returns true if the input value is a valid MinuteOfDay (0-1439).
  *
- * @param input
- * @returns
+ * @param input - The number to validate
+ * @returns True if the input is within the valid MinuteOfDay range
  */
 export declare function isMinuteOfDay(input: number): input is MinuteOfDay;
 /**
@@ -61,57 +80,57 @@ export interface HoursAndMinutes {
 /**
  * Converts the input number of minutes to the equivalent in hours and minutes.
  *
- * @param inputMinutes
- * @returns
+ * @param inputMinutes - Total minutes to convert
+ * @returns An object with the hour and minute components
  */
 export declare function minutesToHoursAndMinutes(inputMinutes: Minutes): HoursAndMinutes;
 /**
- * Reads the hour and minutes of the Date.
+ * Reads the hour and minutes of the Date in the local timezone.
  *
- * @param date
- * @returns
+ * @param date - The date to extract hours and minutes from
+ * @returns An object with the hour and minute components
  */
 export declare function dateToHoursAndMinutes(date: Date): HoursAndMinutes;
 /**
  * Converts the input hours and minutes to a MinuteOfDay.
  *
- * @param hour
- * @param minute
- * @returns
+ * @param hour - The hour component (0-23)
+ * @param minute - The minute component (0-59)
+ * @returns The corresponding MinuteOfDay value
  */
 export declare function toMinuteOfDay(hour: Hours, minute: Minutes): MinuteOfDay;
 /**
- * Creates a new date from the minute of the day.
+ * Creates a new date with the time set to the given minute of the day.
  *
- * @param minuteOfDay
- * @param day
- * @returns
+ * @param minuteOfDay - The minute of the day (0-1439)
+ * @param day - Optional base date to use (defaults to the current date)
+ * @returns A Date with the time set to the specified minute of day
  */
 export declare function dateFromMinuteOfDay(minuteOfDay: Minutes | MinuteOfDay, day?: Date): Date;
 /**
- * Converts a Date to a MinuteOfDay.
+ * Converts a Date to a MinuteOfDay based on the local timezone.
  *
- * @param date
- * @returns
+ * @param date - The date to convert
+ * @returns The MinuteOfDay for the given date
  */
 export declare function dateToMinuteOfDay(date: Date): MinuteOfDay;
 /**
- * Converts the input minutes to a MinuteOfDay.
+ * Converts the input minutes to a valid MinuteOfDay by wrapping around the day boundary.
  *
- * @param minutes
- * @returns
+ * @param minutes - The minutes value to convert
+ * @returns A MinuteOfDay value (0-1439)
  */
 export declare function asMinuteOfDay(minutes: Minutes): MinuteOfDay;
 /**
- * Returns a string that represents the input hours and minutes.
+ * Returns a human-readable string that represents the input hours and minutes.
  *
  * Examples:
  * - {} -> ''
- * - { hour: 1, minute: 30 } -> "1 hour and 30 minutes"
- * - { hour: 1 } -> "1 hour"
+ * - { hour: 1, minute: 30 } -> "1 hours and 30 minutes"
+ * - { hour: 1 } -> "1 hours"
  * - { minute: 30 } -> "30 minutes"
  *
- * @param input
- * @returns
+ * @param input - The hours and minutes to format
+ * @returns A human-readable string representation
  */
 export declare function hoursAndMinutesToString(input: HoursAndMinutes): string;

package/src/lib/date/minute.d.ts

@@ -11,8 +11,8 @@ export interface MinutesAndSeconds {
  *
  * Rounds down to the nearest second.
  *
- * @param milliseconds
- * @returns
+ * @param milliseconds - The number of milliseconds to convert
+ * @returns An object with the minute and second components
  */
 export declare function millisecondsToMinutesAndSeconds(milliseconds: Milliseconds): MinutesAndSeconds;
 /**
@@ -25,7 +25,7 @@ export interface MinutesAndSeconds {
 /**
  * Converts the input number of seconds to the equivalent in minutes and seconds.
  *
- * @param inputSeconds
- * @returns
+ * @param inputSeconds - The number of seconds to convert
+ * @returns An object with the minute and second components
  */
 export declare function secondsToMinutesAndSeconds(inputSeconds: Seconds): MinutesAndSeconds;

package/src/lib/date/time.d.ts

@@ -19,6 +19,15 @@ export type TimePeriodCounter = (() => number) & {
      */
     readonly _reset: (start?: Date) => Date;
 };
+/**
+ * Creates a counter that tracks invocations within fixed time periods.
+ * Returns the number of invocations since the current period started.
+ * When a new period begins, the counter resets to 0.
+ *
+ * @param timePeriodLength - Length of each time period in milliseconds
+ * @param lastTimePeriodStart - Optional starting point for the first period
+ * @returns A callable counter function with metadata properties
+ */
 export declare function timePeriodCounter(timePeriodLength: number, lastTimePeriodStart?: Maybe<Date>): TimePeriodCounter;
 export type TimerState = 'running' | 'paused' | 'complete' | 'cancelled';
 /**
@@ -101,10 +110,10 @@ export declare class TimerCancelledError extends BaseError {
  */
 export declare function makeTimer(duration: Milliseconds, startImmediately?: boolean): Timer;
 /**
- * Toggles the input Timer's running state.
+ * Toggles the input Timer's running state between running and stopped.
  *
- * @param timer
- * @param toggleRun
+ * @param timer - The timer to toggle
+ * @param toggleRun - If provided, forces the timer to run (true) or stop (false). Otherwise toggles the current state.
  */
 export declare function toggleTimerRunning(timer: Timer, toggleRun?: boolean): void;
 /**

package/src/lib/date/week.d.ts

@@ -12,12 +12,12 @@ export type Saturday = 6;
  */
 export type DayOfWeek = Sunday | Monday | Tuesday | Wednesday | Thusrsday | Friday | Saturday | Sunday;
 /**
- * Returns the day of the week for the input day.
+ * Returns the day of the week for the input date.
  *
- * Equivalent to date.getDay()
+ * Equivalent to date.getDay().
  *
- * @param date
- * @returns
+ * @param date - The date to get the day of week for
+ * @returns The DayOfWeek value (0=Sunday through 6=Saturday)
  */
 export declare function dayOfWeek(date: Date): DayOfWeek;
 /**
@@ -25,10 +25,10 @@ export declare function dayOfWeek(date: Date): DayOfWeek;
  */
 export type IsInAllowedDaysOfWeekSetDecisionFunction = IsInSetDecisionFunction<Date | DayOfWeek, DayOfWeek>;
 /**
- * Creates a DecisionFunction that checks whether or not the input day or days of
+ * Creates a DecisionFunction that checks whether the input day or Date falls within the allowed days of the week.
  *
- * @param allowedDaysOfWeek
- * @returns
+ * @param allowedDaysOfWeek - Set of allowed DayOfWeek values
+ * @returns A decision function that checks membership in the allowed set
  */
 export declare function isInAllowedDaysOfWeekSet(allowedDaysOfWeek: Set<DayOfWeek>): IsInAllowedDaysOfWeekSetDecisionFunction;
 /**
@@ -36,7 +36,9 @@ export declare function isInAllowedDaysOfWeekSet(allowedDaysOfWeek: Set<DayOfWee
  *
  * Returns 7 days by default.
  *
- * @param startingOn
+ * @param startingOn - The day to start from (defaults to Sunday)
+ * @param maxDays - Maximum number of days to return (defaults to 7)
+ * @returns An array of DayOfWeek values
  */
 export declare function daysOfWeekArray(startingOn?: DayOfWeek, maxDays?: number): DayOfWeek[];
 /**
@@ -63,8 +65,23 @@ export interface EnabledDays {
     friday: boolean;
     saturday: boolean;
 }
+/**
+ * Creates an EnabledDays object from an iterable of Day enum values.
+ *
+ * @param input - Iterable of Day values to mark as enabled
+ * @returns An EnabledDays object with the specified days set to true
+ */
 export declare function enabledDaysFromDaysOfWeek(input: Maybe<Iterable<Day>>): EnabledDays;
+/**
+ * Converts an EnabledDays object to an array of Day enum values.
+ *
+ * @param input - The EnabledDays object to convert
+ * @returns An array of Day values for all enabled days
+ */
 export declare function daysOfWeekFromEnabledDays(input: Maybe<EnabledDays>): Day[];
+/**
+ * Configuration for transforming day-of-week name strings.
+ */
 export interface DayOfWeekNamesTransformConfig {
     /**
      * Whether or not to abbreviate the day names.
@@ -80,16 +97,66 @@ export interface DayOfWeekNamesTransformConfig {
     uppercase?: boolean;
 }
 /**
- * Returns an array of strinsg with each day of the week named.
+ * Returns an array of strings with each day of the week named.
  *
- * @returns
+ * @param sundayFirst - If true (default), Sunday is the first day; otherwise Monday is first
+ * @param transform - Optional configuration for abbreviation and casing
+ * @returns Array of day name strings
  */
 export declare function getDaysOfWeekNames(sundayFirst?: boolean, transform?: DayOfWeekNamesTransformConfig): string[];
+/**
+ * Creates a Map from DayOfWeek values to their string names.
+ *
+ * @param transform - Optional configuration for abbreviation and casing
+ * @returns A Map from DayOfWeek to name string
+ */
 export declare function daysOfWeekNameMap(transform?: DayOfWeekNamesTransformConfig): Map<DayOfWeek, string>;
+/**
+ * Function that returns the name string for a given DayOfWeek.
+ */
 export type DayOfWeekNameFunction = (dayOfWeek: DayOfWeek) => string;
+/**
+ * Creates a function that returns the name for a given DayOfWeek.
+ *
+ * @param transform - Optional configuration for abbreviation and casing
+ * @returns A function that maps DayOfWeek values to name strings
+ */
 export declare function daysOfWeekNameFunction(transform?: DayOfWeekNamesTransformConfig): DayOfWeekNameFunction;
+/**
+ * Returns the DayOfWeek for the day after the given day.
+ *
+ * @param day - The starting day
+ * @returns The next day of the week
+ */
 export declare function getDayTomorrow(day: DayOfWeek): DayOfWeek;
+/**
+ * Returns the DayOfWeek for the day before the given day.
+ *
+ * @param day - The starting day
+ * @returns The previous day of the week
+ */
 export declare function getDayYesterday(day: DayOfWeek): DayOfWeek;
+/**
+ * Returns the DayOfWeek offset by the given number of days (positive = forward, negative = backward).
+ *
+ * @param day - The starting day
+ * @param days - The number of days to offset (positive or negative)
+ * @returns The resulting DayOfWeek
+ */
 export declare function getDayOffset(day: DayOfWeek, days: number): DayOfWeek;
+/**
+ * Returns the DayOfWeek that is the given number of days before the input day.
+ *
+ * @param day - The starting day
+ * @param days - The number of days to go back (defaults to 1)
+ * @returns The resulting DayOfWeek
+ */
 export declare function getPreviousDay(day: DayOfWeek, days?: number): DayOfWeek;
+/**
+ * Returns the DayOfWeek that is the given number of days after the input day.
+ *
+ * @param day - The starting day
+ * @param days - The number of days to advance (defaults to 1)
+ * @returns The resulting DayOfWeek
+ */
 export declare function getNextDay(day: DayOfWeek, days?: number): DayOfWeek;

package/src/lib/error/error.d.ts

@@ -7,6 +7,9 @@ export type ThrowErrorFunction<T = unknown> = (error: T) => never | void;
  * A unique identifier for a specific error.
  */
 export type StringErrorCode = string;
+/**
+ * Default error code used when no specific code is provided.
+ */
 export declare const DEFAULT_READABLE_ERROR_CODE = "ERROR";
 /**
  * An error that is identified by a unique code.
@@ -24,25 +27,73 @@ export interface CodedError {
 export interface ReadableError extends Partial<CodedError> {
     readonly message?: Maybe<string>;
 }
+/**
+ * Checks if the error has the default error code or no code at all.
+ *
+ * @param error - A ReadableError or error code string to check
+ * @returns True if the error uses the default code or has no code
+ */
 export declare function isDefaultReadableError(error: Maybe<ReadableError | StringErrorCode>): boolean;
+/**
+ * A ReadableError that is guaranteed to have a code.
+ */
 export type ReadableErrorWithCode<T extends ReadableError = ReadableError> = T & CodedError;
+/**
+ * Creates a ReadableError with a code and optional message.
+ *
+ * @param code - The error code
+ * @param message - Optional human-readable error message
+ * @returns A ReadableErrorWithCode object
+ */
 export declare function readableError(code: StringErrorCode, message?: string): ReadableErrorWithCode;
+/**
+ * A ReadableError that includes additional data of type T.
+ */
 export interface ReadableDataError<T = unknown> extends ReadableError {
     readonly data?: T;
 }
+/**
+ * Wrapper around an error that contains the error data.
+ */
 export interface ErrorWrapper {
     readonly data: ReadableError | CodedError;
 }
+/**
+ * Union of all supported error input types for conversion functions.
+ */
 export type ErrorInput = ErrorWrapper | CodedError | ReadableError | ReadableDataError;
 /**
- * Converts the input error content to a ReadableError or CodedError.
+ * Converts various error input formats to a normalized ReadableErrorWithCode.
+ * Handles CodedError, ErrorWrapper, BaseError, and plain ReadableError inputs.
  *
- * @param inputError
- * @returns
+ * @param inputError - The error to convert
+ * @returns A normalized ReadableErrorWithCode
  */
 export declare function toReadableError(inputError: ErrorInput): CodedError | ReadableErrorWithCode;
 export declare function toReadableError(inputError: Maybe<ErrorInput>): Maybe<CodedError | ReadableErrorWithCode>;
+/**
+ * Checks if an error's message contains the target string.
+ *
+ * @param input - The error or string to check
+ * @param target - The string to search for in the error message
+ * @returns True if the error message contains the target string
+ */
 export declare function errorMessageContainsString(input: Maybe<ErrorInput | string>, target: string): boolean;
+/**
+ * Function that checks if an error's message contains a specific string.
+ */
 export type ErrorMessageContainsStringFunction = (input: Maybe<ErrorInput | string>) => boolean;
+/**
+ * Creates a function that checks if an error's message contains the target string.
+ *
+ * @param target - The string to search for
+ * @returns A function that checks error messages for the target string
+ */
 export declare function errorMessageContainsStringFunction(target: string): ErrorMessageContainsStringFunction;
+/**
+ * Extracts the message string from an error or returns the input if it's already a string.
+ *
+ * @param input - The error or string to extract a message from
+ * @returns The error message string, or null/undefined if not available
+ */
 export declare function messageFromError(input: Maybe<ErrorInput | string>): Maybe<string>;