@dereekb/util 11.1.8 → 12.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/util",
-  "version": "11.1.8",
+  "version": "12.0.0",
   "exports": {
     ".": {
       "types": "./src/index.d.ts",
@@ -40,5 +40,6 @@
   },
   "dependencies": {},
   "module": "./index.esm.js",
-  "main": "./index.cjs.js"
-}
+  "main": "./index.cjs.js",
+  "types": "./index.esm.d.ts"
+}

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

@@ -1,5 +1,8 @@
 import { type ReadModelKeyFunction } from '../model/model';
 import { type Maybe } from '../value/maybe.type';
+/**
+ * A string type used as a key in boolean arrays.
+ */
 export type BooleanStringKey = string;
 /**
  * Boolean represented by an array to describe the current state and reason why.
@@ -11,13 +14,57 @@ export type BooleanStringKeyArray = BooleanKeyArray<BooleanStringKey>;
  * Having any values in the array is considered "true".
  */
 export type BooleanKeyArray<T = string> = Maybe<T[]>;
+/**
+ * Wraps a key reading function to ensure that empty string keys are not used in boolean key arrays.
+ * @param readKey - The key reading function to wrap
+ * @returns A wrapped key reading function that throws an error if an empty string is used as a key
+ */
 export declare function readBooleanKeySafetyWrap<T>(readKey: ReadModelKeyFunction<T>): ReadModelKeyFunction<T>;
+/**
+ * Checks if a boolean key array evaluates to false (empty or undefined).
+ * @param value - The boolean key array to check
+ * @returns True if the array is empty or undefined, false otherwise
+ */
 export declare function isFalseBooleanKeyArray(value: BooleanKeyArray): boolean;
+/**
+ * Checks if a boolean key array evaluates to true (has at least one value).
+ * @param value - The boolean key array to check
+ * @returns True if the array has at least one value, false otherwise
+ */
 export declare function isTrueBooleanKeyArray(value: BooleanKeyArray): boolean;
+/**
+ * Inserts a value into a boolean key array, removing any existing values with the same key.
+ * @param array - The boolean key array to insert into
+ * @param value - The value to insert
+ * @param readKey - Function to extract the key from a value
+ * @returns A new boolean key array with the value inserted
+ */
 export declare function insertIntoBooleanKeyArray<T>(array: BooleanKeyArray<T>, value: T, readKey: ReadModelKeyFunction<T>): BooleanKeyArray<T>;
+/**
+ * Removes a value from a boolean key array based on its key.
+ * @param array - The boolean key array to remove from
+ * @param value - The value to remove
+ * @param readKey - Function to extract the key from a value
+ * @returns A new boolean key array with the value removed
+ */
 export declare function removeFromBooleanKeyArray<T>(array: BooleanKeyArray<T>, value: T, readKey: ReadModelKeyFunction<T>): BooleanKeyArray<T>;
+/**
+ * Removes values from a boolean key array that match the specified key.
+ * @param array - The boolean key array to remove from
+ * @param key - The key to match for removal
+ * @param readKey - Function to extract the key from a value
+ * @returns A new boolean key array with matching values removed
+ */
 export declare function removeByKeyFromBooleanKeyArray<T>(array: BooleanKeyArray<T>, key: string, readKey: ReadModelKeyFunction<T>): BooleanKeyArray<T>;
+/**
+ * Utility type for working with boolean key arrays.
+ */
 export type BooleanKeyArrayUtility<T> = ReturnType<typeof booleanKeyArrayUtility<T>>;
