@dereekb/util 13.11.14 → 13.11.15

package/src/lib/array/array.unique.d.ts

@@ -4,38 +4,38 @@ import { type DecisionFunction } from '../value/decision';
 /**
  * Concatenates multiple arrays and returns only unique values.
  *
+ * @param arrays - Arrays to concatenate. Null/undefined arrays are ignored.
+ * @returns Array containing only unique values from all input arrays.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, unique, concat, distinct, dedupe, deduplicate
  * @dbxUtilRelated unique, flatten-array-unique, concat-arrays
- *
- * @param arrays - Arrays to concatenate. Null/undefined arrays are ignored.
- * @returns Array containing only unique values from all input arrays.
  */
 export declare function concatArraysUnique<T extends PrimativeKey = PrimativeKey>(...arrays: Maybe<T[]>[]): T[];
 /**
  * Flattens a 2D array and returns only unique values.
  *
+ * @param array - Two-dimensional array to flatten and deduplicate.
+ * @returns Array containing only unique values from the flattened input.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, flatten, unique, distinct, dedupe, nested
  * @dbxUtilRelated unique, concat-arrays-unique, flatten-array
- *
- * @param array - Two-dimensional array to flatten and deduplicate.
- * @returns Array containing only unique values from the flattened input.
  */
 export declare function flattenArrayUnique<T extends PrimativeKey = PrimativeKey>(array: T[][]): T[];
 /**
  * Filters the input values and only returns unique values.
  *
+ * @param values - Array of primitive-key values to deduplicate.
+ * @param excludeInput - Optional keys or values to exclude from the result.
+ * @returns Array containing only unique values with exclusions removed.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilTags array, unique, distinct, dedupe, deduplicate, set
  * @dbxUtilRelated filter-unique-values, filter-unique-function, concat-arrays-unique
- *
- * @param values - Array of primitive-key values to deduplicate.
- * @param excludeInput - Optional keys or values to exclude from the result.
- * @returns Array containing only unique values with exclusions removed.
  */
 export declare function unique<T extends PrimativeKey = PrimativeKey>(values: T[], excludeInput?: FilterUniqueFunctionExcludeKeysInput<T, T>): T[];
 /**
@@ -78,30 +78,31 @@ export declare function readKeysFromFilterUniqueFunctionAdditionalKeys<T, K exte
 /**
  * Creates a {@link FilterUniqueFunction} that deduplicates items by their computed key.
  *
+ * @param readKey - Function to extract a unique key from each item.
+ * @param additionalKeysInput - Optional keys or values to pre-seed as already seen, causing them to be excluded.
+ * @returns A reusable filter function that removes duplicate items from arrays.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilKind factory
  * @dbxUtilTags array, unique, distinct, dedupe, factory, key, filter
  * @dbxUtilRelated filter-unique-values, unique, allow-value-once-filter
  *
- * @param readKey - Function to extract a unique key from each item.
- * @param additionalKeysInput - Optional keys or values to pre-seed as already seen, causing them to be excluded.
- * @returns A reusable filter function that removes duplicate items from arrays.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function filterUniqueFunction<T, K extends PrimativeKey = PrimativeKey>(readKey: ReadKeyFunction<T, K>, additionalKeysInput?: FilterUniqueFunctionAdditionalKeysInput<T, K>): FilterUniqueFunction<T, K>;
 /**
  * Filters an array to contain only items with unique keys.
  *
- * @dbxUtil
- * @dbxUtilCategory array
- * @dbxUtilTags array, unique, filter, dedupe, key, distinct
- * @dbxUtilRelated filter-unique-function, unique, is-unique-keyed-function
- *
  * @param values - Array of items to deduplicate.
  * @param readKey - Function to extract a unique key from each item.
  * @param additionalKeys - Optional keys to pre-seed as already seen, excluding matching items.
  * @returns Array containing only the first occurrence of each uniquely-keyed item.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory array
+ * @dbxUtilTags array, unique, filter, dedupe, key, distinct
+ * @dbxUtilRelated filter-unique-function, unique, is-unique-keyed-function
  */
 export declare function filterUniqueValues<T, K extends PrimativeKey = PrimativeKey>(values: T[], readKey: ReadKeyFunction<T, K>, additionalKeys?: K[]): T[];
 /**
@@ -111,14 +112,15 @@ export type IsUniqueKeyedFunction<T> = DecisionFunction<T[]>;
 /**
  * Creates an {@link IsUniqueKeyedFunction} that checks whether all items in an array have unique keys.
  *
+ * @param readKey - Function to extract a unique key from each item.
+ * @returns A decision function that returns true if all items have distinct keys.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilKind factory
  * @dbxUtilTags array, unique, validation, distinct, key, decision, factory
  * @dbxUtilRelated filter-unique-function, unique
  *
- * @param readKey - Function to extract a unique key from each item.
- * @returns A decision function that returns true if all items have distinct keys.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function isUniqueKeyedFunction<T, K extends PrimativeKey = PrimativeKey>(readKey: ReadKeyFunction<T, K>): IsUniqueKeyedFunction<T>;

package/src/lib/array/array.value.d.ts

@@ -10,14 +10,15 @@ export type UniversalFilterMaybeArrayFunction = <T>(values: Maybe<Maybe<T>[]>) =
 /**
  * Creates a {@link FilterMaybeArrayFunction} that filters maybe values from an array using the provided filter function.
  *
+ * @param filterFn - Filter predicate used to determine which values to keep.
+ * @returns Reusable filter operator that drops nullish entries and applies the predicate to the rest.
+ *
  * @dbxUtil
  * @dbxUtilCategory array
  * @dbxUtilKind factory
  * @dbxUtilTags array, filter, maybe, factory, predicate
  * @dbxUtilRelated filter-maybe-array-values
  *
- * @param filterFn - Filter predicate used to determine which values to keep.
- * @returns A function that filters maybe values from an optional input array.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function filterMaybeArrayFunction<T>(filterFn: Parameters<Array<Maybe<T>>['filter']>[0]): FilterMaybeArrayFunction<T>;

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

@@ -37,13 +37,13 @@ export declare class AssertionError extends BaseError implements ReadableError {
     /**
      * Gets the target object that failed the assertion.
      *
-     * @returns The target object
+     * @returns The target object.
      */
     get target(): object;
     /**
      * Gets the property key that failed the assertion.
      *
-     * @returns The property key as a string
+     * @returns The property key as a string.
      */
     get propertyKey(): string;
 }
