@dereekb/util 13.0.7 → 13.2.0

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

@@ -1,7 +1,16 @@
 import { type ArrayOrValue } from '../array/array';
 import { type DecisionFunction } from '../value/decision';
+/**
+ * Result describing the first and last index positions of a character within a string.
+ */
 export interface FirstAndLastCharacterOccurrence {
+    /**
+     * Index of the first occurrence, or -1 if the character was not found.
+     */
     readonly first: number | -1;
+    /**
+     * Index of the last occurrence, or -1 if the character was not found.
+     */
     readonly last: number | -1;
     /**
      * Total number of occurrences.
@@ -9,15 +18,20 @@ export interface FirstAndLastCharacterOccurrence {
     readonly occurences: number;
 }
 /**
- * Find the first and last occurence of the input character in the input string.
+ * Finds the first and last occurrence of a single character within the input string.
  *
- * @param input string to find the character occurrences
- * @param find character to find
- * @returns
+ * @param input - string to search through
+ * @param find - single character to find
+ * @returns an object containing the first index, last index, and total occurrence count
+ * @throws Error if find is not exactly one character long
  */
 export declare function firstAndLastCharacterOccurrence(input: string, find: string): FirstAndLastCharacterOccurrence;
 /**
- * Returns true if the input string contains the character (or string) to find.
+ * Checks whether the input string contains the given substring.
+ *
+ * @param input - string to search within
+ * @param find - substring to search for
+ * @returns true if the substring is found within the input
  */
 export declare function stringContains(input: string, find: string): boolean;
 /**
@@ -25,48 +39,49 @@ export declare function stringContains(input: string, find: string): boolean;
  */
 export type ReplaceLastCharacterIfIsFunction = (input: string) => string;
 /**
- * Replaces the last character with the replacement string if it is any of the input values.
+ * Creates a function that replaces the last character of a string with the replacement string
+ * if that character matches any of the specified values.
  *
- * @param input
- * @param replacement
- * @param is
- * @returns
+ * @param replacement - string to substitute for the last character
+ * @param is - character(s) that trigger the replacement
+ * @returns a function that conditionally replaces the last character
  */
 export declare function replaceLastCharacterIfIsFunction(replacement: string, is: ArrayOrValue<string>): ReplaceLastCharacterIfIsFunction;
 /**
- * Replaces the last character with the replacement string if the decision is true.
+ * Replaces the last character of a string with the replacement if the decision function returns true for that character.
  *
- * @param input
- * @param index
- * @param replacement
- * @returns
+ * @param input - string to potentially modify
+ * @param replacement - string to substitute for the last character
+ * @param decision - function that determines whether the last character should be replaced
+ * @returns the modified string, or the original if the decision is false or the string is empty
  */
 export declare function replaceLastCharacterIf(input: string, replacement: string, decision: DecisionFunction<string>): string;
 /**
- * Replaces the character at the given index with the replacement string if the decision is true.
+ * Replaces the character at the given index with the replacement string if the decision function returns true for that character.
  *
- * @param input
- * @param index
- * @param replacement
- * @returns
+ * @param input - string to potentially modify
+ * @param index - character index to evaluate
+ * @param replacement - string to substitute at the index
+ * @param decision - function that determines whether the character should be replaced
+ * @returns the modified string, or the original if the decision is false
  */
 export declare function replaceCharacterAtIndexIf(input: string, index: number, replacement: string, decision: DecisionFunction<string>): string;
 /**
  * Replaces the character at the given index with the replacement string.
  *
- * @param input
- * @param index
- * @param replacement
- * @returns
+ * @param input - string to modify
+ * @param index - character index to replace
+ * @param replacement - string to substitute at the index
+ * @returns the string with the character at the index replaced
  */
 export declare function replaceCharacterAtIndexWith(input: string, index: number, replacement: string): string;
 /**
- * Splits the input string at the given character index.
+ * Splits the input string into two parts at the given character index.
  *
- * @param input
- * @param index
- * @param replacement
- * @returns
+ * @param input - string to split
+ * @param index - character index at which to split
+ * @param inclusive - if true, the character at the index is included in the tail; if false (default), it is excluded from both parts
+ * @returns a tuple of [head, tail] substrings
  */
 export declare function splitStringAtIndex(input: string, index: number, inclusive?: boolean): [string, string];
 /**
@@ -84,11 +99,10 @@ export declare const UTF_8_START_CHARACTER = "\0";
  */
 export declare const UTF_PRIVATE_USAGE_AREA_START = "\uF8FF";
 /**
- * Takes in a string and returns a Record that has the index value mapped to the property of the character.
- *
- * The latest character index is used in collision cases.
+ * Creates a lookup record mapping each character in the input string to its index position.
+ * In case of duplicate characters, the last occurrence's index is used.
  *
- * @param chars
- * @returns
+ * @param chars - string whose characters become keys in the record
+ * @returns a record mapping each character to its index in the input string
  */
 export declare function stringCharactersToIndexRecord(chars: string): Record<string, number>;

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

@@ -7,25 +7,46 @@ import { type Maybe } from '../value/maybe.type';
 export type PrimativeKeyDencoderValueMap<D extends PrimativeKey, E extends PrimativeKey> = {
     [key in E]: D;
 };
+/**
+ * A tuple pairing an encoded value to its decoded counterpart.
+ */
 export type PrimativeKeyDencoderTuple<D extends PrimativeKey, E extends PrimativeKey> = [E, D];
+/**
+ * An array of {@link PrimativeKeyDencoderTuple} values.
+ */
 export type PrimativeKeyDencoderTupleArray<D extends PrimativeKey, E extends PrimativeKey> = PrimativeKeyDencoderTuple<D, E>[];
 /**
  * PrimativeKeyDencoder values. No key or value should be repeated.
  */
 export type PrimativeKeyDencoderValues<D extends PrimativeKey, E extends PrimativeKey> = PrimativeKeyDencoderTupleArray<D, E> | PrimativeKeyDencoderValueMap<D, E>;
+/**
+ * A bidirectional Map that maps both encoded-to-decoded and decoded-to-encoded values.
+ * Also carries the original tuple array used to construct it.
+ */
 export type PrimativeKeyDencoderMap<D extends PrimativeKey, E extends PrimativeKey> = Map<D | E, E | D> & {
     readonly _tuples: PrimativeKeyDencoderTupleArray<D, E>;
 };
 /**
- * Creates a Map of the PrimativeKeyDencoder values.
- *
- * If any repeat values are found, an error will be thrown.
+ * Creates a bidirectional {@link PrimativeKeyDencoderMap} from the given values,
+ * allowing lookup in both directions (encoded-to-decoded and decoded-to-encoded).
  *
- * @param values
+ * @param values - encoder/decoder value pairs as tuples or a map object
+ * @returns a bidirectional Map for encoding/decoding
+ * @throws Error if any key or value is repeated
  */
 export declare function primativeKeyDencoderMap<D extends PrimativeKey, E extends PrimativeKey>(values: PrimativeKeyDencoderValues<D, E>): PrimativeKeyDencoderMap<D, E>;
+/**
+ * Configuration for creating a {@link PrimativeKeyDencoderFunction}.
+ */
 export interface PrimativeKeyDencoderConfig<D extends PrimativeKey, E extends PrimativeKey> {
+    /**
+     * The encode/decode value pairs.
+     */
     readonly values: PrimativeKeyDencoderValues<D, E>;
+    /**
+     * Optional factory to produce a fallback value when a lookup misses.
+     * If not provided or if it returns null, an error is thrown for unknown values.
+     */
     readonly defaultValue?: FactoryWithRequiredInput<D | E, D | E>;
 }
 /**
@@ -36,13 +57,23 @@ export interface PrimativeKeyDencoderConfig<D extends PrimativeKey, E extends Pr
 export type PrimativeKeyDencoderFunction<D extends PrimativeKey, E extends PrimativeKey> = ((encodedValue: E) => D) & ((decodedValue: D) => E) & ((encodedValues: E[]) => D[]) & ((decodedValues: D[]) => E[]) & {
     readonly _map: PrimativeKeyDencoderMap<D, E>;
 };
+/**
+ * Default fallback factory for {@link PrimativeKeyDencoderFunction} that always returns null,
+ * causing an error to be thrown for unknown values.
+ */
 export declare const PRIMATIVE_KEY_DENCODER_VALUE: (input: unknown) => null;
 /**
- * Creates a new PrimiativeKeyDencoder.
+ * Creates a new {@link PrimativeKeyDencoderFunction} that can bidirectionally encode/decode
+ * primitive key values based on the configured value pairs.
+ *
+ * @param config - configuration with value pairs and optional default fallback
+ * @returns a function that encodes or decodes single values or arrays
+ * @throws Error if a single value lookup produces a null result and no default handles it
  */
 export declare function primativeKeyDencoder<D extends PrimativeKey, E extends PrimativeKey>(config: PrimativeKeyDencoderConfig<D, E>): PrimativeKeyDencoderFunction<D, E>;
 /**
- * Used to decode
+ * Configuration for creating a {@link PrimativeKeyStringDencoderFunction} that can encode/decode
+ * between a compact string representation and an array of values.
  */
 export interface PrimativeKeyStringDencoderConfig<D extends PrimativeKey, E extends PrimativeKey> {
     /**
@@ -61,10 +92,15 @@ export interface PrimativeKeyStringDencoderConfig<D extends PrimativeKey, E exte
  */
 export type PrimativeKeyStringDencoderFunction<D extends PrimativeKey, E extends PrimativeKey, S extends string = string> = ((encodedValues: S) => (E | D)[]) & ((decodedValues: (E | D)[]) => S);
 /**
- * Creates a new PrimativeKeyStringDencoderFunction.
+ * Creates a new {@link PrimativeKeyStringDencoderFunction} that converts between a compact string
+ * and an array of encoded/decoded values.
+ *
+ * When no splitter is defined, all encoded values must be exactly one character long so the string
+ * can be split character-by-character.
  *
- * @param config
- * @returns
+ * @param config - configuration with dencoder and optional splitter
+ * @returns a bidirectional function for string-to-array and array-to-string conversion
+ * @throws Error if encoded values contain the splitter character, or if values exceed one character when no splitter is defined
  */
 export declare function primativeKeyStringDencoder<D extends PrimativeKey, E extends PrimativeKey>(config: PrimativeKeyStringDencoderConfig<D, E>): PrimativeKeyStringDencoderFunction<D, E>;
 /**
@@ -124,24 +160,59 @@ export interface NumberStringDencoder {
      */
     decodeNumber(encodedNumber: NumberStringDencoderString): NumberStringDencoderNumber;
 }
+/**
+ * Configuration for creating a {@link NumberStringDencoder}.
+ */
 export interface NumberStringDencoderConfig {
     /**
      * Optional negative prefix character. Should not be in the digits.
      */
     readonly negativePrefix?: Maybe<string>;
+    /**
+     * The character set used for encoding. Length must be a power of 2.
+     */
     readonly digits: NumberStringDencoderDigits;
 }
 /**
- * Creates an integer-type NumberStringDencoder.
+ * Creates an integer-type {@link NumberStringDencoder} that can encode and decode integers
+ * using a custom character set (digit alphabet).
  *
- * If the config does not include a negative prefix, any negative number will be treated like a positive number.
+ * If the config does not include a negative prefix, negative numbers lose their sign during encoding.
  *
- * @param config
- * @returns
+ * @param config - configuration with digit alphabet and optional negative prefix
+ * @returns a NumberStringDencoder capable of encoding/decoding integers
  */
 export declare function numberStringDencoder(config: NumberStringDencoderConfig): NumberStringDencoder;
+/**
+ * Pre-configured 64-character {@link NumberStringDencoder} using the default digit alphabet and negative prefix.
+ */
 export declare const NUMBER_STRING_DENCODER_64: NumberStringDencoder;
+/**
+ * A bidirectional function that encodes a number to a string or decodes a string to a number,
+ * depending on the type of the input.
+ */
 export type NumberStringDencoderFunction = ((input: NumberStringDencoderString) => NumberStringDencoderNumber) & ((input: NumberStringDencoderNumber) => NumberStringDencoderString);
+/**
+ * Creates a {@link NumberStringDencoderFunction} from the given dencoder.
+ * The returned function auto-detects the input type: numbers are encoded, strings are decoded.
+ *
+ * @param dencoder - the NumberStringDencoder to wrap
+ * @returns a bidirectional encode/decode function
+ */
 export declare function numberStringDencoderFunction(dencoder: NumberStringDencoder): NumberStringDencoderFunction;
+/**
+ * Creates a function that always returns the encoded string form of the input.
+ * Numbers are encoded; strings are passed through as-is.
+ *
+ * @param dencoder - the NumberStringDencoder to use for encoding
+ * @returns a function that normalizes input to an encoded string
+ */
 export declare function numberStringDencoderEncodedStringValueFunction(dencoder: NumberStringDencoder): (input: NumberStringDencoderString | NumberStringDencoderNumber) => NumberStringDencoderString;
+/**
+ * Creates a function that always returns the decoded number form of the input.
+ * Strings are decoded; numbers are passed through as-is.
+ *
+ * @param dencoder - the NumberStringDencoder to use for decoding
+ * @returns a function that normalizes input to a decoded number
+ */
 export declare function numberStringDencoderDecodedNumberValueFunction(dencoder: NumberStringDencoder): (input: NumberStringDencoderString | NumberStringDencoderNumber) => NumberStringDencoderNumber;

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

@@ -1,20 +1,29 @@
 import { type FactoryWithInput, type Factory, type FactoryWithRequiredInput } from '../getter';
 import { type Maybe } from '../value';
 import { type TransformStringFunctionConfig } from './transform';
+/**
+ * A factory that produces a string value with no input.
+ */
 export type StringFactory<K extends string = string> = Factory<K>;
+/**
+ * A function that converts a value of type T to a string.
+ */
 export type ToStringFunction<T, K extends string = string> = FactoryWithRequiredInput<K, T>;
 /**
- * Wraps another factory with a ToStringFactory function to generate strings from the original factory.
+ * Wraps an existing factory with a {@link ToStringFunction} to produce strings from the factory's output.
  *
- * @param factory
- * @param toStringFunction
- * @returns
+ * @param factory - the original value factory
+ * @param toStringFunction - function to convert the factory's output to a string
+ * @returns a new factory that produces string values
  */
 export declare function stringFactoryFromFactory<T, K extends string = string>(factory: Factory<T>, toStringFunction: ToStringFunction<T, K>): StringFactory<K>;
 /**
  * A factory that returns a string based on the input date.
  */
 export type StringFromDateFactory = FactoryWithInput<string, Maybe<Date>>;
+/**
+ * Configuration for creating a {@link StringFromDateFactory}.
+ */
 export interface StringFromDateConfig {
     /**
      * The number of digits to return from the end of the generated string.

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

@@ -26,16 +26,17 @@ export type SpaceSeparatedCssStyles = string;
  */
 export type CssClassesArray = ArrayOrValue<ArrayOrValue<SpaceSeparatedCssClasses>>;
 /**
- * Joins together various array of classes and only keeps the unique values.
+ * Joins together various arrays of CSS classes into a single space-separated string of unique class names.
  *
- * @param cssClasses
- * @returns
+ * @param cssClasses - one or more CSS class values or arrays of class values
+ * @returns a space-separated string of unique CSS class names, or an empty string if input is null/undefined
  */
 export declare function spaceSeparatedCssClasses(cssClasses: Maybe<CssClassesArray>): SpaceSeparatedCssClasses;
 /**
- * Joins together various array of classes and returns the set of unique CSS classes.
+ * Parses and deduplicates CSS classes from various array/string inputs into a Set.
+ * Space-separated class strings are split into individual class names.
  *
- * @param cssClasses
- * @returns
+ * @param cssClasses - one or more CSS class values or arrays of class values
+ * @returns a Set of unique CSS class names, or an empty Set if input is null/undefined
  */
 export declare function cssClassesSet(cssClasses: Maybe<CssClassesArray>): Set<CssClass>;

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

@@ -28,35 +28,77 @@ 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. */
 export declare const JPEG_MIME_TYPE: MimeTypeWithoutParameters;
+/** MIME type for PNG images. */
 export declare const PNG_MIME_TYPE: MimeTypeWithoutParameters;
+/** MIME type for WebP images. */
 export declare const WEBP_MIME_TYPE: MimeTypeWithoutParameters;
+/** MIME type for GIF images. */
 export declare const GIF_MIME_TYPE: MimeTypeWithoutParameters;
+/** MIME type for HEIF images. */
 export declare const HEIF_MIME_TYPE: MimeTypeWithoutParameters;
+/** MIME type for TIFF images. */
 export declare const TIFF_MIME_TYPE: MimeTypeWithoutParameters;
+/** MIME type for SVG images. */
 export declare const SVG_MIME_TYPE: MimeTypeWithoutParameters;
+/** MIME type for RAW images. */
 export declare const RAW_MIME_TYPE: MimeTypeWithoutParameters;
+/**
+ * Maps image file extensions to their corresponding MIME types.
+ */
 export declare const IMAGE_FILE_EXTENSION_TO_MIME_TYPES_RECORD: Record<ImageFileExtension, MimeTypeWithoutParameters>;
+/**
+ * Maps image MIME types back to their corresponding file extensions.
+ */
 export declare const IMAGE_MIME_TYPES_TO_FILE_EXTENSIONS_RECORD: Record<MimeTypeWithoutParameters, ImageFileExtension>;
 /**
- * Returns the mimetype for the given image type, or undefined if the type is not known.
+ * Returns the MIME type for the given image file extension, or undefined if the extension is not recognized.
+ *
+ * @param extension - the image file extension to look up
+ * @returns the corresponding MIME type, or undefined if the extension is not known
  */
 export declare function mimeTypeForImageFileExtension(extension: ImageFileExtension): MimeTypeWithoutParameters;
 export declare function mimeTypeForImageFileExtension(extension: SlashPathTypedFileExtension): Maybe<MimeTypeWithoutParameters>;
 export declare function mimeTypeForImageFileExtension(extension: Maybe<ImageFileExtension | SlashPathTypedFileExtension>): Maybe<MimeTypeWithoutParameters>;
+/**
+ * Returns the image file extension for the given MIME type, or undefined if the MIME type is not a known image type.
+ *
+ * @param mimeType - the MIME type to look up
+ * @returns the corresponding image file extension, or undefined if not recognized
+ */
 export declare function imageFileExtensionForMimeType(mimeType: Maybe<MimeTypeWithoutParameters>): Maybe<ImageFileExtension>;
+/**
+ * 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. */
 export declare const PDF_MIME_TYPE: MimeTypeWithoutParameters;
+/** MIME type for DOCX (Word) documents. */
 export declare const DOCX_MIME_TYPE: MimeTypeWithoutParameters;
+/** MIME type for XLSX (Excel) spreadsheets. */
 export declare const XLSX_MIME_TYPE: MimeTypeWithoutParameters;
+/** MIME type for plain text files. */
 export declare const TXT_MIME_TYPE: MimeTypeWithoutParameters;
+/** MIME type for CSV files. */
 export declare const CSV_MIME_TYPE: MimeTypeWithoutParameters;
+/** MIME type for HTML files. */
 export declare const HTML_MIME_TYPE: MimeTypeWithoutParameters;
+/** MIME type for XML files. */
 export declare const XML_MIME_TYPE: MimeTypeWithoutParameters;
+/** MIME type for JSON files. */
 export declare const JSON_MIME_TYPE: MimeTypeWithoutParameters;
+/** MIME type for YAML files. */
 export declare const YAML_MIME_TYPE: MimeTypeWithoutParameters;
+/** MIME type for Markdown files. */
 export declare const MARKDOWN_MIME_TYPE: MimeTypeWithoutParameters;
+/**
+ * Maps document file extensions to their corresponding MIME types.
+ */
 export declare const DOCUMENT_FILE_EXTENSION_TO_MIME_TYPES_RECORD: Record<DocumentFileExtension, MimeTypeWithoutParameters>;
+/**
+ * Maps document MIME types back to their corresponding file extensions.
+ */
 export declare const DOCUMENT_MIME_TYPES_TO_FILE_EXTENSIONS_RECORD: Record<MimeTypeWithoutParameters, DocumentFileExtension>;
 /**
  * Returns the mimetype for the given document file extension, or undefined if the extension is not known/recognized.
@@ -74,9 +116,19 @@ export declare function mimeTypeForDocumentFileExtension(extension: Maybe<Docume
  * @returns The document file extension for the given mimetype, or undefined if the mimetype is not known.
  */
 export declare function documentFileExtensionForMimeType(mimeType: Maybe<MimeTypeWithoutParameters>): Maybe<DocumentFileExtension>;
+/**
+ * Non-exhaustive list of common application file extensions.
+ */
 export type ApplicationFileExtension = 'zip';
+/** MIME type for ZIP archive files. */
 export declare const ZIP_FILE_MIME_TYPE: MimeTypeWithoutParameters;
+/**
+ * Maps application file extensions to their corresponding MIME types.
+ */
 export declare const APPLICATION_FILE_EXTENSION_TO_MIME_TYPES_RECORD: Record<ApplicationFileExtension, MimeTypeWithoutParameters>;
+/**
+ * Maps application MIME types back to their corresponding file extensions.
+ */
 export declare const APPLICATION_MIME_TYPES_TO_FILE_EXTENSIONS_RECORD: Record<MimeTypeWithoutParameters, ApplicationFileExtension>;
 /**
  * Returns the mimetype for the given application file extension, or undefined if the extension is not known/recognized.
@@ -87,6 +139,12 @@ export declare const APPLICATION_MIME_TYPES_TO_FILE_EXTENSIONS_RECORD: Record<Mi
 export declare function mimeTypeForApplicationFileExtension(extension: ApplicationFileExtension): MimeTypeWithoutParameters;
 export declare function mimeTypeForApplicationFileExtension(extension: SlashPathTypedFileExtension): Maybe<MimeTypeWithoutParameters>;
 export declare function mimeTypeForApplicationFileExtension(extension: Maybe<ApplicationFileExtension | SlashPathTypedFileExtension>): Maybe<MimeTypeWithoutParameters>;
+/**
+ * Returns the application file extension for the given MIME type, or undefined if the MIME type is not a known application type.
+ *
+ * @param mimeType - the MIME type to look up
+ * @returns the corresponding application file extension, or undefined if not recognized
+ */
 export declare function applicationFileExtensionForMimeType(mimeType: Maybe<MimeTypeWithoutParameters>): Maybe<ApplicationFileExtension>;
 /**
  * List of known file extensions supported by dbx-components.
@@ -103,6 +161,12 @@ export type DbxComponentsKnownFileExtension = ImageFileExtension | DocumentFileE
 export declare function mimeTypeForFileExtension(extension: DbxComponentsKnownFileExtension): MimeTypeWithoutParameters;
 export declare function mimeTypeForFileExtension(extension: SlashPathTypedFileExtension): Maybe<MimeTypeWithoutParameters>;
 export declare function mimeTypeForFileExtension(extension: Maybe<DbxComponentsKnownFileExtension | SlashPathTypedFileExtension>): Maybe<MimeTypeWithoutParameters>;
+/**
+ * Returns the file extension for the given MIME type by checking image, document, and application types in order.
+ *
+ * @param mimeType - the MIME type to look up
+ * @returns the corresponding file extension, or undefined if the MIME type is not recognized
+ */
 export declare function fileExtensionForMimeType(mimeType: Maybe<MimeTypeWithoutParameters>): Maybe<DbxComponentsKnownFileExtension>;
 /**
  * A content disposition string, which is used to determine how the browser should show the target content.

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

@@ -27,6 +27,12 @@ export type CharacterPrefixString<P extends CharacterPrefix = '', T extends stri
  * A string that has a known suffix.
  */
 export type CharacterSuffixString<S extends CharacterSuffix = '', T extends string = string> = CharacterPrefixSuffixString<'', S, T>;
+/**
+ * Configuration for creating a {@link CharacterPrefixSuffixInstance} that manages adding and removing prefix/suffix strings.
+ *
+ * @template P - The prefix string type.
+ * @template S - The suffix string type.
+ */
 export interface CharacterPrefixSuffixInstanceConfiguration<P extends CharacterPrefix = '', S extends CharacterSuffix = ''> {
     /**
      * The prefix characters to add/remove to/from the start of the string.
@@ -45,28 +51,36 @@ export interface CharacterPrefixSuffixInstanceConfiguration<P extends CharacterP
      */
     readonly suffixEmptyString?: boolean;
 }
+/**
+ * Instance that can add or remove a configured prefix and/or suffix from strings.
+ *
+ * @template P - The prefix string type.
+ * @template S - The suffix string type.
+ */
 export interface CharacterPrefixSuffixInstance<P extends CharacterPrefix = '', S extends CharacterSuffix = ''> extends CharacterPrefixSuffixInstanceConfiguration<P, S> {
     /**
-     * Adds the prefix and suffix to the input string.
+     * Adds the prefix and suffix to the input string. Cleans any existing prefix/suffix before adding.
      *
-     * @param input
+     * @param input - The string to prefix and suffix.
+     * @returns The string with prefix and suffix applied.
      */
     prefixSuffixString(input: ''): string;
     prefixSuffixString<T extends string>(input: T | CharacterPrefixSuffixString<P, S, T> | CharacterPrefixString<P, T> | CharacterSuffixString<S, T>): CharacterPrefixSuffixString<P, S, T>;
     prefixSuffixString(input: string): CharacterPrefixSuffixString<P, S>;
     /**
-     * Removes the prefix and suffix from the input string.
+     * Removes the prefix and suffix from the input string, stripping repeated occurrences.
      *
-     * @param input
+     * @param input - The string to clean.
+     * @returns The string with prefix and suffix removed.
      */
     cleanString<T extends string>(input: T | CharacterPrefixSuffixString<P, S, T> | CharacterPrefixString<P, T> | CharacterSuffixString<S, T>): T;
     cleanString(input: string): string;
 }
 /**
- * Creates a CharacterPrefixSuffixInstance
+ * Creates a {@link CharacterPrefixSuffixInstance} that can add or remove configured prefix/suffix strings.
  *
- * @param config
- * @returns
+ * @param config - Configuration specifying the prefix, suffix, and empty string behavior.
+ * @returns A new instance for managing prefix/suffix operations on strings.
  */
 export declare function characterPrefixSuffixInstance<P extends CharacterPrefix = '', S extends CharacterSuffix = ''>(config: CharacterPrefixSuffixInstanceConfiguration<P, S>): CharacterPrefixSuffixInstance<P, S>;
 /**

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

@@ -1,11 +1,14 @@
 /**
- * A record where the keys and values are strings.
+ * A record where both keys and values are typed strings.
+ *
+ * @template K - The key string type.
+ * @template V - The value string type.
  */
 export type StringRecord<K extends string, V extends string> = Record<K, V>;
 /**
- * Inverts a string record, inverting the key and value of each entry in the record.
+ * Inverts a string record by swapping each entry's key and value.
  *
- * @param record
- * @returns
+ * @param record - The record to invert.
+ * @returns A new record with the original values as keys and the original keys as values.
  */
 export declare function invertStringRecord<K extends string, V extends string>(record: StringRecord<K, V>): StringRecord<V, K>;