@dereekb/util 13.0.6 → 13.1.0

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

@@ -1,11 +1,65 @@
 import { type IndexRange } from '../value/indexed';
+/**
+ * Reduces an array of numbers to its maximum value.
+ *
+ * @param array - numbers to evaluate
+ * @param emptyArrayValue - value to return when the array is empty
+ * @returns the maximum number in the array, or the empty array value if the array is empty
+ */
 export declare function reduceNumbersWithMax(array: number[], emptyArrayValue?: number): number | undefined;
+/**
+ * Creates a reducer function that finds the maximum value in a number array.
+ *
+ * @param emptyArrayValue - value to return when the array is empty
+ * @returns a function that reduces a number array to its maximum value
+ */
 export declare function reduceNumbersWithMaxFn(emptyArrayValue?: number): (array: number[]) => number | undefined;
+/**
+ * Reduces an array of numbers to its minimum value.
+ *
+ * @param array - numbers to evaluate
+ * @param emptyArrayValue - value to return when the array is empty
+ * @returns the minimum number in the array, or the empty array value if the array is empty
+ */
 export declare function reduceNumbersWithMin(array: number[], emptyArrayValue?: number): number | undefined;
+/**
+ * Creates a reducer function that finds the minimum value in a number array.
+ *
+ * @param emptyArrayValue - value to return when the array is empty
+ * @returns a function that reduces a number array to its minimum value
+ */
 export declare function reduceNumbersWithMinFn(emptyArrayValue?: number): (array: number[]) => number | undefined;
+/**
+ * Reduces an array of numbers by summing all values.
+ *
+ * @param array - numbers to sum
+ * @param emptyArrayValue - value to return when the array is empty; defaults to 0
+ * @returns the sum of all numbers in the array
+ */
 export declare function reduceNumbersWithAdd(array: number[], emptyArrayValue?: number): number;
+/**
+ * Creates a reducer function that sums all values in a number array.
+ *
+ * @param emptyArrayValue - value to return when the array is empty; defaults to 0
+ * @returns a function that reduces a number array to the sum of its values
+ */
 export declare function reduceNumbersWithAddFn(emptyArrayValue?: number): (array: number[]) => number;
+/**
+ * Reduces an array of numbers using a custom reducer function.
+ *
+ * @param reduceFn - binary function applied to successive pairs of numbers
+ * @param array - numbers to reduce
+ * @param emptyArrayValue - value to return when the array is empty
+ * @returns the reduced result, or the empty array value if the array is empty
+ */
 export declare function reduceNumbers(reduceFn: (a: number, b: number) => number, array: number[], emptyArrayValue?: number): number | undefined;
+/**
+ * Creates a reusable reducer function that reduces a number array using a custom binary function.
+ *
+ * @param reduceFn - binary function applied to successive pairs of numbers
+ * @param emptyArrayValue - value to return when the array is empty
+ * @returns a function that reduces a number array to a single value
+ */
 export declare function reduceNumbersFn(reduceFn: (a: number, b: number) => number): (array: number[]) => number | undefined;
 export declare function reduceNumbersFn<D extends number>(reduceFn: (a: number, b: number) => number, emptyArrayValue?: D): (array: number[]) => number | D;
 /**
@@ -25,13 +79,17 @@ export interface RangeInputObject {
      */
     readonly end: RangeInputEndValue;
 }
+/**
+ * Input for the {@link range} function. Accepts a plain number (treated as the exclusive end with start at 0),
+ * a {@link RangeInputObject}, or an {@link IndexRange}.
+ */
 export type RangeInput = number | RangeInputObject | IndexRange;
 /**
- * Generates an array containing the range of numbers specified.
- *
- * The end value is excluded.
+ * Generates an array containing the range of numbers specified. The end value is excluded.
+ * Supports ascending and descending ranges.
  *
- * @param param0
- * @returns
+ * @param input - range specification as a number, {@link RangeInputObject}, or {@link IndexRange}; when a number and `inputEnd` is provided, acts as the start value
+ * @param inputEnd - optional exclusive end value when `input` is a number
+ * @returns an array of sequential numbers within the specified range
  */
 export declare function range(input: RangeInput, inputEnd?: RangeInputEndValue): number[];

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