@@ -54,23 +54,23 @@ export declare class AssertionIssueHandler {
     /**
      * Handles an assertion issue by throwing an appropriate exception.
      *
-     * @param error - The assertion issue to handle
-     * @throws AssertionError
+     * @param error - The assertion issue to handle.
+     * @throws {AssertionError} Always — wraps the issue and rethrows it.
      */
     handle(error: AssertionIssue): void;
     /**
      * Builds an AssertionError from an AssertionIssue.
      *
-     * @param error - The assertion issue to build an exception from
-     * @returns A new AssertionError instance
+     * @param error - The assertion issue to build an exception from.
+     * @returns A new AssertionError instance.
      */
     buildException(error: AssertionIssue): AssertionError;
     /**
      * Builds an error message string from an AssertionIssue.
      * Uses the custom message if provided, otherwise creates a default message.
      *
-     * @param error - The assertion issue to build a message for
-     * @returns The error message string
+     * @param error - The assertion issue to build a message for.
+     * @returns The error message string.
      */
     protected buildExceptionString(error: AssertionIssue): string;
 }

package/src/lib/assertion/assertion.d.ts

@@ -29,18 +29,18 @@ export declare class PropertyDescriptorUtility {
      * Creates a property descriptor interceptor that validates values using an assertion function
      * before allowing them to be set. Optionally maps the value after validation.
      *
-     * @param assertValueFn - Function that returns true if the value is valid
+     * @param assertValueFn - Function that returns true if the value is valid.
      * @param options - Custom assertion options (message, map function)
-     * @param defaultOptions - Default options merged under the custom options
-     * @returns A property descriptor interceptor function
+     * @param defaultOptions - Default options merged under the custom options.
+     * @returns A property descriptor interceptor function.
      */
     static makePropertyDescriptorAssertion<T>(assertValueFn: AccessorValueAssertion<T>, options?: MapDescriptorAssertionOptions<T>, defaultOptions?: MapDescriptorAssertionOptions<T>): (target: object, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) => void;
     /**
      * Creates a low-level property descriptor interceptor that replaces the setter
      * of a property with a custom function produced by the given factory.
      *
-     * @param makeSetValueInterceptorFn - Factory that produces the replacement setter function
-     * @returns A property descriptor interceptor function
+     * @param makeSetValueInterceptorFn - Factory that produces the replacement setter function.
+     * @returns A property descriptor interceptor function.
      */
     static makeSetPropertyDescriptorInterceptor<T>(makeSetValueInterceptorFn: SetValueInterceptorFunctionFactory<T>): (target: object, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) => void;
 }

