@dereekb/util 13.4.0 → 13.4.2

package/src/lib/relation/relation.d.ts

@@ -125,6 +125,12 @@ export declare class ModelRelationUtility {
      * The mask results are merged together.
      *
      * Order from the "current" is retained. Anything in currentRetain overrides modifiedResults.
+     *
+     * @param current - the original array whose ordering is preserved
+     * @param currentRetain - items from `current` that were excluded from modification and take precedence in the merge
+     * @param modifiedResults - items that were modified or added during the relation change
+     * @param readKey - function that extracts the relation key from each item for ordering
+     * @returns the merged array with original ordering restored
      */
     private static _mergeMaskResults;
     private static _modifyCollectionWithoutMask;
@@ -149,6 +155,12 @@ export declare class ModelRelationUtility {
     static insertCollection<T extends RelationObject>(current: T[], update: T[], config: UpdateRelationConfig<T> | UpdateMiltiTypeRelationConfig<T>): T[];
     /**
      * Used to modify a collection which may be multi-type. If readType is provided, the collection is handled as a multi-type map.
+     *
+     * @param current - the current collection of relation objects
+     * @param mods - the modifications to apply to the collection
+     * @param modifyCollection - function that applies modifications to a single-type subset of the collection
+     * @param readType - optional function to read the type from each relation object, enabling multi-type handling
+     * @returns the modified collection with all changes applied
      */
     private static _modifyCollection;
     private static _modifyMultiTypeCollection;

package/src/lib/service/handler.config.d.ts

@@ -73,7 +73,9 @@ export type HandlerConfigurerFactory<C extends HandlerBindAccessor<T, K, R>, T,
  * Configuration for {@link handlerConfigurerFactory}.
  */
 export interface HandlerConfigurerFactoryConfig<C extends HandlerBindAccessor<T, K, R>, T, K extends PrimativeKey = string, R = HandleResult> {
-    /** Creates a typed configurer from a bind accessor. */
+    /**
+     * Creates a typed configurer from a bind accessor.
+     */
     configurerForAccessor: (accessor: HandlerBindAccessor<T, K, R>) => C;
 }
 /**

package/src/lib/service/handler.d.ts

@@ -80,9 +80,13 @@ export type HandlerFactory<T, K extends PrimativeKey = string, R = HandleResult>
  * Options for configuring default and negative results in a {@link HandlerFactory}.
  */
 export interface HandlerFactoryOptions<R = HandleResult> {
-    /** The result returned when a handler function returns void. */
+    /**
+     * The result returned when a handler function returns void.
+     */
     readonly defaultResult: R;
-    /** The result returned when no handler matches the input key. */
+    /**
+     * The result returned when no handler matches the input key.
+     */
     readonly negativeResult: R;
 }
 /**

package/src/lib/service/typed.service.d.ts

@@ -35,7 +35,9 @@ export declare class TypedServiceRegistryInstance<S, T extends string = string>
  * Configuration for initializing a {@link TypedServiceRegistryInstance} with a set of services.
  */
 export interface TypedServiceRegistrySetupConfig<S, T extends string = string> {
-    /** A record mapping type keys to their service instances. */
+    /**
+     * A record mapping type keys to their service instances.
+     */
     services: {
         [K in T]: S;
     };

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

@@ -266,6 +266,11 @@ export declare function setIncludesFunction<T>(valuesSet: Set<T>, mode?: SetIncl
 export declare function setIncludes<T>(valuesSet: Set<T>, valuesToFind: IterableOrValue<T>, mode?: SetIncludesMode): boolean;
 /**
  * Returns false if the input array contains any value from the second array.
+ *
+ * @param values - the values to check against
+ * @param valuesToFind - the values to look for
+ * @param emptyValuesToFindArrayResult - result when valuesToFind is empty
+ * @returns `true` if none of the valuesToFind are present in values
  */
 export declare function containsNoneOfValue<T>(values: IterableOrValue<T>, valuesToFind: IterableOrValue<T>, emptyValuesToFindArrayResult?: boolean): boolean;
 /**
@@ -290,6 +295,11 @@ export declare function setContainsNoneOfValue<T>(valuesSet: Set<T>, valuesToFin
  * Returns true if the input array contains any value from the second array.
  *
  * If valuesToFind is empty, returns the emptyValuesToFindArrayResult value. Defaults to false.
+ *
+ * @param values - the values to build a set from and check against
+ * @param valuesToFind - the values to search for within the set
+ * @param emptyValuesToFindArrayResult - result when valuesToFind is empty; defaults to false
+ * @returns `true` if any of the valuesToFind exist in values
  */
 export declare function containsAnyValue<T>(values: IterableOrValue<T>, valuesToFind: IterableOrValue<T>, emptyValuesToFindArrayResult?: boolean): boolean;
 /**
@@ -297,9 +307,10 @@ export declare function containsAnyValue<T>(values: IterableOrValue<T>, valuesTo
  *
  * If values is empty, returns the emptyValuesToFindArrayResult value. Defaults to false.
  *
- * @param values
- * @param valuesToFind
- * @returns
+ * @param values - the values to check for membership in the set
+ * @param valuesToFind - the set to check against
+ * @param emptyValuesArrayResult - result when values is empty; defaults to false
+ * @returns `true` if any of the values are present in the set
  */
 export declare function containsAnyValueFromSet<T>(values: IterableOrValue<T>, valuesToFind: Set<T>, emptyValuesArrayResult?: boolean): boolean;
 /**
@@ -307,10 +318,10 @@ export declare function containsAnyValueFromSet<T>(values: IterableOrValue<T>, v
  *
  * If valuesToFind is empty, returns the emptyValuesToFindArrayResult value. Defaults to false.
  *
- * @param valuesSet
- * @param valuesToFind
- * @param emptyValuesToFindArrayResult
- * @returns
+ * @param valuesSet - the set to check for membership
+ * @param valuesToFind - the values to search for in the set
+ * @param emptyValuesToFindArrayResult - result when valuesToFind is empty; defaults to false
+ * @returns `true` if any of the valuesToFind are present in the set
  */
 export declare function setContainsAnyValue<T>(valuesSet: Set<T>, valuesToFind: IterableOrValue<T>, emptyValuesToFindArrayResult?: boolean): boolean;
 /**
@@ -318,9 +329,10 @@ export declare function setContainsAnyValue<T>(valuesSet: Set<T>, valuesToFind:
  *
  * If valuesToFind is empty, returns the emptyValuesToFindArrayResult value. Defaults to true.
  *
- * @param values
- * @param valuesToFind
- * @returns
+ * @param values - the iterable of values to build a set from
+ * @param valuesToFind - the values that must all be present
+ * @param emptyValuesArrayResult - result when valuesToFind is empty; defaults to true
+ * @returns `true` if all valuesToFind are present in the values set
  */
 export declare function containsAllValues<T>(values: Iterable<T>, valuesToFind: IterableOrValue<T>, emptyValuesArrayResult?: boolean): boolean;
 /**
@@ -328,24 +340,25 @@ export declare function containsAllValues<T>(values: Iterable<T>, valuesToFind:
  *
  * If valuesToFind is empty, returns the emptyValuesToFindArrayResult value. Defaults to true.
  *
- * @param valuesSet
- * @param valuesToFind
- * @param emptyValuesToFindArrayResult
- * @returns
+ * @param valuesSet - the set to check for full containment
+ * @param valuesToFind - the values that must all be present in the set
+ * @param emptyValuesToFindArrayResult - result when valuesToFind is empty; defaults to true
+ * @returns `true` if every value in valuesToFind is present in the set
  */
 export declare function setContainsAllValues<T>(valuesSet: Set<T>, valuesToFind: IterableOrValue<T>, emptyValuesToFindArrayResult?: boolean): boolean;
 /**
  * Returns true if both iterables are defined (or are both null/undefined) and have the same values exactly.
  *
- * @param a
- * @param b
- * @returns
+ * @param a - first iterable to compare
+ * @param b - second iterable to compare
+ * @returns `true` if both iterables contain the same unique values, or both are nullish
  */
 export declare function iterablesAreSetEquivalent<T>(a: Maybe<Iterable<T>>, b: Maybe<Iterable<T>>): boolean;
 /**
  * Returns true if both sets are defined (or are both null/undefined) and have the same values exactly.
  *
- * @param a
- * @param b
+ * @param a - first set to compare
+ * @param b - second set to compare
+ * @returns `true` if both sets contain the same values, or both are nullish
  */
 export declare function setsAreEquivalent<T>(a: Maybe<Set<T>>, b: Maybe<Set<T>>): boolean;

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

@@ -4,7 +4,9 @@ import { type Maybe } from '../value/maybe.type';
  * Configuration for a {@link HashSet}, providing the key extraction function.
  */
 export interface HashSetConfig<K extends PrimativeKey, T> {
-    /** Extracts the unique key used for equality comparison from each value. */
+    /**
+     * Extracts the unique key used for equality comparison from each value.
+     */
     readKey: ReadKeyFunction<T, K>;
 }
 /**

package/src/lib/sort.d.ts

@@ -40,6 +40,9 @@ export type AscendingSortCompareFunction<T> = SortCompareFunction<T>;
 export type SortDescendingCompareFunction<T> = SortCompareFunction<T>;
 /**
  * Convenience function that reverses the order of the sorted values.
+ *
+ * @param compareFn - the comparison function whose order should be reversed
+ * @returns a new comparison function with the opposite sort direction
  */
 export declare function reverseCompareFn<T>(compareFn: AscendingSortCompareFunction<T>): SortDescendingCompareFunction<T>;
 export declare function reverseCompareFn<T>(compareFn: SortDescendingCompareFunction<T>): AscendingSortCompareFunction<T>;
@@ -47,6 +50,10 @@ export declare function reverseCompareFn<T>(compareFn: SortDescendingCompareFunc
  * Convenience function that reverses the order of the sorted values if the order is specified descending.
  *
  * The input comparison function must be in ascending order.
+ *
+ * @param ascendingCompareFn - a comparison function that sorts in ascending order
+ * @param order - the desired sort direction; defaults to 'asc'
+ * @returns the original function if ascending, or a reversed version if descending
  */
 export declare function compareFnOrder<T>(ascendingCompareFn: AscendingSortCompareFunction<T>, order?: SortingOrder): SortCompareFunction<T>;
 /**
@@ -110,6 +117,10 @@ export declare function sortValues<T>(input: SortValuesInput<T>): T[];
 export declare function sortValuesFunctionWithSortRef<T>(sortRef: Maybe<Partial<SortCompareFunctionRef<T>>>, sortOnCopyDefault?: boolean): SortValuesFunction<T>;
 /**
  * Creates a SortValuesFunction using the input. If the input is not defined, or it's sort function is not defined, then returns mapIdentityFunction().
+ *
+ * @param sortRef - optional reference containing the sort comparison function
+ * @param sortOnCopyDefault - whether to sort on a copy by default
+ * @returns a sort function that sorts arrays, or the identity function if no sort comparison is configured
  */
 export declare function sortValuesFunctionOrMapIdentityWithSortRef<T>(sortRef: Maybe<Partial<SortCompareFunctionRef<T>>>, sortOnCopyDefault?: boolean): SortValuesFunction<T>;
 /**

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

@@ -6,6 +6,7 @@ import { type ReadStoredData } from './storage';
 export declare class StoredDataError extends BaseError {
     /**
      * Creates an instance of StoredDataError.
+     *
      * @param message Optional error message.
      */
     constructor(message?: string);
@@ -16,6 +17,7 @@ export declare class StoredDataError extends BaseError {
 export declare class DataDoesNotExistError extends StoredDataError {
     /**
      * Creates an instance of DataDoesNotExistError.
+     *
      * @param message Optional error message.
      */
     constructor(message?: string);
@@ -29,6 +31,7 @@ export declare class DataIsExpiredError<T> extends StoredDataError {
     readonly data: ReadStoredData<T>;
     /**
      * Creates an instance of DataIsExpiredError.
+     *
      * @param data The expired data, including metadata.
      * @param message Optional error message. If not provided, a default message will be used.
      */

package/src/lib/storage/storage.memory.d.ts

@@ -9,22 +9,27 @@ export declare class MemoryStorageInstance implements StorageObject {
     private _storage;
     /**
      * The number of items stored.
+     *
+     * @returns the current count of stored key-value pairs
      */
     get length(): number;
     /**
      * Returns the key at the given index.
+     *
      * @param index The index of the key to retrieve.
      * @returns The key string if found, otherwise null.
      */
     key(index: number): string;
     /**
      * Checks if a key exists in the storage.
+     *
      * @param key The key to check.
      * @returns True if the key exists, false otherwise.
      */
     hasKey(key: string): boolean;
     /**
      * Retrieves an item from storage.
+     *
      * @param key The key of the item to retrieve.
      * @returns The item string if found, otherwise null or undefined.
      */
@@ -32,12 +37,14 @@ export declare class MemoryStorageInstance implements StorageObject {
     /**
      * Sets an item in storage.
      * If the item is null or undefined, the key will be removed.
+     *
      * @param key The key of the item to set.
      * @param item The item string to store.
      */
     setItem(key: string, item: Maybe<string>): void;
     /**
      * Removes an item from storage.
+     *
      * @param key The key of the item to remove.
      */
     removeItem(key: string): void;

package/src/lib/storage/storage.object.d.ts

@@ -6,18 +6,21 @@ import { type StoredDataStorageKey } from './storage';
 export declare abstract class SimpleStorageObject {
     /**
      * Retrieves an item from storage.
+     *
      * @param key The key of the item to retrieve.
      * @returns The item string if found, otherwise null or undefined.
      */
     abstract getItem(key: StoredDataStorageKey): Maybe<string>;
     /**
      * Sets an item in storage.
+     *
      * @param key The key of the item to set.
      * @param item The item string to store. If null or undefined, the item may be removed depending on implementation.
      */
     abstract setItem(key: StoredDataStorageKey, item: Maybe<string>): void;
     /**
      * Removes an item from storage.
+     *
      * @param key The key of the item to remove.
      */
     abstract removeItem(key: StoredDataStorageKey): void;
@@ -36,6 +39,7 @@ export declare abstract class StorageObject extends SimpleStorageObject {
      * Returns the string key for the index.
      *
      * Returns null if no key available.
+     *
      * @param index The index of the key to retrieve.
      * @returns The key string if found, otherwise null.
      */
@@ -55,6 +59,7 @@ export declare abstract class FullStorageObject extends StorageObject {
     abstract readonly isAvailable: boolean;
     /**
      * Removes all items from storage.
+     *
      * @returns An array of keys that were removed.
      */
     abstract removeAll(): string[];

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

@@ -60,8 +60,11 @@ export type PrimativeKeyDencoderFunction<D extends PrimativeKey, E extends Prima
 /**
  * Default fallback factory for {@link PrimativeKeyDencoderFunction} that always returns null,
  * causing an error to be thrown for unknown values.
+ *
+ * @param _input - the unknown value to look up (ignored; always returns null)
+ * @returns always returns null to signal an unknown value
  */
-export declare const PRIMATIVE_KEY_DENCODER_VALUE: (input: unknown) => null;
+export declare const PRIMATIVE_KEY_DENCODER_VALUE: (_input: unknown) => null;
 /**
  * Creates a new {@link PrimativeKeyDencoderFunction} that can bidirectionally encode/decode
  * primitive key values based on the configured value pairs.

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

@@ -28,21 +28,37 @@ export type ContentTypeMimeType = string;
  * This is a non-exhaustive list of common image types.
  */
 export type ImageFileExtension = 'jpeg' | 'jpg' | 'png' | 'webp' | 'gif' | 'svg' | 'raw' | 'heif' | 'tiff';
-/** MIME type for JPEG images. */
+/**
+ * MIME type for JPEG images.
+ */
 export declare const JPEG_MIME_TYPE: MimeTypeWithoutParameters;
-/** MIME type for PNG images. */
+/**
+ * MIME type for PNG images.
+ */
 export declare const PNG_MIME_TYPE: MimeTypeWithoutParameters;
-/** MIME type for WebP images. */
+/**
+ * MIME type for WebP images.
+ */
 export declare const WEBP_MIME_TYPE: MimeTypeWithoutParameters;
-/** MIME type for GIF images. */
+/**
+ * MIME type for GIF images.
+ */
 export declare const GIF_MIME_TYPE: MimeTypeWithoutParameters;
-/** MIME type for HEIF images. */
+/**
+ * MIME type for HEIF images.
+ */
 export declare const HEIF_MIME_TYPE: MimeTypeWithoutParameters;
-/** MIME type for TIFF images. */
+/**
+ * MIME type for TIFF images.
+ */
 export declare const TIFF_MIME_TYPE: MimeTypeWithoutParameters;
-/** MIME type for SVG images. */
+/**
+ * MIME type for SVG images.
+ */
 export declare const SVG_MIME_TYPE: MimeTypeWithoutParameters;
-/** MIME type for RAW images. */
+/**
+ * MIME type for RAW images.
+ */
 export declare const RAW_MIME_TYPE: MimeTypeWithoutParameters;
 /**
  * Maps image file extensions to their corresponding MIME types.
@@ -72,25 +88,45 @@ export declare function imageFileExtensionForMimeType(mimeType: Maybe<MimeTypeWi
  * Non-exhaustive list of common document file extensions.
  */
 export type DocumentFileExtension = 'pdf' | 'docx' | 'xlsx' | 'txt' | 'csv' | 'html' | 'xml' | 'json' | 'yaml' | 'md';
-/** MIME type for PDF documents. */
+/**
+ * MIME type for PDF documents.
+ */
 export declare const PDF_MIME_TYPE: MimeTypeWithoutParameters;
-/** MIME type for DOCX (Word) documents. */
+/**
+ * MIME type for DOCX (Word) documents.
+ */
 export declare const DOCX_MIME_TYPE: MimeTypeWithoutParameters;
-/** MIME type for XLSX (Excel) spreadsheets. */
+/**
+ * MIME type for XLSX (Excel) spreadsheets.
+ */
 export declare const XLSX_MIME_TYPE: MimeTypeWithoutParameters;
-/** MIME type for plain text files. */
+/**
+ * MIME type for plain text files.
+ */
 export declare const TXT_MIME_TYPE: MimeTypeWithoutParameters;
-/** MIME type for CSV files. */
+/**
+ * MIME type for CSV files.
+ */
 export declare const CSV_MIME_TYPE: MimeTypeWithoutParameters;
-/** MIME type for HTML files. */
+/**
+ * MIME type for HTML files.
+ */
 export declare const HTML_MIME_TYPE: MimeTypeWithoutParameters;
-/** MIME type for XML files. */
+/**
+ * MIME type for XML files.
+ */
 export declare const XML_MIME_TYPE: MimeTypeWithoutParameters;
-/** MIME type for JSON files. */
+/**
+ * MIME type for JSON files.
+ */
 export declare const JSON_MIME_TYPE: MimeTypeWithoutParameters;
-/** MIME type for YAML files. */
+/**
+ * MIME type for YAML files.
+ */
 export declare const YAML_MIME_TYPE: MimeTypeWithoutParameters;
-/** MIME type for Markdown files. */
+/**
+ * MIME type for Markdown files.
+ */
 export declare const MARKDOWN_MIME_TYPE: MimeTypeWithoutParameters;
 /**
  * Maps document file extensions to their corresponding MIME types.
@@ -120,7 +156,9 @@ export declare function documentFileExtensionForMimeType(mimeType: Maybe<MimeTyp
  * Non-exhaustive list of common application file extensions.
  */
 export type ApplicationFileExtension = 'zip';
-/** MIME type for ZIP archive files. */
+/**
+ * MIME type for ZIP archive files.
+ */
 export declare const ZIP_FILE_MIME_TYPE: MimeTypeWithoutParameters;
 /**
  * Maps application file extensions to their corresponding MIME types.

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

@@ -2,18 +2,21 @@ import { type MapFunction } from '../value/map';
 import { type Maybe } from '../value/maybe.type';
 /**
  * Trims leading and trailing whitespace from a string.
+ *
  * @param input The string to trim.
  * @returns The trimmed string.
  */
 export declare function stringTrimFunction(input: string): string;
 /**
  * Converts a string to uppercase.
+ *
  * @param input The string to convert.
  * @returns The uppercase string.
  */
 export declare function stringToUppercaseFunction(input: string): string;
 /**
  * Converts a string to lowercase.
+ *
  * @param input The string to convert.
  * @returns The lowercase string.
  */
@@ -56,7 +59,9 @@ export type TransformStringFunctionConfig<S extends string = string> = {
  * @template S The specific string type, defaults to `string`.
  */
 export interface TransformStringFunctionConfigRef<S extends string = string> {
-    /** The string transformation configuration. */
+    /**
+     * The string transformation configuration.
+     */
     readonly transform: TransformStringFunctionConfig<S>;
 }
 /**
@@ -111,6 +116,7 @@ export declare function addPrefix(prefix: string, input: string): string;
 export type AddPrefixFunction = (input: string) => string;
 /**
  * Creates a function that adds a configured prefix to the input string if it does not exist on that string.
+ *
  * @param prefix The prefix to add.
  * @returns A function that adds the prefix to a string.
  */
@@ -121,6 +127,7 @@ export declare function addPrefixFunction(prefix: string): AddPrefixFunction;
 export type AddSuffixFunction = TransformStringFunction;
 /**
  * Adds a suffix to a string if it does not already end with that suffix.
+ *
  * @param suffix The suffix to add.
  * @param input The string to modify.
  * @returns The modified string.
@@ -128,6 +135,7 @@ export type AddSuffixFunction = TransformStringFunction;
 export declare function addSuffix(suffix: string, input: string): string;
 /**
  * Creates a function that adds a configured suffix to the input string if it does not exist on that string.
+ *
  * @param suffix The suffix to add.
  * @returns A function that adds the suffix to a string.
  */
@@ -138,6 +146,7 @@ export declare function addSuffixFunction(suffix: string): AddSuffixFunction;
 export type PadStartFunction = TransformStringFunction;
 /**
  * Pads the start of a string to a minimum length.
+ *
  * @param minLength The minimum length of the string.
  * @param padCharacter The character to use for padding.
  * @returns A function that pads the start of a string.

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

@@ -65,7 +65,9 @@ export type SplitStringTreeRoot<M = unknown> = Pick<SplitStringTree<M>, 'childre
  * @template M - The type of metadata attached to tree nodes.
  */
 export interface SplitStringTreeFactoryInput<M = unknown> extends Pick<AddToSplitStringTreeInputValueWithMeta<M>, 'leafMeta' | 'nodeMeta'> {
-    /** One or more string values to split and add to the tree. */
+    /**
+     * One or more string values to split and add to the tree.
+     */
     readonly values: ArrayOrValue<SplitStringTreeNodeString>;
 }
 /**
@@ -95,11 +97,17 @@ export declare function splitStringTreeFactory<M = unknown>(config: SplitStringT
  * @template M - The type of metadata attached to tree nodes.
  */
 export interface ApplySplitStringTreeWithMultipleValuesInput<M = unknown> {
-    /** The entries to add to the tree, each potentially with different metadata. */
+    /**
+     * The entries to add to the tree, each potentially with different metadata.
+     */
     readonly entries: SplitStringTreeFactoryInput<M>[];
-    /** The factory to use for building the tree. */
+    /**
+     * The factory to use for building the tree.
+     */
     readonly factory: SplitStringTreeFactory<M>;
-    /** An optional existing tree to extend rather than creating a new one. */
+    /**
+     * An optional existing tree to extend rather than creating a new one.
+     */
     readonly existing?: SplitStringTree<M>;
 }
 /**
@@ -115,7 +123,9 @@ export declare function applySplitStringTreeWithMultipleValues<M = unknown>(inpu
  * @template M - The type of metadata attached to tree nodes.
  */
 export interface AddToSplitStringTreeInputValueWithMeta<M = unknown> {
-    /** The string value to split and insert into the tree. */
+    /**
+     * The string value to split and insert into the tree.
+     */
     readonly value: SplitStringTreeNodeString;
     /**
      * The meta value to merge/attach to each node in the tree
@@ -132,7 +142,9 @@ export interface AddToSplitStringTreeInputValueWithMeta<M = unknown> {
  * @template M - The type of metadata attached to tree nodes.
  */
 export interface AddToSplitStringTreeInputConfig<M = unknown> {
-    /** The separator character used to split string values into tree path segments. */
+    /**
+     * The separator character used to split string values into tree path segments.
+     */
     readonly separator: string;
     /**
      * Used for merging the meta values of two nodes.