@dereekb/util 13.0.7 → 13.2.0

package/src/lib/model/model.d.ts

@@ -5,6 +5,10 @@ import { type MapFunction } from '../value/map';
  * A string model key
  */
 export type ModelKey = string;
+/**
+ * A string model identifier (typically the document/record ID segment, not the full path).
+ */
+export type ModelId = string;
 /**
  * Arbitrary model type.
  */
@@ -30,6 +34,9 @@ export interface NamedUniqueModel extends UniqueModel {
 export interface ModelKeyRef {
     key: ModelKey;
 }
+export interface ModelIdRef {
+    id: ModelId;
+}
 export type ModelOrKey<T> = T | ModelKey;
 /**
  * ModelOrKey where the model extends UniqueModel
@@ -54,39 +61,196 @@ export type ReadModelKeyFunction<T> = ReadKeyFunction<T, ModelKey>;
 export type ReadModelTypeFunction<T, M extends ModelTypeString = ModelTypeString> = ReadKeyFunction<T, M>;
 export type ReadRelationKeysFunction<T> = ReadMultipleKeysFunction<T, ModelKey>;
 export type MultiModelKeyMap<T> = Map<string, T>;
+/**
+ * Reads the `id` property from a {@link UniqueModel}.
+ *
+ * @param model - Model to read the key from
+ * @returns The model's `id` value
+ */
 export declare const readUniqueModelKey: (model: UniqueModel) => string | undefined;
+/**
+ * Abstract base class for models identified by a unique {@link ModelKey}.
+ *
+ * Copies the `id` from the provided template during construction.
+ */
 export declare abstract class AbstractUniqueModel {
     id?: ModelKey;
     constructor(template: Partial<AbstractUniqueModel>);
 }
+/**
+ * Deduplicates an array of model keys using a Set.
+ *
+ * @param keys - Array of model keys that may contain duplicates
+ * @returns Array containing only unique keys
+ *
+ * @example
+ * ```ts
+ * const result = uniqueKeys(['a', 'b', 'a', 'c']);
+ * // result: ['a', 'b', 'c']
+ * ```
+ */
 export declare function uniqueKeys(keys: ModelKey[]): ModelKey[];
+/**
+ * Deduplicates models by their key, keeping the first occurrence of each unique key.
+ *
+ * @param models - Array of models that may contain duplicates
+ * @param readKey - Function to extract the key from each model; defaults to reading the `id` property
+ * @returns Array containing only the first model for each unique key
+ */
 export declare function uniqueModels<T extends UniqueModel>(models: T[], readKey?: ReadModelKeyFunction<T>): T[];
 export declare function uniqueModels<T>(models: T[], readKey: ReadModelKeyFunction<T>): T[];
+/**
+ * Extracts model keys from an array of model objects.
+ *
+ * @param input - Array of model objects to read keys from
+ * @param required - Whether keys are required; throws if a key is missing and this is `true`
+ * @param read - Function to extract the key from each model; defaults to reading the `id` property
+ * @returns Array of model keys (may contain undefined values if `required` is false)
+ * @throws Error if `required` is true and any model lacks a key
+ */
 export declare function readModelKeysFromObjects<T extends UniqueModel>(input: T[], required?: boolean, read?: ReadModelKeyFunction<T>): Maybe<ModelKey>[];
 export declare function readModelKeysFromObjects<T extends UniqueModel>(input: T[], required: true, read?: ReadModelKeyFunction<T>): ModelKey[];
+/**
+ * Computes the symmetric difference (elements in either array but not both) between two arrays of models or keys.
+ *
+ * @param a - First array of models or keys
+ * @param b - Second array of models or keys
+ * @param required - Whether keys are required
+ * @param read - Function to extract keys from models
+ * @returns Keys that appear in one array but not the other
+ */
 export declare function symmetricDifferenceWithModels<T extends UniqueModel>(a: ModelOrKey<T>[], b: ModelOrKey<T>[], required?: boolean, read?: ReadModelKeyFunction<T>): Maybe<ModelKey>[];
+/**
+ * Removes all models from the array that share the same key as the given model.
+ *
+ * @param input - Array of models to filter
+ * @param model - Reference model whose key should be excluded
+ * @param read - Function to extract the key from each model
+ * @returns Filtered array excluding models with the same key as the reference model
+ */
 export declare function removeModelsWithSameKey<T>(input: T[], model: T, read: ReadModelKeyFunction<T>): T[];
+/**
+ * Removes all models from the array that have the specified key.
+ *
+ * @param input - Array of models to filter
+ * @param key - Key value to exclude
+ * @param read - Function to extract the key from each model; defaults to reading the `id` property
+ * @returns Filtered array excluding models with the matching key
+ */
 export declare function removeModelsWithKey<T extends UniqueModel>(input: T[], key: Maybe<ModelKey>, read?: ReadModelKeyFunction<T>): T[];
 export declare function removeModelsWithKey<T>(input: T[], key: Maybe<ModelKey>, read: ReadModelKeyFunction<T>): T[];
+/**
+ * Creates a Map from model key to model, indexing each model by its key.
+ *
+ * If multiple models share the same key, the last one wins.
+ *
+ * @param input - Array of models to index
+ * @param read - Function to extract the key from each model; defaults to reading the `id` property
+ * @returns Map from model key to model
+ */
 export declare function makeModelMap<T extends UniqueModel>(input: T[], read?: ReadModelKeyFunction<T>): Map<Maybe<ModelKey>, T>;
 export declare function makeModelMap<T>(input: T[], read: ReadModelKeyFunction<T>): Map<Maybe<ModelKey>, T>;
 /**
- * Creates a UniqueRelationsMap
+ * Creates a Map that indexes each model by multiple keys, allowing lookup of a model by any of its relation keys.
+ *
+ * If multiple models share the same relation key, the last one wins for that key.
+ *
+ * @param input - Array of models to index
+ * @param read - Function that returns an array of relation keys for each model
+ * @returns Map from relation key to model
  */
 export declare function makeMultiModelKeyMap<T>(input: T[], read: ReadRelationKeysFunction<T>): MultiModelKeyMap<T>;
+/**
+ * Dispatches to either `useModel` or `useKey` depending on whether the input is a model object or a key string.
+ *
+ * If the input is null/undefined and `required` is true, throws an error.
+ *
+ * @param input - A model object or a model key string
+ * @param config - Handlers for model and key cases, plus whether input is required
+ * @returns The result of the matched handler, or undefined if input is nullish and not required
+ * @throws Error if `required` is true and input is nullish
+ */
 export declare function useModelOrKey<O, T extends UniqueModel>(input: ModelOrKey<T>, { useModel, useKey, required }: {
     useModel?: (model: T) => O;
     useKey: (key: Maybe<ModelKey>) => O;
     required?: boolean;
 }): Maybe<O>;
+/**
+ * Extracts model keys from an array of models or key strings.
+ *
+ * @param input - Array of models, key strings, or undefined values
+ * @param required - Whether keys are required
+ * @param read - Function to extract the key from model objects
+ * @returns Array of model keys
+ */
 export declare function readModelKeys<T extends UniqueModel>(input: (ModelOrKey<T> | undefined)[], required?: boolean, read?: ReadModelKeyFunction<T>): Maybe<ModelKey>[];
+/**
+ * Reads a model key from a model or key string. Convenience wrapper around {@link readModelKey} with default params.
+ *
+ * @param input - A model object or a key string
+ * @returns The extracted model key, or undefined if input is undefined
+ */
 export declare function requireModelKey<T extends UniqueModel>(input: ModelOrKey<T> | undefined): Maybe<ModelKey>;
+/**
+ * Reads a model key from a value that may be a model object, a key string, or undefined.
+ *
+ * Strings are returned as-is. Objects are passed through the `read` function to extract the key.
+ *
+ * @param input - A model object, key string, or undefined
+ * @param params - Configuration for reading, including whether the key is required and the read function
+ * @returns The extracted model key, or undefined
+ * @throws Error if `required` is true and no key can be extracted
+ */
 export declare function readModelKey<T>(input: ModelOrKey<T> | undefined, params: ReadModelKeyParams<T>): Maybe<ModelKey>;
 export declare function readModelKey<T extends UniqueModel>(input: ModelOrKey<T> | undefined, params?: Partial<ReadModelKeyParams<T>>): Maybe<ModelKey>;
+/**
+ * Reads a model key directly from a model object using the provided read function.
+ *
+ * @param input - Model object to read the key from
+ * @param required - Whether the key is required; throws if missing when true
+ * @param read - Function to extract the key; defaults to reading the `id` property
+ * @returns The extracted model key, or undefined
+ * @throws Error if `required` is true and the key is missing
+ */
 export declare function readModelKeyFromObject<T extends UniqueModel>(input: T, required?: boolean, read?: ReadModelKeyFunction<T>): Maybe<ModelKey>;
+/**
+ * Type guard that checks whether the input is a string model key rather than a model object.
+ *
+ * @param input - A model object or a key string
+ * @returns `true` if the input is a string key
+ */
 export declare function isModelKey<T extends UniqueModel>(input: ModelOrKey<T>): input is ModelKey;
+/**
+ * Throws an error indicating a model key was required but not provided.
+ *
+ * @throws Error always
+ */
 export declare function throwKeyIsRequired(): void;
+/**
+ * Encodes a {@link ModelKeyTypePair} into a single string in the format `type_key`.
+ *
+ * @param pair - The type/key pair to encode
+ * @returns Encoded string representation
+ *
+ * @example
+ * ```ts
+ * const encoded = encodeModelKeyTypePair({ type: 'user', key: '123' });
+ * // encoded: 'user_123'
+ * ```
+ */
 export declare function encodeModelKeyTypePair(pair: ModelKeyTypePair): ModelKey;
+/**
+ * Decodes a string in the format `type_key` back into a {@link ModelKeyTypePair}.
+ *
+ * @param linkKey - Encoded string to decode
+ * @returns The decoded type/key pair
+ *
+ * @example
+ * ```ts
+ * const pair = decodeModelKeyTypePair('user_123');
+ * // pair: { type: 'user', key: '123' }
+ * ```
+ */
 export declare function decodeModelKeyTypePair<M extends ModelTypeString = ModelTypeString>(linkKey: ModelKey): ModelKeyTypePair<M>;
 /**
  * A type and data pair.
@@ -98,4 +262,13 @@ export interface ModelTypeDataPair<T = unknown, M extends ModelTypeString = Mode
  * Used for converting the input data into a ModelTypeDataPair value.
  */
 export type ModelTypeDataPairFactory<T, M extends ModelTypeString = ModelTypeString> = MapFunction<T, ModelTypeDataPair<T, M>>;
+/**
+ * Creates a factory function that wraps input data into a {@link ModelTypeDataPair} by reading the type from the data.
+ *
+ * Falls back to the provided default type if the type reader returns a nullish value.
+ *
+ * @param typeReader - Function to extract the model type from input data
+ * @param defaultType - Fallback type string when the reader returns nullish
+ * @returns Factory function that produces ModelTypeDataPair values
+ */
 export declare function modelTypeDataPairFactory<T, M extends ModelTypeString = ModelTypeString>(typeReader: ReadModelTypeFunction<T, M>, defaultType?: string): ModelTypeDataPairFactory<T, M>;

package/src/lib/model/model.modify.d.ts

@@ -10,6 +10,14 @@ export type ModelInputModelModifier<V extends object> = {
 };
 export type ModelModifier<V extends object, D extends object> = ModelInputModelModifier<V> & ModelInputDataModifier<D>;
 export type PartialModelModifier<V extends object, D extends object> = Partial<MaybeMap<ModelModifier<V, D>>>;
+/**
+ * Merges one or more partial model modifiers into a single {@link PartialModelModifier}.
+ *
+ * Combines all `modifyData` and `modifyModel` functions from the input modifiers into unified modifier functions.
+ *
+ * @param input - One or more partial model modifiers to merge
+ * @returns A single merged modifier with combined `modifyData` and `modifyModel` functions
+ */
 export declare function maybeMergeModelModifiers<V extends object, D extends object>(input: ArrayOrValue<PartialModelModifier<V, D>>): PartialModelModifier<V, D>;
 export interface ModifyModelMapFunctionsConfig<V extends object, D extends object> {
     readonly mapFunctions: ModelMapFunctions<V, D>;
@@ -34,13 +42,24 @@ export interface ModifyModelMapFunctionsConfig<V extends object, D extends objec
      */
     readonly copyData?: boolean;
 }
+/**
+ * Wraps existing {@link ModelMapFunctions} with modifier functions that are applied to the input before conversion.
+ *
+ * Optionally copies the input object before modification to avoid mutating the original.
+ *
+ * @param config - Configuration with the base map functions, modifiers, and copy options
+ * @returns New model map functions with modifiers applied before each conversion
+ */
 export declare function modifyModelMapFunctions<V extends object, D extends object>(config: ModifyModelMapFunctionsConfig<V, D>): ModelMapFunctions<V, D>;
 /**
- * Merges a ModifierFunction with a ModelMapFunction
+ * Wraps a single {@link ModelMapFunction} with a modifier that is applied to the input before the map function runs.
+ *
+ * When `copy` is true (default), the input is shallow-copied before modification to avoid mutating the original.
+ * If no modifier is provided, the original map function is returned unchanged.
  *
- * @param mapFn
- * @param modifyModel
- * @param copy
- * @returns
+ * @param mapFn - The base map function to wrap
+ * @param modifyModel - Optional modifier to apply before mapping
+ * @param copy - Whether to shallow-copy the input before modifying; defaults to true
+ * @returns The wrapped map function, or the original if no modifier is provided
  */
 export declare function modifyModelMapFunction<I extends object, O extends object>(mapFn: ModelMapFunction<I, O>, modifyModel: Maybe<ModifierFunction<I>>, copy?: boolean): ModelMapFunction<I, O>;

package/src/lib/nodejs/stream.d.ts

@@ -3,9 +3,10 @@
  */
 export type ReadableStreamToStringFunction = (stream: NodeJS.ReadableStream) => Promise<string>;
 /**
- * Creates a new ReadableStreamToStringFunction
- * @param encoding
- * @returns
+ * Creates a function that reads a Node.js ReadableStream and converts its contents to a string using the specified encoding.
+ *
+ * @param encoding - The buffer encoding to use (e.g., 'utf-8', 'base64')
+ * @returns A function that consumes a ReadableStream and resolves to its string content
  */
 export declare function readableStreamToStringFunction(encoding: BufferEncoding): ReadableStreamToStringFunction;
 /**
@@ -13,9 +14,10 @@ export declare function readableStreamToStringFunction(encoding: BufferEncoding)
  */
 export declare const readableStreamToBase64: ReadableStreamToStringFunction;
 /**
- * Converts a ReadableStream to a Buffer promise.
+ * Reads all data from a Node.js ReadableStream and concatenates it into a single Buffer.
  *
- * @param encoding
- * @returns
+ * @param stream - The readable stream to consume
+ * @returns Promise resolving to a Buffer containing all stream data
+ * @throws Rejects if the stream emits an error event
  */
 export declare function readableStreamToBuffer(stream: NodeJS.ReadableStream): Promise<Buffer>;

package/src/lib/number/bitwise.dencoder.d.ts

@@ -19,17 +19,40 @@ export type BitwiseEncodedSet = number;
  * Encodes a BitwiseEncodedSet from a set of values.
  */
 export type BitwiseSetEncoder<D extends BitwiseEncodedSetIndex> = (set: Set<D>) => BitwiseEncodedSet;
+/**
+ * Encodes a Set of bit indices into a single {@link BitwiseEncodedSet} number using bitwise OR.
+ *
+ * @param input - Set of indices (0-31) to encode
+ * @returns A number with bits set at each index position
+ */
 export declare function encodeBitwiseSet<D extends BitwiseEncodedSetIndex>(input: Set<D>): BitwiseEncodedSet;
 /**
  * Decodes an BitwiseEncodedSet to a Set of values.
  */
 export type BitwiseSetDecoder<D extends BitwiseEncodedSetIndex> = (set: BitwiseEncodedSet) => Set<D>;
+/**
+ * Creates a decoder that converts a {@link BitwiseEncodedSet} number back into a Set of indices by checking each bit position up to `maxIndex`.
+ *
+ * @param maxIndex - The exclusive upper bound of indices to check
+ * @returns A function that decodes an encoded number into a Set of active indices
+ */
 export declare function bitwiseSetDecoder<D extends BitwiseEncodedSetIndex>(maxIndex: number): BitwiseSetDecoder<D>;
+/**
+ * Default decoder that checks all 32 bit positions.
+ */
 export declare const dencodeBitwiseSet: BitwiseSetDecoder<number>;
 /**
  * Encodes and Decodes a BitwiseEncodedSet, depending on the input.
  */
 export type BitwiseSetDencoder<D extends BitwiseEncodedSetIndex> = BitwiseSetEncoder<D> & BitwiseSetDecoder<D>;
+/**
+ * Creates a bidirectional encoder/decoder for {@link BitwiseEncodedSet}.
+ *
+ * Accepts either a Set (encodes to number) or a number (decodes to Set).
+ *
+ * @param maxIndex - Optional exclusive upper bound of indices for decoding; defaults to 32
+ * @returns A function that encodes Sets to numbers and decodes numbers to Sets
+ */
 export declare function bitwiseSetDencoder<D extends BitwiseEncodedSetIndex>(maxIndex?: number): BitwiseSetDencoder<D>;
 /**
  * Maps the input object to a set of index values.
@@ -44,16 +67,25 @@ export type BitwiseObjectFromSetFunction<T extends object, D extends BitwiseEnco
  */
 export type BitwiseObjectEncoder<T extends object> = (object: T) => BitwiseEncodedSet;
 /**
- * Creates a BitwiseObjectEncoder<T> from the input.
+ * Creates a {@link BitwiseObjectEncoder} that converts an object to a {@link BitwiseEncodedSet} number.
+ *
+ * Uses the provided `toSetFunction` to first map the object to a Set of indices, then encodes it.
  *
- * @param toSetFunction
- * @returns
+ * @param toSetFunction - Function that maps an object to a Set of bit indices
+ * @returns An encoder function that produces a bitwise-encoded number from the object
  */
 export declare function bitwiseObjectEncoder<T extends object, D extends BitwiseEncodedSetIndex>(toSetFunction: BitwiseObjectToSetFunction<T, D>): BitwiseObjectEncoder<T>;
 /**
  * Decodes an object from the input BitwiseEncodedSet.
  */
 export type BitwiseObjectDecoder<T extends object> = (set: BitwiseEncodedSet) => T;
+/**
+ * Creates a {@link BitwiseObjectDecoder} that converts a {@link BitwiseEncodedSet} number back into an object.
+ *
+ * @param fromSetFunction - Function that maps a Set of bit indices back to an object
+ * @param maxIndex - Optional exclusive upper bound of indices for decoding; defaults to 32
+ * @returns A decoder function that produces an object from a bitwise-encoded number
+ */
 export declare function bitwiseObjectdecoder<T extends object, D extends BitwiseEncodedSetIndex>(fromSetFunction: BitwiseObjectFromSetFunction<T, D>, maxIndex?: number): BitwiseObjectDecoder<T>;
 /**
  * Encodes/Decodes an object.
@@ -67,4 +99,12 @@ export interface BitwiseObjectDencoderConfig<T extends object, D extends Bitwise
      */
     readonly maxIndex?: number;
 }