package/src/lib/assertion/assertion.generic.d.ts

@@ -4,8 +4,8 @@ import { type AccessorValueAssertion } from './assertion';
  * Creates a property decorator that validates values using a custom assertion function
  * before allowing them to be set on the property.
  *
- * @param assertion - Function that returns true if the value is valid
- * @param options - Optional assertion options including custom error message and value mapping
- * @returns A property descriptor interceptor that enforces the assertion on the setter
+ * @param assertion - Function that returns true if the value is valid.
+ * @param options - Optional assertion options including custom error message and value mapping.
+ * @returns A property descriptor interceptor that enforces the assertion on the setter.
  */
 export declare function Assert<T>(assertion: AccessorValueAssertion<T>, options?: MapDescriptorAssertionOptions<T>): (target: object, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) => void;

package/src/lib/assertion/assertion.number.d.ts

@@ -3,17 +3,17 @@ import { type DescriptorAssertionOptions } from './assert';
  * Creates a property decorator that asserts the numeric value is greater than or equal to a minimum.
  *
  * @param min - The minimum allowed value (inclusive)
- * @param options - Optional assertion options including custom error message
- * @returns A property descriptor interceptor that enforces the minimum value constraint
- * @throws {@link AssertionError} when the assigned value is less than `min`
+ * @param options - Optional assertion options including custom error message.
+ * @returns A property descriptor interceptor that enforces the minimum value constraint.
+ * @throws {@link AssertionError} When the assigned value is less than `min`
  */
 export declare function AssertMin(min: number, options?: DescriptorAssertionOptions): (target: object, propertyKey: string, descriptor: TypedPropertyDescriptor<number>) => void;
 /**
  * Creates a property decorator that asserts the numeric value is less than or equal to a maximum.
  *
  * @param max - The maximum allowed value (inclusive)
- * @param options - Optional assertion options including custom error message
- * @returns A property descriptor interceptor that enforces the maximum value constraint
- * @throws {@link AssertionError} when the assigned value is greater than `max`
+ * @param options - Optional assertion options including custom error message.
+ * @returns A property descriptor interceptor that enforces the maximum value constraint.
+ * @throws {@link AssertionError} When the assigned value is greater than `max`
  */
 export declare function AssertMax(max: number, options?: DescriptorAssertionOptions): (target: object, propertyKey: string, descriptor: TypedPropertyDescriptor<number>) => void;

package/src/lib/auth/auth.role.claims.d.ts

@@ -84,11 +84,11 @@ export interface AuthRoleClaimsFactoryConfigEntryEncodeOptions<V extends AuthCla
      *
      * If not defined, will defer to role for finding matches and pull from value.
      */
-    encodeValueFromRoles: (roles: AuthRoleSet) => V | undefined;
+    encodeValueFromRoles: (roles: AuthRoleSet) => Maybe<V>;
     /**
      * (Optional) Auth roles associated with this claims. If not defined, the claims key is used.
      */
