@dereekb/util 13.11.14 → 13.11.15

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

@@ -20,18 +20,18 @@ export interface FirstAndLastCharacterOccurrence {
 /**
  * Finds the first and last occurrence of a single character within the input string.
  *
- * @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
+ * @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;
 /**
  * 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
+ * @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;
 /**
@@ -42,53 +42,54 @@ export type ReplaceLastCharacterIfIsFunction = (input: string) => string;
  * 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 replacement - String to substitute for the last character.
+ * @param is - Character(s) that trigger the replacement.
+ * @returns Conditionally replaces the last character.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, replace, last, character, conditional, factory
  * @dbxUtilRelated replace-last-character-if, replace-character-at-index-if
  *
- * @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
  * @__NO_SIDE_EFFECTS__
  */
 export declare function replaceLastCharacterIfIsFunction(replacement: string, is: ArrayOrValue<string>): ReplaceLastCharacterIfIsFunction;
 /**
  * Replaces the last character of a string with the replacement if the decision function returns true for that character.
  *
- * @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
+ * @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 function returns true for that character.
  *
- * @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
+ * @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 - 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
+ * @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 into two parts at the given character index.
  *
- * @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
+ * @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];
 /**
@@ -109,7 +110,7 @@ export declare const UTF_PRIVATE_USAGE_AREA_START = "\uF8FF";
  * 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 - string whose characters become keys in the record
- * @returns a record mapping each character to its index in the input string
+ * @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

@@ -30,9 +30,9 @@ export type PrimativeKeyDencoderMap<D extends PrimativeKey, E extends PrimativeK
  * Creates a bidirectional {@link PrimativeKeyDencoderMap} from the given values,
  * allowing lookup in both directions (encoded-to-decoded and decoded-to-encoded).
  *
- * @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
+ * @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>;
 /**
@@ -61,23 +61,24 @@ 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
+ * @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;
 /**
  * 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 Encodes or decodes single values or arrays.
+ * @throws {Error} If a single value lookup produces a null result and no default handles it.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, encode, decode, dencoder, bidirectional, factory, primitive
  * @dbxUtilRelated primative-key-dencoder-map, primative-key-string-dencoder
  *
- * @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
  * @__NO_SIDE_EFFECTS__
  */
 export declare function primativeKeyDencoder<D extends PrimativeKey, E extends PrimativeKey>(config: PrimativeKeyDencoderConfig<D, E>): PrimativeKeyDencoderFunction<D, E>;
@@ -108,15 +109,16 @@ export type PrimativeKeyStringDencoderFunction<D extends PrimativeKey, E extends
  * 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 - 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.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, encode, decode, dencoder, splitter, factory, primitive
  * @dbxUtilRelated primative-key-dencoder, primative-key-dencoder-map
  *
- * @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
  * @__NO_SIDE_EFFECTS__
  */
 export declare function primativeKeyStringDencoder<D extends PrimativeKey, E extends PrimativeKey>(config: PrimativeKeyStringDencoderConfig<D, E>): PrimativeKeyStringDencoderFunction<D, E>;
@@ -157,7 +159,7 @@ export declare const NUMBER_STRING_DENCODER_64_DIGITS: NumberStringDencoderDigit
 /**
  * The default negative prefix for negative numbers.
  */
-export declare const NUMBER_STRING_DENCODER_64_DEFAULT_NEGATIVE_PREFIX = "!";
+export declare const DEFAULT_NUMBER_STRING_DENCODER_64_NEGATIVE_PREFIX = "!";
 /**
  * The NumberString dencoder type
  * - positive_integer: can only encode/decode positive integers
@@ -208,8 +210,8 @@ export interface NumberStringDencoderConfig {
  *
  * If the config does not include a negative prefix, negative numbers lose their sign during encoding.
  *
- * @param config - configuration with digit alphabet and optional negative prefix
- * @returns a NumberStringDencoder capable of encoding/decoding integers
+ * @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;
 /**
@@ -225,14 +227,15 @@ export type NumberStringDencoderFunction = ((input: 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.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, number, encode, decode, dencoder, bidirectional, factory
  * @dbxUtilRelated number-string-dencoder, number-string-dencoder-encoded-string-value-function, number-string-dencoder-decoded-number-value-function
  *
- * @param dencoder - the NumberStringDencoder to wrap
- * @returns a bidirectional encode/decode function
  * @__NO_SIDE_EFFECTS__
  */
 export declare function numberStringDencoderFunction(dencoder: NumberStringDencoder): NumberStringDencoderFunction;
@@ -240,14 +243,15 @@ export declare function numberStringDencoderFunction(dencoder: NumberStringDenco
  * 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 Normalizes input to an encoded string.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, number, encode, normalize, factory
  * @dbxUtilRelated number-string-dencoder-function, number-string-dencoder-decoded-number-value-function
  *
- * @param dencoder - the NumberStringDencoder to use for encoding
- * @returns a function that normalizes input to an encoded string
  * @__NO_SIDE_EFFECTS__
  */
 export declare function numberStringDencoderEncodedStringValueFunction(dencoder: NumberStringDencoder): (input: NumberStringDencoderString | NumberStringDencoderNumber) => NumberStringDencoderString;
@@ -255,14 +259,15 @@ export declare function numberStringDencoderEncodedStringValueFunction(dencoder:
  * 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 Normalizes input to a decoded number.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, number, decode, normalize, factory
  * @dbxUtilRelated number-string-dencoder-function, number-string-dencoder-encoded-string-value-function
  *
- * @param dencoder - the NumberStringDencoder to use for decoding
- * @returns a function that normalizes input to a decoded number
  * @__NO_SIDE_EFFECTS__
  */
 export declare function numberStringDencoderDecodedNumberValueFunction(dencoder: NumberStringDencoder): (input: NumberStringDencoderString | NumberStringDencoderNumber) => NumberStringDencoderNumber;

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

@@ -6,21 +6,22 @@ import { type TransformStringFunctionConfig } from './transform';
  */
 export type StringFactory<K extends string = string> = Factory<K>;
 /**
- * A function that converts a value of type T to a string.
+ * Converts a value of type T to a string.
  */
 export type ToStringFunction<T, K extends string = string> = FactoryWithRequiredInput<K, T>;
 /**
  * Wraps an existing factory with a {@link ToStringFunction} to produce strings from the factory's output.
  *
+ * @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.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, factory, wrap, transform, to-string
  * @dbxUtilRelated string-from-date-factory, string-from-time-factory
  *
- * @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
  * @__NO_SIDE_EFFECTS__
  */
 export declare function stringFactoryFromFactory<T, K extends string = string>(factory: Factory<T>, toStringFunction: ToStringFunction<T, K>): StringFactory<K>;
@@ -50,28 +51,30 @@ export interface StringFromDateConfig {
 /**
  * Creates a factory that returns a string based on the input date.
  *
+ * @param config - Configuration for the factory.
+ * @returns A factory that returns a string based on the input date.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, date, factory, transform, slice
  * @dbxUtilRelated string-from-time-factory, string-factory-from-factory, transform-string-function
  *
- * @param config Configuration for the factory.
- * @returns A factory that returns a string based on the input date.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function stringFromDateFactory(config: StringFromDateConfig): StringFromDateFactory;
 /**
  * Creates a factory that returns a string based on the Unix timestamp of the input date.
  *
+ * @param digitsFromEnd - The number of digits to return from the end of the generated string. Defaults to 7.
+ * @returns A StringFromDateFactory.
+ *
  * @dbxUtil
  * @dbxUtilCategory string
  * @dbxUtilKind factory
  * @dbxUtilTags string, date, time, timestamp, factory, suffix
  * @dbxUtilRelated string-from-date-factory
  *
- * @param digitsFromEnd The number of digits to return from the end of the generated string. Defaults to 7.
- * @returns A StringFromDateFactory.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function stringFromTimeFactory(digitsFromEnd?: number): StringFromDateFactory;

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

@@ -47,27 +47,15 @@ export type CssTokenVar<T extends CssToken = CssToken> = `var(${T})`;
 /**
  * Converts a CSS token into a var() string.
  *
+ * @param cssToken - The CSS token to convert.
+ * @returns The var() string.
+ *
  * @example
  * ```ts
  * cssTokenVar('--dbx-primary-color'); // 'var(--dbx-primary-color)'
  * ```
- *
- * @param cssToken - the CSS token to convert
- * @returns the var() string
  */
 export declare function cssTokenVar<T extends CssToken>(cssToken: T): CssTokenVar<T>;
-/**
- * @deprecated Use {@link CssToken} instead.
- */
-export type CssVariable = CssToken;
-/**
- * @deprecated Use {@link CssTokenVar} instead.
- */
-export type CssVariableVar<T extends CssToken = CssToken> = CssTokenVar<T>;
-/**
- * @deprecated Use {@link cssTokenVar} instead.
- */
-export declare const cssVariableVar: typeof cssTokenVar;
 /**
  * Represents a single CSS Style
  *
@@ -103,15 +91,27 @@ export type CssClassesArray = ArrayOrValue<ArrayOrValue<SpaceSeparatedCssClasses
 /**
  * Joins together various arrays of CSS classes into a single space-separated string of unique class names.
  *
- * @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
+ * @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;
 /**
  * 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 - 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
+ * @param cssClasses - One or more CSS class values or arrays of class values.
+ * @returns Set of unique CSS class names, or an empty Set if input is null/undefined.
  */
 export declare function cssClassesSet(cssClasses: Maybe<CssClassesArray>): Set<CssClass>;
+/**
+ * @deprecated Use {@link CssToken} instead.
+ */
+export type CssVariable = CssToken;
+/**
+ * @deprecated Use {@link CssTokenVar} instead.
+ */
+export type CssVariableVar<T extends CssToken = CssToken> = CssTokenVar<T>;
+/**
+ * @deprecated Use {@link cssTokenVar} instead.
+ */
+export declare const cssVariableVar: typeof cssTokenVar;

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

@@ -1,4 +1,5 @@
 import { type SlashPathTypedFileExtension } from '../path/path';
+import { type SuggestedString } from '../type';
 import { type Maybe } from '../value/maybe.type';
 /**
  * A simple mime type string with just the type/subtype and no parameters.
@@ -106,8 +107,8 @@ export declare function mimeTypeForImageFileExtension(extension: Maybe<ImageFile
 /**
  * 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
+ * @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>;
 /**
@@ -174,7 +175,7 @@ export declare function mimeTypeForDocumentFileExtension(extension: Maybe<Docume
 /**
  * Returns the document file extension for the given mimetype, or undefined if the mimetype is not known/recognized.
  *
- * @param mimeType The mimetype to get the document file extension for.
+ * @param mimeType - The mimetype to get the document file extension for.
  * @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>;
@@ -206,8 +207,8 @@ export declare function mimeTypeForApplicationFileExtension(extension: Maybe<App
 /**
  * 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
+ * @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>;
 /**
@@ -228,8 +229,8 @@ export declare function mimeTypeForFileExtension(extension: Maybe<DbxComponentsK
 /**
  * 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
+ * @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>;
 /**
@@ -237,4 +238,4 @@ export declare function fileExtensionForMimeType(mimeType: Maybe<MimeTypeWithout
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Disposition
  */
-export type ContentDispositionString = 'inline' | 'attachment' | (string & {});
+export type ContentDispositionString = SuggestedString<'inline' | 'attachment'>;

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

@@ -20,7 +20,7 @@ export type CharacterPrefix = string;
  */
 export type CharacterSuffix = string;
 /**
- * A string that does not have a CharacterPrefix or CharacterSuffix.
+ * Does not have a CharacterPrefix or CharacterSuffix.
  *
  * @semanticType
  * @semanticTopic string
@@ -28,15 +28,15 @@ export type CharacterSuffix = string;
  */
 export type CharacterPrefixSuffixCleanString = string;
 /**
- * A string that is a combination of a prefix and suffix.
+ * Is a combination of a prefix and suffix.
  */
 export type CharacterPrefixSuffixString<P extends CharacterPrefix = '', S extends CharacterSuffix = '', T extends string = string> = `${P}${T}${S}`;
 /**
- * A string that has a known prefix.
+ * Has a known prefix.
  */
 export type CharacterPrefixString<P extends CharacterPrefix = '', T extends string = string> = CharacterPrefixSuffixString<P, '', T>;
 /**
- * A string that has a known suffix.
+ * Has a known suffix.
  */
 export type CharacterSuffixString<S extends CharacterSuffix = '', T extends string = string> = CharacterPrefixSuffixString<'', S, T>;
 /**
@@ -103,8 +103,8 @@ export declare function characterPrefixSuffixInstance<P extends CharacterPrefix
  * (vs. {@link removeFirstMatchingSuffix}, which silently passes the
  * input through).
  *
- * @param input The string to trim.
- * @param suffix The suffix to remove.
+ * @param input - The string to trim.
+ * @param suffix - The suffix to remove.
  * @returns The input without the suffix, or `undefined` when the input
  *   does not end with the suffix.
  */
@@ -113,8 +113,8 @@ export declare function removeSuffix(input: string, suffix: string): Maybe<strin
  * Removes the first matching suffix from the input string. Returns the
  * input unchanged when none of the suffixes match.
  *
- * @param input The string to trim.
- * @param suffixes The suffixes to try in order.
+ * @param input - The string to trim.
+ * @param suffixes - The suffixes to try in order.
  * @returns The input with the first matching suffix removed, or the
  *   input unchanged when no suffix matches.
  */