+/**
+ * Creates a utility object with functions for working with boolean key arrays.
+ * @param readKey - Function to extract the key from a value
+ * @returns An object with utility functions for boolean key arrays
+ */
 export declare function booleanKeyArrayUtility<T>(readKey: ReadModelKeyFunction<T>): {
     isFalse: (value: BooleanKeyArray) => boolean;
     isTrue: (value: BooleanKeyArray) => boolean;
@@ -26,6 +73,9 @@ export declare function booleanKeyArrayUtility<T>(readKey: ReadModelKeyFunction<
     remove: (array: BooleanKeyArray<T>, value: T) => BooleanKeyArray<T>;
     removeByKey: (array: BooleanKeyArray<T>, key: string) => BooleanKeyArray<T>;
 };
+/**
+ * Utility for working with boolean string key arrays.
+ */
 export declare const BooleanStringKeyArrayUtility: {
     isFalse: (value: BooleanKeyArray) => boolean;
     isTrue: (value: BooleanKeyArray) => boolean;

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

@@ -2,47 +2,50 @@ import { type Factory, type FactoryWithIndex, type FactoryWithRequiredInput } fr
 import { type AsyncMapFunction } from '../value/map';
 /**
  * Factory that generates multiple values given a number of items to make.
+ * Takes a count parameter and returns an array of generated items.
  */
 export type ArrayFactory<T> = FactoryWithRequiredInput<T[], number>;
 /**
- * Async ArrayFactory
+ * Async version of ArrayFactory that returns a promise resolving to an array of items.
  */
 export type AsyncArrayFactory<T> = AsyncMapFunction<ArrayFactory<T>>;
 /**
  * Factory that generates a value for each input value.
+ * Takes an array of input values and returns an array of output values.
  */
 export type ArrayInputFactory<I, O> = FactoryWithRequiredInput<O[], I[]>;
 /**
- * Async ArrayInputFactory
+ * Async version of ArrayInputFactory that returns a promise resolving to an array of output values.
  */
 export type AsyncArrayInputFactory<I, O> = AsyncMapFunction<ArrayInputFactory<I, O>>;
 /**
- * Creates a new ArrayFactory.
+ * Creates a new ArrayFactory that generates multiple values.
  *
- * @param factory
- * @returns
+ * @param factory - The factory function used to generate each item
+ * @returns A function that takes a count parameter and returns an array of generated items
  */
 export declare function arrayFactory<T>(factory: Factory<T> | FactoryWithIndex<T>): ArrayFactory<T>;
 /**
- * Creates a ArrayInputFactory.
+ * Creates an ArrayInputFactory that transforms input values into output values.
  *
- * @param factory
- * @returns
+ * @param factory - The factory function used to transform each input value
+ * @returns A function that takes an array of input values and returns an array of output values
  */
 export declare function arrayInputFactory<O, I>(factory: FactoryWithRequiredInput<O, I>): ArrayInputFactory<I, O>;
 /**
  * Creates a factory that returns the items from the input array and returns null after the factory function has exhausted all array values.
  *
- * The factory can only be used once.
+ * The factory can only be used once as it maintains internal state.
  *
- * @param array
+ * @param array - The source array to pull values from
+ * @returns A factory function that returns items from the array or null when exhausted
  */
 export declare function terminatingFactoryFromArray<T>(array: T[]): Factory<T | null>;
 /**
+ * Creates a factory that returns the items from the input array and returns the specified terminating value when the array is exhausted.
  *
- * Creates a factory that returns the items from the input array and returns the terminating value if the input array is empty.
- *
- * @param array
- * @param terminatingValue
+ * @param array - The source array to pull values from
+ * @param terminatingValue - The value to return when all array items have been consumed
+ * @returns A factory function that returns items from the array or the terminating value when exhausted
  */
 export declare function terminatingFactoryFromArray<T, E>(array: T[], terminatingValue: E): Factory<T | E>;

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

@@ -1,48 +1,64 @@
 import { type MapFunction } from '../value/map';
 import { type DecisionFunction } from '../value/decision';
+import { type AscendingSortCompareFunction } from '../sort';
 /**
- * Filters the input values by distance. The original order is retained.
+ * Filters the input values by distance while maintaining the original order of elements.
+ * Values that are too close to each other (based on the minDistance parameter) will be filtered out.
  *
- * If order is irrelevant, use filterValuesByDistanceNoOrder().
+ * If order is irrelevant, use filterValuesByDistanceNoOrder() instead.
+ *
+ * @param input - The array of values to filter
+ * @param minDistance - The minimum distance required between values
+ * @param getValue - Function that extracts a numeric value from each item for distance comparison
+ * @returns A filtered array with only values that are at least minDistance apart
  */
 export declare function filterValuesByDistance<T>(input: T[], minDistance: number, getValue: (value: T) => number | null): T[];
 /**
- * Filters the input values by an arbitrary "distance"/difference from eachother and returns the values sorted by their determined distance.
+ * Filters the input values by an arbitrary "distance"/difference from each other and returns the values sorted by their determined distance.
  *
- * This is useful in cases where many values are too "close" to eachother (Generally items that share the same time, or within seconds of eachother), and
+ * This is useful in cases where many values are too "close" to each other (generally items that share the same time, or within seconds of each other), and
  * we are only interested in seeing one of those items.
+ *
+ * @param input - The array of values to filter
+ * @param minDistance - The minimum distance required between values (inclusive)
+ * @param getValue - Function that extracts a numeric value from each item for distance comparison
+ * @returns A filtered array with only values that are at least minDistance apart, sorted by the extracted value
  */
 export declare function filterValuesByDistanceNoOrder<T>(input: T[], minDistance: number, getValue: (value: T) => number | null): T[];
 /**
  * Same as applyBestFit, but returns a new array, rather than modifying the existing array.
  *
- * @param input
- * @param filter
- * @param updateNonBestFit
+ * @param input - The array to filter for the best fit
+ * @param filter - Function that determines which items are candidates for the best fit
+ * @param compare - AscendingSortCompareFunction to compare two values to determine which is the best fit
+ * @param updateNonBestFit - Function that transforms non-best-fit items
+ * @returns A new array with only the best fit item and transformed non-best-fit items
  */
-export declare function makeBestFit<T>(input: T[], filter: (value: T) => boolean, compare: (a: T, b: T) => number, updateNonBestFit: (value: T) => T): T[];
+export declare function makeBestFit<T>(input: T[], filter: (value: T) => boolean, compare: AscendingSortCompareFunction<T>, updateNonBestFit: (value: T) => T): T[];
 /**
  * Used for updating an array so that a single element becomes the "best fit" in whatever context is provided.
  *
  * For instance, if two items are selected but only one can be selected by design, this function can be used to
  * pick the best fit, and update the input array.
  *
- * @param input
- * @param filter
- * @param updateNonBestFit
- * @returns
+ * @param input - The array to modify in-place
+ * @param filter - Function that determines which items are candidates for the best fit
+ * @param compare - AscendingSortCompareFunction to compare two values to determine which is the best fit
+ * @param updateNonBestFit - Function that transforms non-best-fit items
+ * @returns The modified input array with only the best fit item and transformed non-best-fit items
  */
-export declare function applyBestFit<T>(input: T[], filter: (value: T) => boolean, compare: (a: T, b: T) => number, updateNonBestFit: (value: T) => T): T[];
+export declare function applyBestFit<T>(input: T[], filter: (value: T) => boolean, compare: AscendingSortCompareFunction<T>, updateNonBestFit: (value: T) => T): T[];
 /**
  * Filters and maps the input values to an array.
+ * Combines filtering and mapping operations into a single pass over the data.
  */
 export type FilterAndMapFunction<I, O> = MapFunction<Iterable<I>, O[]>;
 /**
- * Filters the input values and maps all correct values to a new value.
+ * Creates a function that filters the input values and maps all matching values to a new value.
+ * This is a higher-order function that combines filtering and mapping operations.
  *
- * @param values
- * @param decisionFunction
- * @param mapFunction
- * @returns
+ * @param decisionFunction - Function that determines which items to include in the result
+ * @param mapFunction - Function that transforms each included item
+ * @returns A function that takes an iterable of input values and returns an array of transformed values
  */
 export declare function filterAndMapFunction<I, O>(decisionFunction: DecisionFunction<I>, mapFunction: MapFunction<I, O>): FilterAndMapFunction<I, O>;

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

@@ -1,21 +1,33 @@
 import { type SetIncludesMode } from '../set/set.mode';
 /**
  * A decision function used by the array find function.
+ * Similar to the predicate function in Array.prototype.find() or Array.prototype.filter().
+ * @template T - The type of elements in the array
  */
 export type ArrayFindDecisionFunction<T> = (value: T, index: number, obj: T[]) => boolean;
 /**
- * Returns a decision about an array based on it's input values using a preconfigured DecisionFunction and SetInclduesMode.
+ * Returns a decision about an array based on its input values using a preconfigured DecisionFunction and SetIncludesMode.
+ *
+ * @template T - The type of elements in the array
  */
 export type ArrayDecisionFunction<T> = (values: T[]) => boolean;
 /**
- * Creates a ArrayDecisionFunction based on the input decision and mode.
+ * Creates an ArrayDecisionFunction based on the input decision and mode.
  *
- * @param decision
- * @param mode
- * @returns
+ * @template T - The type of elements in the array
+ * @param decision - The function used to test individual elements of the array
+ * @param mode - The mode determining how the decision is applied ('any' or 'all')
+ * @returns A function that takes an array and returns a boolean decision based on the array elements
  */
 export declare function arrayDecisionFunction<T>(decision: ArrayFindDecisionFunction<T>, mode: SetIncludesMode): ArrayDecisionFunction<T>;
 /**
  * Returns true based on the input values and find decision.
+ * A convenience function that creates and immediately applies an array decision function.
+ *
+ * @template T - The type of elements in the array
+ * @param values - The array to evaluate
+ * @param decision - The function used to test individual elements of the array
+ * @param mode - The mode determining how the decision is applied ('any' or 'all')
+ * @returns A boolean indicating whether the array meets the decision criteria
  */
 export declare function arrayDecision<T>(values: T[], decision: ArrayFindDecisionFunction<T>, mode: SetIncludesMode): boolean;

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

@@ -1,3 +1,4 @@
+import { type AscendingSortCompareFunction } from '../sort';
 import { type IndexNumber, type IndexRef, type IndexRangeInput } from '../value/indexed';
 import { type Maybe } from '../value/maybe.type';
 /**
@@ -33,7 +34,7 @@ export declare function findBest<T>(input: T[], compare: (a: T, b: T) => number)
  * @param compare
  * @returns
  */
-export declare function findBestIndexSetPair<T>(input: IndexSetPairSet<T>, compare: (a: T, b: T) => number): IndexSetPair<T>;
+export declare function findBestIndexSetPair<T>(input: IndexSetPairSet<T>, compare: AscendingSortCompareFunction<T>): IndexSetPair<T>;
 /**
  * Slices a configured index range from the input array.
  */

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

@@ -3,11 +3,12 @@ export interface LimitArrayConfig {
     /**
      * Number of items in the list to limit in the result.
      */
-    limit: number;
+    readonly limit: number;
     /**
      * If true the limit will be pulled from the end instead of the front of the array.
      */
-    limitFromEnd?: boolean;
+    readonly limitFromEnd?: boolean;
 }
 export declare function limitArray<T>(array: T[], { limit, limitFromEnd }: Partial<LimitArrayConfig>): T[];
 export declare function limitArray<T>(array: Maybe<T[]>, { limit, limitFromEnd }: Partial<LimitArrayConfig>): Maybe<T[]>;
+export declare function limitArray<T>(array: Maybe<T[]>, config: Maybe<Partial<LimitArrayConfig>>): Maybe<T[]>;

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

@@ -1,15 +1,23 @@
 /**
- * Interface for configuring a Description Assertion
+ * Interface for configuring a Description Assertion.
+ * Provides options for customizing assertion messages.
+ * @interface
  */
 export interface DescriptorAssertionOptions {
     message?: string;
 }
 /**
  * DescriptorAssertionOptions extension that also maps one value to another.
+ * Extends the base assertion options to include a mapping function.
+ * @interface
+ * @template T - The type of value being mapped
  */
 export interface MapDescriptorAssertionOptions<T> extends DescriptorAssertionOptions {
     /**
      * Maps the value after it has been validated.
+     * This function is applied to transform the value after the assertion passes.
+     * @param value - The value to transform after validation
+     * @returns The transformed value
      */
     map?: (value: T) => T;
 }

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

@@ -1,32 +1,75 @@
 import { type ReadableError } from '../error';
 import { BaseError } from 'make-error';
 import { type DescriptorAssertionOptions } from './assert';
+/**
+ * Interface representing an assertion issue that occurred.
+ * Contains information about the object and property that failed the assertion.
+ * @interface
+ */
 export interface AssertionIssue {
     /**
-     * Object that encoundered the issue.
+     * Object that encountered the issue.
      */
-    target: object;
+    readonly target: object;
     /**
-     * Property that
+     * Property key that failed the assertion.
      */
-    propertyKey: string;
-    options?: DescriptorAssertionOptions;
+    readonly propertyKey: string;
+    readonly options?: DescriptorAssertionOptions;
 }
+/**
+ * Error code for assertion errors.
+ */
 export declare const ASSERTION_ERROR_CODE = "DBX_ASSERTION_ERROR";
+/**
+ * Error thrown when an assertion fails.
+ * Extends BaseError and implements ReadableError interface.
+ */
 export declare class AssertionError extends BaseError implements ReadableError {
     readonly code = "DBX_ASSERTION_ERROR";
-    private _target;
-    private _property;
+    private readonly _target;
+    private readonly _property;
     constructor(error: {
         target: object;
         propertyKey: string;
     }, message: string);
+    /**
+     * Gets the target object that failed the assertion.
+     * @returns The target object
+     */
     get target(): object;
+    /**
+     * Gets the property key that failed the assertion.
+     * @returns The property key as a string
+     */
     get propertyKey(): string;
 }
+/**
+ * Handler for assertion issues that builds and throws appropriate errors.
+ */
 export declare class AssertionIssueHandler {
+    /**
+     * Handles an assertion issue by throwing an appropriate exception.
+     * @param error - The assertion issue to handle
+     * @throws AssertionError
+     */
     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
+     */
     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
+     */
     protected buildExceptionString(error: AssertionIssue): string;
 }
+/**
+ * Default instance of AssertionIssueHandler used for handling assertion issues.
+ * TODO: Allow changing, if needed.
+ */
 export declare const ASSERTION_HANDLER: AssertionIssueHandler;

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

@@ -27,4 +27,11 @@ export declare const AUTH_ADMIN_ROLE = "admin";
  * Auth role for a general user. Is allowed into the app and is logged in.
  */
 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
+ */
 export declare function authRolesSetHasRoles(authRolesSet: AuthRoleSet, roles: Maybe<Iterable<AuthRole>>): boolean;

package/src/lib/boolean.d.ts

@@ -1,8 +1,53 @@
 import { type Factory } from './getter/getter';
+/**
+ * Type representing whether something is valid.
+ */
+export type IsValid = boolean;
+/**
+ * Type representing whether something is equal to something else.
+ */
+export type IsEqual = boolean;
+/**
+ * Type representing whether something has been modified.
+ */
+export type IsModified = boolean;
+/**
+ * Reduces an array of booleans with the logical AND operation.
+ *
+ * @param array - Array of boolean values to reduce
+ * @param emptyArrayValue - Value to return if the array is empty (default: undefined which becomes false)
+ * @returns The result of ANDing all boolean values in the array
+ */
 export declare function reduceBooleansWithAnd(array: boolean[], emptyArrayValue?: boolean): boolean;
+/**
+ * Reduces an array of booleans with the logical OR operation.
+ *
+ * @param array - Array of boolean values to reduce
+ * @param emptyArrayValue - Value to return if the array is empty (default: undefined which becomes false)
+ * @returns The result of ORing all boolean values in the array
+ */
 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 (default: undefined which becomes false)
+ * @returns A function that takes an array of booleans and returns the result of ANDing them
+ */
 export declare function reduceBooleansWithAndFn(emptyArrayValue?: boolean): (array: boolean[]) => boolean;
+/**
+ * Creates a function that reduces an array of booleans with the logical OR operation.
+ *
+ * @param emptyArrayValue - Value to return if the array is empty (default: undefined which becomes false)
+ * @returns A function that takes an array of booleans and returns the result of ORing them
+ */
 export declare function reduceBooleansWithOrFn(emptyArrayValue?: boolean): (array: boolean[]) => boolean;
+/**
+ * Creates a function that reduces an array of booleans using a custom reduce function.
+ *
+ * @param reduceFn - Function that takes two boolean values and returns a single boolean
+ * @param emptyArrayValue - Value to return if the array is empty (default: undefined which uses the standard reduce behavior)
+ * @returns A function that takes an array of booleans and returns the result of reducing them
+ */
 export declare function reduceBooleansFn(reduceFn: (a: boolean, b: boolean) => boolean, emptyArrayValue?: boolean): (array: boolean[]) => boolean;
 /**
  * Factory that generates boolean values.
@@ -19,16 +64,16 @@ export interface BooleanFactoryConfig {
     chance: BooleanChance;
 }
 /**
- * Creates a new BooleanFactory.
+ * Creates a new BooleanFactory that generates random boolean values based on chance.
  *
- * @param config
- * @returns
+ * @param config - Configuration for the boolean factory, including the chance of returning true
+ * @returns A factory function that generates random boolean values
  */
 export declare function booleanFactory(config: BooleanFactoryConfig): () => boolean;
 /**
- * Returns a random boolean.
+ * Returns a random boolean based on the specified chance.
  *
- * @param chance Number between 0 and 100
- * @returns
+ * @param chance - Number between 0 and 100 representing the percentage chance of returning true (default: 50)
+ * @returns A random boolean value with the specified probability of being true
  */
 export declare function randomBoolean(chance?: BooleanChance): boolean;

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

@@ -1,15 +1,48 @@
+/**
+ * Type representing an email address as a string.
+ */
 export type EmailAddress = string;
+/**
+ * Interface representing a pair of a name and an email address.
+ */
 export interface NameEmailPair {
     name?: string;
     email: EmailAddress;
 }
+/**
+ * Type representing an email participant with a name and email address.
+ * Alias for NameEmailPair for semantic clarity in email-related contexts.
+ */
 export type EmailParticipant = NameEmailPair;
 /**
  * Email participant string. Starts with the email, followed by the name if available.
  */
 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
+ */
 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 - 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
+ */
 export declare function coerceToEmailParticipants({ participants, emails }: {
     participants?: EmailParticipant[];
     emails?: EmailAddress[];