-    decodeRolesFromValue: (value: Maybe<V>) => AuthRole[] | undefined;
+    decodeRolesFromValue: (value: Maybe<V>) => Maybe<AuthRole[]>;
 }
 export type IgnoreAuthRoleClaimsEntry = null;
 export type AuthRoleClaimsFactoryConfig<T extends AuthClaimsObject = AuthClaimsObject> = {
@@ -98,13 +98,13 @@ export interface AuthRoleClaimsFactoryDefaults {
     /**
      * Default value to use for claims that have no value present.
      *
-     * If undefined, defaults to AUTH_ROLE_CLAIMS_DEFAULT_CLAIM_VALUE.
+     * If undefined, defaults to DEFAULT_AUTH_ROLE_CLAIMS_CLAIM_VALUE.
      */
     claimValue?: AuthClaimValue;
     /**
      * Default value for claims that are not defined.
      *
-     * If undefined, defaults to AUTH_ROLE_CLAIMS_DEFAULT_EMPTY_VALUE.
+     * If undefined, defaults to DEFAULT_AUTH_ROLE_CLAIMS_EMPTY_VALUE.
      */
     emptyValue?: AuthClaimValue | ClearAuthClaimValue;
 }
@@ -142,23 +142,24 @@ export interface AuthRoleClaimsService<T extends AuthClaimsObject> {
     readonly defaultClaimValue: unknown;
     readonly defaultEmptyValue: unknown;
 }
-export declare const AUTH_ROLE_CLAIMS_DEFAULT_CLAIM_VALUE = 1;
-export declare const AUTH_ROLE_CLAIMS_DEFAULT_EMPTY_VALUE: null;
+export declare const DEFAULT_AUTH_ROLE_CLAIMS_CLAIM_VALUE = 1;
+export declare const DEFAULT_AUTH_ROLE_CLAIMS_EMPTY_VALUE: null;
 /**
  * Creates an {@link AuthRoleClaimsService} that converts between {@link AuthRoleSet} and JWT-style claims objects.
  *
  * Each key in the config maps a claim key to role(s). Simple entries map a claim value to one or more roles,
  * while encode/decode entries allow custom bidirectional conversion logic.
  *
+ * @param config - Mapping of claim keys to their role configuration entries (or null to ignore)
+ * @param defaults - Optional default values for claim presence and absence.
+ * @returns A service with `toClaims` and `toRoles` conversion functions.
+ *
  * @dbxUtil
  * @dbxUtilCategory auth
  * @dbxUtilKind factory
  * @dbxUtilTags auth, role, claims, jwt, factory, bidirectional
  * @dbxUtilRelated auth-role
  *
- * @param config - Mapping of claim keys to their role configuration entries (or null to ignore)
- * @param defaults - Optional default values for claim presence and absence
- * @returns A service with `toClaims` and `toRoles` conversion functions
  * @__NO_SIDE_EFFECTS__
  */
 export declare function authRoleClaimsService<T extends AuthClaimsObject>(config: AuthRoleClaimsFactoryConfig<T>, defaults?: AuthRoleClaimsFactoryDefaults): AuthRoleClaimsService<T>;
@@ -168,7 +169,7 @@ export declare function authRoleClaimsService<T extends AuthClaimsObject>(config
  * Useful for cleaning up a claims update before persisting or comparing, since update objects
  * use `null` to indicate claim removal.
  *
- * @param authClaimsUpdate - The claims update object potentially containing null values
- * @returns A clean claims object with all null entries removed
+ * @param authClaimsUpdate - The claims update object potentially containing null values.
+ * @returns A clean claims object with all null entries removed.
  */
 export declare function authClaims<T extends AuthClaimsObject = AuthClaimsObject>(authClaimsUpdate: AuthClaimsUpdate<T>): AuthClaims<T>;

package/src/lib/auth/auth.role.d.ts

@@ -35,8 +35,8 @@ export declare const AUTH_USER_ROLE = "user";
 /**
  * Checks if an AuthRoleSet contains all of the specified roles.
  *
- * @param authRolesSet - The set of auth roles to check against
- * @param roles - An iterable of roles to check for, or null/undefined
- * @returns True if the authRolesSet contains all the specified roles, or if roles is empty/null
+ * @param authRolesSet - Granted roles that must satisfy the required-roles check.
+ * @param roles - Roles that must all be present; nullish or empty is treated as vacuously true.
+ * @returns True when every required role appears in the granted set; otherwise false.
  */
 export declare function authRolesSetHasRoles(authRolesSet: AuthRoleSet, roles: Maybe<Iterable<AuthRole>>): boolean;

package/src/lib/auth/pkce.d.ts

@@ -7,7 +7,7 @@ export declare function generatePkceCodeVerifier(): string;
 /**
  * Generates a PKCE code challenge from a code verifier using SHA-256.
  *
- * @param verifier - The code verifier string to hash
- * @returns A base64url-encoded SHA-256 hash of the verifier
+ * @param verifier - The code verifier string to hash.
+ * @returns A base64url-encoded SHA-256 hash of the verifier.
  */
 export declare function generatePkceCodeChallenge(verifier: string): Promise<string>;

package/src/lib/boolean.d.ts

@@ -56,22 +56,22 @@ export declare function reduceBooleansWithAnd(array: boolean[], emptyArrayValue?
 /**
  * Reduces an array of booleans with the logical OR operation.
  *
- * @dbxUtil
- * @dbxUtilCategory boolean
- * @dbxUtilTags boolean, reduce, or, some, any, disjunction, aggregate
- * @dbxUtilRelated reduce-booleans-with-and, reduce-booleans-with-or-fn
- *
  * @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.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory boolean
+ * @dbxUtilTags boolean, reduce, or, some, any, disjunction, aggregate
+ * @dbxUtilRelated reduce-booleans-with-and, reduce-booleans-with-or-fn
  */
 export declare function reduceBooleansWithOr(array: boolean[], emptyArrayValue?: boolean): boolean;
 /**
  * Creates a function that reduces an array of booleans with the logical AND operation.
  *
  * @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.
+ * @returns Reducer that yields true only when every entry is truthy (or the fallback for empty input).
  *
  * @example
  * ```ts
@@ -86,7 +86,7 @@ export declare function reduceBooleansWithAndFn(emptyArrayValue?: boolean): (arr
  * Creates a function that reduces an array of booleans with the logical OR operation.
  *
  * @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.
+ * @returns Reducer that yields true when any entry is truthy (or the fallback for empty input).
  *
  * @example
  * ```ts
@@ -102,7 +102,7 @@ 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.
+ * @returns Reducer that folds the array with `reduceFn`, falling back to `emptyArrayValue` when empty.
  *
  * @example
  * ```ts
@@ -160,13 +160,13 @@ export declare function booleanFactory(config: BooleanFactoryConfig): BooleanFac
 /**
  * Returns a random boolean based on the specified chance.
  *
+ * @param chance - Number between 0.0 and 100.0 representing the percentage chance of returning true (default: 50, i.e., 50%).
+ * @returns A random boolean value with the specified probability of being true.
+ *
  * @dbxUtil
  * @dbxUtilCategory boolean
  * @dbxUtilTags boolean, random, chance, probability, coin-flip
  * @dbxUtilRelated boolean-factory
- *
- * @param chance - Number between 0.0 and 100.0 representing the percentage chance of returning true (default: 50, i.e., 50%).
- * @returns A random boolean value with the specified probability of being true.
  */
 export declare function randomBoolean(chance?: BooleanTrueChance): boolean;
 /**

package/src/lib/cache/cache.memoize.d.ts

@@ -10,14 +10,14 @@ import { type AsyncKeyedValueCache, type AsyncValueCache } from './cache';
  * Note: the memoized value is per-process. Long-running processes will not observe writes
  * made by other processes to the inner backing once the memo is populated.
  *
+ * @param inner - The backing cache to memoize. Reads are delegated once and cached; writes are forwarded through and refresh the memo.
+ * @returns An {@link AsyncValueCache} that proxies the inner cache with a single-load memoization layer.
+ *
  * @dbxUtil
  * @dbxUtilCategory cache
  * @dbxUtilTags memoize, memo, cache, async, single-load, async-value
  * @dbxUtilRelated memoize-async-keyed-value-cache
  *
- * @param inner - The backing cache to memoize. Reads are delegated once and cached; writes are forwarded through and refresh the memo.
- * @returns An {@link AsyncValueCache} that proxies the inner cache with a single-load memoization layer.
- *
  * @example
  * ```ts
  * const memo = memoizeAsyncValueCache(inMemoryAsyncValueCache<string>('initial'));
@@ -40,14 +40,14 @@ export declare function memoizeAsyncValueCache<T>(inner: AsyncValueCache<T>): As
  * Note: the memoized record is per-process. Long-running processes will not observe writes
  * made by other processes to the inner backing once the memo is populated.
  *
+ * @param inner - The backing keyed cache to memoize. The full record is loaded once and cached; writes are forwarded through and applied to the memo.
+ * @returns An {@link AsyncKeyedValueCache} that proxies the inner cache with a record-level memoization layer.
+ *
  * @dbxUtil
  * @dbxUtilCategory cache
  * @dbxUtilTags memoize, memo, cache, async, keyed, record
  * @dbxUtilRelated memoize-async-value-cache
  *
- * @param inner - The backing keyed cache to memoize. The full record is loaded once and cached; writes are forwarded through and applied to the memo.
- * @returns An {@link AsyncKeyedValueCache} that proxies the inner cache with a record-level memoization layer.
- *
  * @example
  * ```ts
  * const memo = memoizeAsyncKeyedValueCache(inMemoryAsyncKeyedValueCache<number>({ a: 1 }));

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

@@ -11,25 +11,25 @@ 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.
+ *
  * @dbxUtil
  * @dbxUtilCategory contact
  * @dbxUtilTags email, domain, extract, unique, dedupe, case-insensitive
  * @dbxUtilRelated read-domain-from-email-address, read-email-domain-from-url-or-email-address
- *
- * @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.
+ *
  * @dbxUtil
  * @dbxUtilCategory contact
  * @dbxUtilTags email, domain, extract, parse, lowercase
  * @dbxUtilRelated read-domains-from-email-addresses, read-email-domain-from-url-or-email-address
- *
- * @param address - The email address to extract the domain from
- * @returns The lowercase domain string
  */
 export declare function readDomainFromEmailAddress(address: EmailAddress): EmailAddressDomain;
 /**
@@ -43,12 +43,12 @@ export declare function readDomainFromEmailAddress(address: EmailAddress): Email
  *
  * 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.
+ *
  * @dbxUtil
  * @dbxUtilCategory contact
  * @dbxUtilTags email, domain, url, extract, normalize, parse, www
  * @dbxUtilRelated read-domain-from-email-address, read-domains-from-email-addresses
- *
- * @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/email.d.ts

@@ -32,41 +32,41 @@ export type EmailParticipantString = string;
  * Converts an EmailParticipant object to a formatted string representation.
  * The format is: "name<email>" or "<email>" if no name is provided.
  *
+ * @param participant - The email participant to convert.
+ * @returns A formatted string representation of the participant.
+ *
  * @dbxUtil
  * @dbxUtilCategory contact
  * @dbxUtilTags email, participant, convert, format, serialize, name
  * @dbxUtilRelated convert-email-participant-string-to-participant, coerce-to-email-participants
- *
- * @param participant - The email participant to convert
- * @returns A formatted string representation of the participant
  */
 export declare function convertParticipantToEmailParticipantString(participant: EmailParticipant): EmailParticipantString;
 /**
  * Converts a formatted participant string into an EmailParticipant object.
  * Parses strings in the format "name<email>" or "<email>".
  *
+ * @param participantString - Serialized participant in `name<email>` or `<email>` form.
+ * @returns Parsed participant pairing the optional display name with the extracted address.
+ *
  * @dbxUtil
  * @dbxUtilCategory contact
  * @dbxUtilTags email, participant, parse, deserialize, name, address
  * @dbxUtilRelated convert-participant-to-email-participant-string, coerce-to-email-participants
- *
- * @param participantString - The string to parse
- * @returns An EmailParticipant object with the extracted name and email
  */
 export declare function convertEmailParticipantStringToParticipant(participantString: EmailParticipantString): EmailParticipant;
 /**
  * Combines an array of EmailParticipants with an array of email addresses.
  * Email addresses that don't already exist in the participants array are converted to EmailParticipant objects.
  *
+ * @param options - Object containing participants and/or emails arrays.
+ * @param options.participants - Array of existing EmailParticipant objects.
+ * @param options.emails - Array of email addresses to include.
+ * @returns A combined array of EmailParticipant objects.
+ *
  * @dbxUtil
  * @dbxUtilCategory contact
  * @dbxUtilTags email, participant, merge, combine, dedupe, coerce, normalize
  * @dbxUtilRelated convert-participant-to-email-participant-string, convert-email-participant-string-to-participant
- *
- * @param options - Object containing participants and/or emails arrays
- * @param options.participants - Array of existing EmailParticipant objects
- * @param options.emails - Array of email addresses to include
- * @returns A combined array of EmailParticipant objects
  */
 export declare function coerceToEmailParticipants({ participants, emails }: {
     participants?: EmailParticipant[];

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

@@ -43,9 +43,9 @@ export declare const E164PHONE_NUMBER_REGEX: RegExp;
 /**
  * Validates if the input string is a valid E.164 phone number.
  *
- * @param input - The phone number string to validate
- * @param allowExtension - If true, allows an extension in the format +number#extension
- * @returns True if the input is a valid E.164 phone number
+ * @param input - The phone number string to validate.
+ * @param allowExtension - If true, allows an extension in the format +number#extension.
+ * @returns True if the input is a valid E.164 phone number.
  */
 export declare function isE164PhoneNumber(input: string, allowExtension?: boolean): input is E164PhoneNumber;
 /**
@@ -78,8 +78,8 @@ export declare const E164PHONE_NUMBER_WITH_EXTENSION_REGEX: RegExp;
  * Validates if the input string is a valid E.164 phone number with an extension.
  * The phone number must be in the format +number#extension.
  *
- * @param input - The phone number string to validate
- * @returns True if the input is a valid E.164 phone number with extension
+ * @param input - The phone number string to validate.
+ * @returns True if the input is a valid E.164 phone number with extension.
  */
 export declare function isE164PhoneNumberWithExtension(input: string): input is E164PhoneNumberWithExtension;
 /**
@@ -91,8 +91,8 @@ export declare const PHONE_EXTENSION_NUMBER_REGEX: RegExp;
  * Validates if the input string is a valid phone extension number.
  * Valid extensions are 1-6 digits with no other characters.
  *
- * @param input - The extension string to validate
- * @returns True if the input is a valid phone extension number
+ * @param input - The extension string to validate.
+ * @returns True if the input is a valid phone extension number.
  */
 export declare function isValidPhoneExtensionNumber(input: string): input is PhoneExtensionNumber;
 /**
@@ -114,16 +114,16 @@ export interface E164PhoneNumberExtensionPair {
  * Splits a phone number into its main number and extension components.
  * If the input contains a # character, everything before is the number and everything after is the extension.
  *
- * @param input - The phone number string to split
- * @returns An object containing the number and optional extension
+ * @param input - The phone number string to split.
+ * @returns An object containing the number and optional extension.
  */
 export declare function e164PhoneNumberExtensionPair(input: PhoneNumber | E164PhoneNumberWithOptionalExtension): E164PhoneNumberExtensionPair;
 /**
  * Combines a phone number and optional extension into a single string.
  * If an extension is provided, it will be appended with a # separator.
  *
- * @param input - An object containing the phone number and optional extension
- * @returns A formatted phone number string with optional extension
+ * @param input - An object containing the phone number and optional extension.
+ * @returns A formatted phone number string with optional extension.
  */
 export declare function e164PhoneNumberFromE164PhoneNumberExtensionPair(input: E164PhoneNumberExtensionPair): E164PhoneNumberWithOptionalExtension;
 /**
@@ -135,7 +135,7 @@ export declare function e164PhoneNumberFromE164PhoneNumberExtensionPair(input: E
  *
  * @param input - A raw phone number string, possibly with formatting (e.g. `'(720)6620850'`, `'720-662-0850'`)
  * @param defaultCountryCode - The country calling code to prepend if the number lacks one (default: `'1'` for US/Canada)
- * @returns The corrected {@link E164PhoneNumber}, or `undefined` if the input cannot be converted
+ * @returns The corrected {@link E164PhoneNumber}, or `undefined` if the input cannot be converted.
  *
  * @example
  * ```typescript