+/**
+ * Creates a bidirectional {@link BitwiseObjectDencoder} that encodes objects to numbers and decodes numbers back to objects.
+ *
+ * Accepts either a number (decodes to object) or an object (encodes to number). Returns 0 for null/undefined input.
+ *
+ * @param config - Configuration with `toSetFunction`, `fromSetFunction`, and optional `maxIndex`
+ * @returns A function that encodes objects to numbers and decodes numbers to objects
+ */
 export declare function bitwiseObjectDencoder<T extends object, D extends BitwiseEncodedSetIndex = BitwiseEncodedSetIndex>(config: BitwiseObjectDencoderConfig<T, D>): BitwiseObjectDencoder<T>;

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

@@ -9,8 +9,21 @@ export interface NumberBound<T extends number = number> {
      */
     readonly max: T;
 }
+/**
+ * Checks whether a {@link NumberBound} is valid (min is less than or equal to max).
+ *
+ * @param bounds - The bounds to validate
+ * @returns `true` if `min <= max`
+ */
 export declare function isValidNumberBound(bounds: NumberBound): boolean;
 export type IsInNumberBoundFunction = (number: number) => boolean;
+/**
+ * Creates a function that checks whether a number falls within the specified inclusive bounds.
+ *
+ * @param bounds - The min/max bounds to test against
+ * @returns A function that returns `true` if the input number is within bounds
+ * @throws Error if the bounds are invalid (min > max)
+ */
 export declare function isInNumberBoundFunction(bounds: NumberBound): IsInNumberBoundFunction;
 export interface WrapNumberFunctionConfig<T extends number = number> extends NumberBound<T> {
     /**
@@ -23,6 +36,14 @@ export interface WrapNumberFunctionConfig<T extends number = number> extends Num
 export type WrapNumberFunction<T extends number = number> = MapFunction<number, T> & {
     readonly _wrap: WrapNumberFunctionConfig;
 };
+/**
+ * Creates a function that wraps numbers around within the specified bounds, like modular arithmetic.
+ *
+ * When `fencePosts` is true, wraps to the nearest "fence post" value, extending the wrap range by one in each direction.
+ *
+ * @param wrapNumberFunctionConfig - Configuration with min, max, and optional fence post behavior
+ * @returns A function that wraps input numbers into the bounded range
+ */
 export declare function wrapNumberFunction<T extends number = number>(wrapNumberFunctionConfig: WrapNumberFunctionConfig<T>): WrapNumberFunction<T>;
 export interface BoundNumberFunctionConfig<T extends number = number> extends NumberBound<T> {
     /**
@@ -33,13 +54,21 @@ export interface BoundNumberFunctionConfig<T extends number = number> extends Nu
     readonly wrap?: boolean;
 }
 export type BoundNumberFunction<T extends number = number> = MapFunction<number, T>;
+/**
+ * Creates a function that constrains numbers within bounds, either by clamping or wrapping.
+ *
+ * When `wrap` is true, uses modular wrapping. Otherwise, clamps values to the min/max range.
+ *
+ * @param boundNumberFunctionConfig - Configuration with min, max, and optional wrap behavior
+ * @returns A function that bounds input numbers into the configured range
+ */
 export declare function boundNumberFunction<T extends number = number>(boundNumberFunctionConfig: BoundNumberFunctionConfig<T>): BoundNumberFunction<T>;
 /**
- * Returns the input number clamped between the min and max values.
+ * Clamps the input number between the min and max values (inclusive).
  *
- * @param input
- * @param min
- * @param max
- * @returns
+ * @param input - Number to clamp
+ * @param min - Minimum allowed value
+ * @param max - Maximum allowed value
+ * @returns The clamped value
  */
 export declare function boundNumber<T extends number = number>(input: number, min: T, max: T): T;

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

@@ -32,18 +32,19 @@ export declare const DOLLAR_AMOUNT_STRING_REGEX: RegExp;
  */
 export declare const DOLLAR_AMOUNT_PRECISION = 2;
 /**
- * Returns true if the input is a valid DollarAmountString value.
+ * Checks whether the input string matches the expected dollar amount format (e.g., "12.50" or "$12.50").
  *
- * @param value
- * @returns
+ * @param value - String to test
+ * @returns `true` if the string matches the dollar amount regex
  */
 export declare function isDollarAmountString(value: string): boolean;
 /**
- * Returns a dollar amount, or '0.00' if null/undefined.
+ * Formats a number as a dollar amount string with exactly two decimal places.
  *
- * If the input number has more than two decimal places, only the first two are used; no rounding occurs. (I.E. 1.115 becomes 1.11)
+ * Truncates (does not round) excess precision: e.g., 1.115 becomes "1.11". Returns "0.00" for null/undefined.
  *
- * @param number
+ * @param number - The dollar amount to format
+ * @returns Formatted string with two decimal places (e.g., "12.50")
  */
 export declare function dollarAmountString(number: Maybe<number>): string;
 /**
@@ -55,4 +56,10 @@ export declare function dollarAmountString(number: Maybe<number>): string;
 export type DollarAmountStringWithUnitFunction<U extends DollarAmountUnit> = ((amount: DollarAmount) => DollarAmountStringWithUnit<U>) & {
     readonly unit: U;
 };
+/**
+ * Creates a function that formats dollar amounts as strings with a unit prefix (e.g., "$12.50").
+ *
+ * @param unit - The unit prefix to prepend; defaults to "$"
+ * @returns A function that formats dollar amounts with the configured unit
+ */
 export declare function dollarAmountStringWithUnitFunction<U extends DollarAmountUnit>(unit?: U): DollarAmountStringWithUnitFunction<U>;

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

@@ -14,9 +14,17 @@ export interface IncrementingNumberFactoryConfig {
     increaseBy?: GetterOrValue<number>;
 }
 /**
- * Creates a factory that returns increasing numbers.
+ * Creates a factory that returns sequentially increasing numbers, starting from a configurable value and incrementing by a configurable step.
  *
- * @param config
- * @returns
+ * @param config - Configuration with optional `startAt` (default 0) and `increaseBy` (default 1)
+ * @returns A factory function that returns the next number in the sequence on each call
+ *
+ * @example
+ * ```ts
+ * const factory = incrementingNumberFactory({ startAt: 10, increaseBy: 5 });
+ * factory(); // 10
+ * factory(); // 15
+ * factory(); // 20
+ * ```
  */
 export declare function incrementingNumberFactory(config?: IncrementingNumberFactoryConfig): NumberFactory;

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

@@ -18,12 +18,22 @@ export type PercentNumber = number;
  */
 export type PercentDecimal = number;
 /**
- * Converts the percent number to a decimal value.
+ * Converts a {@link PercentNumber} (e.g., 5 for 5%) to its decimal equivalent (e.g., 0.05).
  *
- * @param input
- * @returns
+ * Returns 0 for null/undefined input.
+ *
+ * @param input - A percent number value (e.g., 5 means 5%)
+ * @returns The decimal equivalent
  */
 export declare function percentNumberToDecimal(input: Maybe<number>): number;
+/**
+ * Converts a {@link PercentDecimal} (e.g., 0.05 for 5%) to its {@link PercentNumber} equivalent (e.g., 5).
+ *
+ * Returns 0 for null/undefined input.
+ *
+ * @param input - A decimal percent value (e.g., 0.05 means 5%)
+ * @returns The percent number equivalent
+ */
 export declare function percentNumberFromDecimal(input: Maybe<number>): PercentNumber;
 export type NumberOrNumberString = number | NumberString;
 /**
@@ -35,17 +45,22 @@ export type ReadNumberFunction<T, N extends number = number> = MapFunction<T, N>
  */
 export type AsNumberInput = Maybe<NumberOrNumberString>;
 /**
- * Converts the input value to a number.
+ * Converts a number, string, or null/undefined value to a number.
  *
- * @param input
+ * Strings are parsed via `Number()`. Null/undefined returns 0.
+ *
+ * @param input - A number, number string, or null/undefined
+ * @returns The numeric value, or 0 for null/undefined
  */
 export declare function asNumber(input: AsNumberInput): number;
 /**
- * Returns true if the input value is divisible by the divisor.
+ * Checks whether the input value is evenly divisible by the divisor.
+ *
+ * Treats null/undefined as 0.
  *
- * @param value
- * @param divisor
- * @returns
+ * @param value - The number to check
+ * @param divisor - The divisor to test against
+ * @returns `true` if the remainder is zero
  */
 export declare function isNumberDivisibleBy(value: Maybe<number>, divisor: number): boolean;
 export interface NearestDivisibleValues {
@@ -55,51 +70,59 @@ export interface NearestDivisibleValues {
     nearestFloor: number;
 }
 /**
- * Returns true if the input value is divisible by the divisor.
+ * Finds the nearest values that are evenly divisible by the divisor, both above (ceil) and below (floor) the input value.
  *
- * @param value
- * @param divisor
- * @returns
+ * @param value - The value to find divisible neighbors for
+ * @param divisor - The divisor to align to
+ * @returns Object with the input value, divisor, and the nearest ceil/floor divisible values
  */
 export declare function nearestDivisibleValues(value: number, divisor: number): NearestDivisibleValues;
 /**
- * Returns true if the input is an even number.
+ * Checks whether the input is an even number.
  *
- * @param value
- * @returns
+ * @param value - Number to test
+ * @returns `true` if even
  */
 export declare function isEvenNumber(value: number): boolean;
 /**
- * Returns true if the input is an odd number.
+ * Checks whether the input is an odd number.
  *
- * @param value
- * @returns
+ * @param value - Number to test
+ * @returns `true` if odd
  */
 export declare function isOddNumber(value: number): boolean;
 /**
- * The sum of all numbers between the two input number values, inclusive.
+ * Computes the sum of all integers between two values, inclusive, using Gauss's formula.
+ *
+ * The `from` value is floored and the `to` value is ceiled before computation.
  *
- * @param from
- * @param to
+ * @param from - The starting value (floored to nearest integer)
+ * @param to - The ending value (ceiled to nearest integer)
+ * @returns Sum of all integers in the range
  */
 export declare function sumOfIntegersBetween(from: number, to: number): number;
+/**
+ * A {@link SortCompareFunction} for numbers that sorts in ascending order.
+ */
 export declare const sortCompareNumberFunction: SortCompareFunction<number>;
 /**
- * Returns the min and max values from the input numbers.
+ * Finds the minimum and maximum values from an iterable of numbers.
  *
- * @param values
- * @returns
+ * @param values - Iterable of numbers to examine
+ * @returns Object with `min` and `max` values
  */
 export declare function minAndMaxNumber(values: Iterable<number>): MinAndMaxFunctionResult<number>;
 /**
- * Returns the lorgathirm of y with base x.
+ * Computes the logarithm of `y` with base `x`.
  *
- * Example:
- * - (log2(16)): x = 2, y = 16 -> 4    (2^4 = 16)
- * - (log10(100)): x = 10, y = 100 -> 2   (10^2 = 100)
+ * @param x - The base of the logarithm
+ * @param y - The value to compute the logarithm of
+ * @returns The base-x logarithm of y
  *
- * @param x
- * @param y
- * @returns
+ * @example
+ * ```ts
+ * getBaseLog(2, 16); // 4 (2^4 = 16)
+ * getBaseLog(10, 100); // 2 (10^2 = 100)
+ * ```
  */
 export declare function getBaseLog(x: number, y: number): number;