@@ -1,6 +1,6 @@
 import { type IndexNumber } from '../value/index';
 /**
- * Returns a random value from the pre-configured values array.
+ * A callable factory that returns a random value from its pre-configured values array on each invocation.
  */
 export type RandomPickFactory<T> = (() => T) & {
     /**
@@ -9,22 +9,25 @@ export type RandomPickFactory<T> = (() => T) & {
     readonly _values: T[];
 };
 /**
- * Creates a RandomPickFactory<T> from the input values.
+ * Creates a {@link RandomPickFactory} from the input values.
  *
- * @param values
- * @returns
+ * @param values - array of values to randomly pick from
+ * @returns a callable factory that returns a random value from the array on each invocation
+ * @throws Error if the input array is empty
  */
 export declare function randomPickFactory<T>(values: T[]): RandomPickFactory<T>;
 /**
- * Returns a random index from the input values.
+ * Returns a random index from the input array. Returns 0 if the array is empty.
  *
- * @param values
- * @returns
+ * @param values - array to generate a random index for
+ * @returns a random valid index within the array, or 0 if the array is empty
  */
 export declare function randomArrayIndex<T>(values: T[]): IndexNumber;
 /**
- * Picks an item randomly from the input array. If the array is empty, returns undefined.
+ * Picks a single item randomly from the input array.
  *
- * @param values
+ * @param values - array to pick a random item from
+ * @returns a randomly selected item from the array
+ * @throws Error if the input array is empty
  */
 export declare function pickOneRandomly<T>(values: T[]): T;

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

@@ -1,7 +1,30 @@
 /**
- * Returns items that exist in both arrays.
+ * Returns items that exist in both arrays (intersection).
+ *
+ * @param values - The source array to filter.
+ * @param secondArray - The array of values to keep.
+ * @returns A new array containing only the values from `values` that also exist in `secondArray`.
  */
 export declare function keepValuesFromArray<T>(values: T[], secondArray: T[]): T[];
+/**
+ * Returns items from the first array that do not exist in the second array (difference).
+ *
+ * @param values - The source array to filter.
+ * @param secondArray - The array of values to exclude.
+ * @returns A new array containing only the values from `values` that do not exist in `secondArray`.
+ */
 export declare function excludeValuesFromArray<T>(values: T[], secondArray: T[]): T[];
+/**
+ * Checks whether the given array contains any duplicate values.
+ *
+ * @param values - The array to check for duplicates.
+ * @returns `true` if the array contains at least one duplicate value, `false` otherwise.
+ */
 export declare function arrayContainsDuplicateValue<T>(values: T[]): boolean;
+/**
+ * Finds the index of the first duplicate value in the given array.
+ *
+ * @param values - The array to search for duplicates.
+ * @returns The index of the first value that is a duplicate of an earlier value, or `-1` if no duplicates exist.
+ */
 export declare function findIndexOfFirstDuplicateValue<T>(values: T[]): number;

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

@@ -2,20 +2,116 @@ import { type ArrayOrValue } from './array';
 import { type ReadKeyFunction } from '../key';
 import { type MapFunction } from '../value/map';
 import { type TransformStringFunctionConfig } from '../string/transform';
+/**
+ * Compares two string arrays and returns whether they contain different values, ignoring case.
+ *
+ * @param a - first array of strings to compare
+ * @param b - second array of strings to compare
+ * @returns `true` if the arrays contain different values when compared case-insensitively
+ */
 export declare function hasDifferentStringsNoCase(a: string[], b: string[]): boolean;
+/**
+ * Maps an array of strings to their trimmed equivalents.
+ *
+ * @param input - array of strings to trim
+ * @returns a new array with each string trimmed of leading and trailing whitespace
+ */
 export declare const trimArray: MapFunction<string[], string[]>;
+/**
+ * Maps an array of strings to their uppercase equivalents.
+ *
+ * @param input - array of strings to convert
+ * @returns a new array with each string converted to uppercase
+ */
 export declare const arrayToUppercase: MapFunction<string[], string[]>;
+/**
+ * Maps an array of strings to their lowercase equivalents.
+ *
+ * @param input - array of strings to convert
+ * @returns a new array with each string converted to lowercase
+ */
 export declare const arrayToLowercase: MapFunction<string[], string[]>;
+/**
+ * A function that transforms an array of strings into another array of strings.
+ */
 export type TransformStringsFunction = MapFunction<string[], string[]>;
+/**
+ * Creates a {@link TransformStringsFunction} from the given configuration. If the configuration results
+ * in an identity transform, the returned function will be an identity function.
+ *
+ * @param config - configuration describing the string transformations to apply
+ * @returns a function that applies the configured transformations to an array of strings
+ */
 export declare function transformStrings(config: TransformStringFunctionConfig): TransformStringsFunction;
+/**
+ * Converts an iterable of strings to a lowercase string array for case-insensitive operations.
+ *
+ * @param values - iterable of strings to convert
+ * @returns an array of lowercase strings
+ */
 export declare function toCaseInsensitiveStringArray(values: Iterable<string>): string[];
+/**
+ * Returns an array of unique strings from the input, compared case-insensitively. All returned strings are lowercase.
+ *
+ * @param values - iterable of strings to deduplicate
+ * @returns an array of unique lowercase strings
+ */
 export declare function uniqueCaseInsensitiveStrings(values: Iterable<string>): string[];
+/**
+ * Returns a {@link Set} of unique lowercase strings from the input, compared case-insensitively.
+ *
+ * @param values - iterable of strings to deduplicate
+ * @returns a set of unique lowercase strings
+ */
 export declare function uniqueCaseInsensitiveStringsSet(values: Iterable<string>): Set<string>;
+/**
+ * Flattens a two-dimensional array of strings into a single array of unique lowercase strings, compared case-insensitively.
+ *
+ * @param array - two-dimensional array of strings to flatten and deduplicate
+ * @returns a flat array of unique lowercase strings
+ */
 export declare function flattenArrayUniqueCaseInsensitiveStrings(array: string[][]): string[];
+/**
+ * Filters an array of models to only include items with unique keys when compared case-insensitively.
+ * Items whose keys match the additional keys are also excluded.
+ *
+ * @param models - array of models to filter
+ * @param readKey - function that extracts the string key from each model
+ * @param additionalKeys - optional keys to treat as already seen, excluding models with matching keys
+ * @returns the filtered array of models with unique case-insensitive keys
+ */
 export declare function filterUniqueCaseInsensitiveStrings<T, K extends string = string>(models: T[], readKey: ReadKeyFunction<T, K>, additionalKeys?: K[]): T[];
+/**
+ * Checks whether the given iterable contains the specified string, ignoring case.
+ *
+ * @param values - iterable of strings to search
+ * @param valueToFind - the string to search for
+ * @param mustContainAtleastOneItem - if `true`, returns `false` when the values iterable is empty
+ * @returns `true` if the string is found case-insensitively
+ */
 export declare function containsStringAnyCase(values: Iterable<string>, valueToFind: string, mustContainAtleastOneItem?: boolean): boolean;
+/**
+ * Checks whether the given iterable contains any of the specified strings, ignoring case.
+ *
+ * @param values - iterable of strings to search
+ * @param valuesToFind - iterable of strings to search for
+ * @param mustContainAtleastOneItem - if `true`, returns `false` when the values iterable is empty
+ * @returns `true` if at least one of the strings is found case-insensitively
+ */
 export declare function containsAnyStringAnyCase(values: Iterable<string>, valuesToFind: Iterable<string>, mustContainAtleastOneItem?: boolean): boolean;
+/**
+ * Checks whether the given iterable contains all of the specified strings, ignoring case.
+ * Returns `true` if there are no strings to find.
+ *
+ * @param values - iterable of strings to search
+ * @param valuesToFind - iterable of strings that must all be present
+ * @param mustContainAtleastOneItem - if `true`, returns `false` when the values iterable is empty
+ * @returns `true` if all of the strings are found case-insensitively
+ */
 export declare function containsAllStringsAnyCase(values: Iterable<string>, valuesToFind: Iterable<string>, mustContainAtleastOneItem?: boolean): boolean;
+/**
+ * Configuration for creating a {@link FilterUniqueTransform} that transforms and deduplicates an array of strings.
+ */
 export interface FilterUniqueStringsTransformConfig extends TransformStringFunctionConfig {
     /**
      * Whether or not to compare values as lowercase when finding uniqueness.
@@ -32,4 +128,12 @@ export interface FilterUniqueStringsTransformConfig extends TransformStringFunct
  * Transforms an array of strings into an array of unique strings.
  */
 export type FilterUniqueTransform = TransformStringsFunction;
+/**
+ * Creates a function that transforms an array of strings and removes duplicates based on the given configuration.
+ * When `caseInsensitive` is enabled, uniqueness is determined before transformation; otherwise, transformation
+ * is applied first and then duplicates are removed.
+ *
+ * @param config - configuration describing transformation, uniqueness comparison, and exclusions
+ * @returns a function that transforms and deduplicates an input array of strings
+ */
 export declare function filterUniqueTransform(config: FilterUniqueStringsTransformConfig): FilterUniqueTransform;

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

@@ -1,14 +1,26 @@
 import { type PrimativeKey, type ReadKeyFunction } from '../key';
 import { type Maybe } from '../value/maybe.type';
 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.
+ */
 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.
+ */
 export declare function flattenArrayUnique<T extends PrimativeKey = PrimativeKey>(array: T[][]): T[];
 /**
  * Filters the input values and only returns unique values.
  *
- * @param values
- * @param exclude
- * @returns
+ * @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[];
 /**
@@ -17,27 +29,64 @@ export declare function unique<T extends PrimativeKey = PrimativeKey>(values: T[
  * Can also specify additional values to exclude.
  */
 export type FilterUniqueFunction<T, K extends PrimativeKey = PrimativeKey> = (input: T[], exclude?: FilterUniqueFunctionExcludeKeysInput<T, K>) => T[];
+/**
+ * Input for specifying additional keys to include in uniqueness checks. Accepts either a raw array of keys or a {@link FilterUniqueFunctionAdditionalKeys} object.
+ */
 export type FilterUniqueFunctionAdditionalKeysInput<T, K extends PrimativeKey = PrimativeKey> = K[] | FilterUniqueFunctionAdditionalKeys<T, K>;
+/**
+ * Input for specifying keys or values to exclude from unique filtering. Accepts either a raw array of values or a {@link FilterUniqueFunctionAdditionalKeys} object.
+ */
 export type FilterUniqueFunctionExcludeKeysInput<T, K extends PrimativeKey = PrimativeKey> = T[] | FilterUniqueFunctionAdditionalKeys<T, K>;
+/**
+ * Provides additional keys and/or values to seed the uniqueness filter, causing those entries to be treated as already seen.
+ */
 export interface FilterUniqueFunctionAdditionalKeys<T, K extends PrimativeKey = PrimativeKey> {
     readonly keys?: Maybe<K[]>;
     readonly values?: Maybe<T[]>;
 }
+/**
+ * Reads and resolves keys from a {@link FilterUniqueFunctionAdditionalKeysInput}, handling both raw key arrays and structured input objects.
+ *
+ * @param additionalKeysInput - Input containing keys to resolve.
+ * @param readKey - Function to extract a key from a value.
+ * @returns Flat array of resolved non-null keys.
+ */
 export declare function readKeysFromFilterUniqueFunctionAdditionalKeysInput<T, K extends PrimativeKey = PrimativeKey>(additionalKeysInput: Maybe<FilterUniqueFunctionAdditionalKeysInput<T, K>>, readKey: ReadKeyFunction<T, K>): K[];
+/**
+ * Reads keys from a {@link FilterUniqueFunctionAdditionalKeys} object by combining explicit keys with keys derived from values.
+ *
+ * @param input - Object containing explicit keys and/or values to derive keys from.
+ * @param readKey - Function to extract a key from a value.
+ * @returns Array of keys, which may include null/undefined entries.
+ */
 export declare function readKeysFromFilterUniqueFunctionAdditionalKeys<T, K extends PrimativeKey = PrimativeKey>(input: FilterUniqueFunctionAdditionalKeys<T, K>, readKey: ReadKeyFunction<T, K>): Maybe<K>[];
 /**
- * Creates a FilterUniqueFunction.
+ * Creates a {@link FilterUniqueFunction} that deduplicates items by their computed key.
  *
- * @param readKey
- * @param additionalKeys
- * @returns
+ * @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.
  */
 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.
+ *
+ * @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.
+ */
 export declare function filterUniqueValues<T, K extends PrimativeKey = PrimativeKey>(values: T[], readKey: ReadKeyFunction<T, K>, additionalKeys?: K[]): T[];
 /**
  * Returns true if all input values have unique keys.
  */
 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.
+ */
 export declare function isUniqueKeyedFunction<T, K extends PrimativeKey = PrimativeKey>(readKey: ReadKeyFunction<T, K>): IsUniqueKeyedFunction<T>;
 /**
  * Function that returns true for a value the first time that value's key is visited. Will return false for all visits after that.
@@ -53,7 +102,10 @@ export type AllowValueOnceFilter<T, K extends PrimativeKey = PrimativeKey> = Dec
     readonly _visitedKeys: Set<Maybe<K>>;
 };
 /**
- * Creates a new AllowValueOnceFilter.
+ * Creates a new {@link AllowValueOnceFilter} that permits each unique key only on its first encounter.
+ *
+ * @param inputReadKey - Optional function to extract a key from each value. Defaults to identity.
+ * @returns A stateful filter function that returns true only for the first occurrence of each key.
  */
 export declare function allowValueOnceFilter<T extends PrimativeKey = PrimativeKey>(): AllowValueOnceFilter<T, T>;
 export declare function allowValueOnceFilter<T, K extends PrimativeKey = PrimativeKey>(readKey?: ReadKeyFunction<T, K>): AllowValueOnceFilter<T, K>;

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

@@ -1,35 +1,44 @@
 import { type Maybe, type MaybeNot } from '../value/maybe.type';
 /**
- * Function that takes the input and returns an array with no Maybe values.
+ * Function that takes an optional array of optional values and returns a filtered array with no Maybe values.
  */
 export type FilterMaybeArrayFunction<T> = (value: Maybe<Maybe<T[]>>) => T[];
+/**
+ * A generic variant of {@link FilterMaybeArrayFunction} that works with any element type.
+ */
 export type UniversalFilterMaybeArrayFunction = <T>(values: Maybe<Maybe<T>[]>) => 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 A function that filters maybe values from an optional input array.
+ */
 export declare function filterMaybeArrayFunction<T>(filterFn: Parameters<Array<Maybe<T>>['filter']>[0]): FilterMaybeArrayFunction<T>;
 /**
  * Filters all maybe values from the input array. If a maybe value is input, returns an empty array.
  *
- * @param values
- * @returns
+ * @param values - Optional array of optional values to filter.
+ * @returns An array containing only non-null and non-undefined values.
  */
 export declare const filterMaybeArrayValues: UniversalFilterMaybeArrayFunction;
 /**
  * Filters all empty and maybe values from the input array. If a maybe value is input, returns an empty array.
  *
- * @param values
- * @returns
+ * @param values - Optional array of optional values to filter.
+ * @returns An array containing only non-null, non-undefined, and non-empty values.
  */
 export declare const filterEmptyArrayValues: UniversalFilterMaybeArrayFunction;
 /**
- * Checks whether or not all values are MaybeNot values.
+ * Checks whether or not all values in the array are {@link MaybeNot} (null or undefined).
  *
- * @param values
- * @returns
+ * @param values - Array of optional values to check.
+ * @returns `true` if every value in the array is null or undefined.
  */
 export declare function allValuesAreMaybeNot<T>(values: Maybe<T>[]): values is MaybeNot[];
 /**
- * Checks whether or not all values are non-MaybeNot values.
+ * Checks whether or not all values in the array are defined (non-null and non-undefined).
  *
- * @param values
- * @returns
+ * @param values - Array of optional values to check.
+ * @returns `true` if every value in the array is non-null and non-undefined.
  */
 export declare function allValuesAreNotMaybe<T>(values: Maybe<T>[]): values is T[];

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

@@ -1,18 +1,46 @@
 import { type MapDescriptorAssertionOptions } from './assert';
 /**
- * Assertion function type.
+ * Assertion function type that validates a value.
  *
- * Returns true if the assertion passes.
+ * Returns true if the assertion passes, false otherwise.
  */
 export type AccessorValueAssertion<T> = (value: T) => boolean;
+/**
+ * Input provided to a set-value interceptor factory function.
+ */
 export interface SetValueInterceptorFunctionInput<T> {
     target: object;
     propertyKey: string;
     descriptor: TypedPropertyDescriptor<T>;
     setValue: (value: T) => void;
 }
+/**
+ * Factory function that creates a setter interceptor from the provided input.
+ */
 export type SetValueInterceptorFunctionFactory<T> = (input: SetValueInterceptorFunctionInput<T>) => (value: T) => void;
+/**
+ * Utility class for creating property descriptor interceptors that validate
+ * values before allowing them to be set on a property.
+ *
+ * Used to build TypeScript decorator functions that enforce assertions on property setters.
+ */
 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 options - Custom assertion options (message, map 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
+     */
     static makeSetPropertyDescriptorInterceptor<T>(makeSetValueInterceptorFn: SetValueInterceptorFunctionFactory<T>): (target: object, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) => void;
 }

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

@@ -1,3 +1,11 @@
 import { type MapDescriptorAssertionOptions } from './assert';
 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
+ */
 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

@@ -1,3 +1,19 @@
 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`
+ */
 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`
+ */
 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

@@ -44,7 +44,7 @@ export type AuthClaimsUpdate<T extends AuthClaimsObject = AuthClaimsObject> = Pa
  */
 export type AuthRoleClaimsFactoryConfigEntry<V extends AuthClaimValue = AuthClaimValue> = V extends SimpleAuthClaimValue ? AuthRoleClaimsFactoryConfigEntryEncodeOptions<V> | AuthRoleClaimsFactoryConfigEntrySimpleOptions<V> : AuthRoleClaimsFactoryConfigEntryEncodeOptions<V>;
 /**
- *
+ * Simple configuration for a claims key that maps a claim value directly to one or more roles.
  */
 export interface AuthRoleClaimsFactoryConfigEntrySimpleOptions<V extends SimpleAuthClaimValue = SimpleAuthClaimValue> {
     /**
@@ -117,17 +117,23 @@ export interface AuthRoleClaimsService<T extends AuthClaimsObject> {
 export declare const AUTH_ROLE_CLAIMS_DEFAULT_CLAIM_VALUE = 1;
 export declare const AUTH_ROLE_CLAIMS_DEFAULT_EMPTY_VALUE: null;
 /**
- * Creates a AuthRoleClaimsService using the input configuration.
+ * 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
- * @param defaults
- * @returns
+ * @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
  */
 export declare function authRoleClaimsService<T extends AuthClaimsObject>(config: AuthRoleClaimsFactoryConfig<T>, defaults?: AuthRoleClaimsFactoryDefaults): AuthRoleClaimsService<T>;
 /**
- * Converts an AuthClaimsUpdate to AuthClaims by removing all null keys.
+ * Converts an {@link AuthClaimsUpdate} to {@link AuthClaims} by stripping all null-valued keys.
+ *
+ * Useful for cleaning up a claims update before persisting or comparing, since update objects
+ * use `null` to indicate claim removal.
  *
- * @param authClaimsUpdate
- * @returns
+ * @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>;