@dereekb/util 13.0.7 → 13.1.0

package/src/lib/iterable/iterable.d.ts

@@ -7,109 +7,121 @@ import { type Maybe } from '../value/maybe.type';
  * Note that strings are a valid Iterable, allowing iteration over characters.
  */
 export type IterableOrValue<T> = T | Iterable<T>;
+/**
+ * Converts an IterableOrValue to an Iterable. Non-iterable values are wrapped in an array.
+ *
+ * @param values - The value or iterable to convert
+ * @param treatStringAsIterable - Whether to treat strings as iterable (defaults to false)
+ * @returns An Iterable containing the value(s)
+ */
 export declare function asIterable<T = unknown>(values: IterableOrValue<T>, treatStringAsIterable?: boolean): Iterable<T>;
 /**
- * Converts the input IterableOrValue value to an array.
+ * Converts an IterableOrValue to an array.
  *
- * By default will treat strings as a non-iterable value, using the string as a single value.
+ * By default treats strings as a non-iterable value, using the string as a single value.
  *
- * @param values
- * @param treatStringAsIterable
- * @returns
+ * @param values - The value or iterable to convert
+ * @param treatStringAsIterable - Whether to treat strings as iterable (defaults to false)
+ * @returns An array containing the value(s)
  */
 export declare function iterableToArray<T = unknown>(values: IterableOrValue<T>, treatStringAsIterable?: boolean): T[];
 /**
- * Converts the input IterableOrValue value to a Set.
+ * Converts an IterableOrValue to a Set.
  *
- * By default will treat strings as a non-iterable value, using the string as a single value.
+ * By default treats strings as a non-iterable value, using the string as a single value.
  *
- * @param values
- * @param treatStringAsIterable
- * @returns
+ * @param values - The value or iterable to convert
+ * @param treatStringAsIterable - Whether to treat strings as iterable (defaults to false)
+ * @returns A Set containing the value(s)
  */
 export declare function iterableToSet<T = unknown>(values: IterableOrValue<T>, treatStringAsIterable?: boolean): Set<T>;
 /**
- * Converts the input IterableOrValue value to a Map using the input readKey function.
+ * Converts an IterableOrValue to a Map using a key extraction function.
  *
- * @param values
- * @param readKey
- * @returns
+ * @param values - The value or iterable to convert
+ * @param readKey - Function to extract the key from each value
+ * @returns A Map with the extracted keys and their corresponding values
  */
 export declare function iterableToMap<T, K extends PrimativeKey = PrimativeKey>(values: IterableOrValue<T>, readKey: ReadKeyFunction<T, K>): Map<Maybe<K>, T>;
 /**
- * Returns true if the input is an Iterable.
- *
- * Can specify whether or not to treat string values as iterable values. Is false by default.
+ * Type guard that returns true if the input is an Iterable.
+ * By default, strings are not treated as iterable.
  *
- * @param values
- * @param treatStringAsIterable
- * @returns
+ * @param values - The value to check
+ * @param treatStringAsIterable - Whether to treat strings as iterable (defaults to false)
+ * @returns True if the value is iterable
  */
 export declare function isIterable<T = unknown>(values: unknown, treatStringAsIterable?: boolean): values is Iterable<T>;
 /**
- * Returns true if there are values to iterate over.
+ * Returns true if the iterable has no values.
  *
- * @param values
- * @returns
+ * @param values - The iterable to check
+ * @returns True if the iterable is empty
  */
 export declare function isEmptyIterable<T = unknown>(values: Iterable<T>): boolean;
 /**
- * Returns the first value from the Iterable. If there are no values, returns undefined. Order is not guranteed.
+ * Returns the first value from the Iterable, or undefined if empty. Order is not guaranteed.
  *
- * @param values
- * @returns
+ * @param values - The iterable to read from
+ * @returns The first value, or undefined if empty
  */
 export declare function firstValueFromIterable<T>(values: Iterable<T>): Maybe<T>;
 /**
- * Takes items from the iterable in the order they are read. Order is not guranteed.
+ * Takes up to `count` items from the iterable. Order is not guaranteed.
  *
- * @param values
- * @param count
- * @returns
+ * @param values - The iterable to take from
+ * @param count - Maximum number of items to take
+ * @returns An array of taken values
  */
 export declare function takeValuesFromIterable<T>(values: Iterable<T>, count: number): T[];
 /**
- * Iterates over iterable values.
+ * Iterates over iterable values, calling the function for each one.
  *
- * @param values
- * @param fn
+ * @param values - The iterable to iterate over
+ * @param fn - The function to call for each value
  */
 export declare function forEachInIterable<T>(values: Iterable<T>, fn: (value: T) => void): void;
 /**
- * Uses the input iterable if it is defined.
+ * Calls the function for each value if the input is iterable, or once with the value if it's a single value.
+ * Does nothing if the input is null/undefined.
  *
- * @param values
- * @param fn
+ * @param values - The value or iterable to process
+ * @param fn - The function to call for each value
+ * @param treatStringAsIterable - Whether to treat strings as iterable (defaults to false)
  */
 export declare function useIterableOrValue<T>(values: Maybe<IterableOrValue<T>>, fn: (value: T) => void, treatStringAsIterable?: boolean): void;
 /**
- * Find the first matching value in the Iterable.
+ * Finds and returns the first value in the iterable that matches the decision function.
  *
- * @param values
- * @param fn
+ * @param values - The iterable to search
+ * @param fn - Decision function that returns true for the desired value
+ * @returns The first matching value, or undefined
  */
 export declare function findInIterable<T>(values: Iterable<T>, fn: DecisionFunction<T>): Maybe<T>;
 /**
- * Whether or not the value exists in the iterable.
+ * Returns true if any value in the iterable matches the decision function.
  *
- * @param values
- * @param fn
- * @returns
+ * @param values - The iterable to search
+ * @param fn - Decision function to test each value
+ * @returns True if at least one value matches
  */
 export declare function existsInIterable<T>(values: Iterable<T>, fn: DecisionFunction<T>): boolean;
 /**
- * Filters values from the iterable using a DecisionFunction.
+ * Filters values from the iterable, keeping those that pass the decision function.
  *
- * @param values
- * @param fn
- * @returns
+ * @param values - The iterable to filter
+ * @param fn - Decision function that returns true for values to keep
+ * @returns An array of matching values
  */
 export declare function filterFromIterable<T>(values: Iterable<T>, fn: DecisionFunction<T>): T[];
 /**
- * Wraps the input tuple values as an array. The tuples should all be the same length in order to wrap them properly, and the tuple value cannot consist of only arrays of the same length.
+ * Wraps a single tuple value into an array. Distinguishes between a single tuple and an array of tuples
+ * by checking whether nested array elements have uniform length.
  *
- * This is used to prevent functions from treating the tuple itself as an array.
+ * Used to prevent functions from incorrectly treating a tuple as an array of values.
  *
- * @param input
+ * @param input - The tuple or array of tuples to wrap
+ * @returns An array containing the tuple(s)
+ * @throws Error if input is not an array
  */
 export declare function wrapTuples<T>(input: IterableOrValue<T>): T[];

package/src/lib/iterable/iterable.map.d.ts

@@ -1,8 +1,8 @@
 /**
- * map utility function for an iterable that maps and places the results into an array.
+ * Maps each value in an iterable through a function and returns the results as an array.
  *
- * @param values
- * @param fn
- * @returns
+ * @param values - The iterable to map over
+ * @param fn - The mapping function to apply to each value
+ * @returns An array of mapped results
  */
 export declare function mapIterable<I, O>(values: Iterable<I>, fn: (value: I) => O): O[];

package/src/lib/iterate.d.ts

@@ -1,6 +1,22 @@
+/**
+ * Callback invoked for each value during iteration. May be sync or async.
+ */
 export type IterateFn<T> = (value: T) => void | Promise<void>;
+/**
+ * Callback invoked for each page of values during iteration. May be sync or async.
+ */
 export type IteratePageFn<T> = (values: T[]) => void | Promise<void>;
 /**
- * Async iteration over the input values in-order.
+ * Iterates over each value in the array sequentially, awaiting each callback before proceeding to the next.
+ *
+ * @param values - Array of values to iterate over.
+ * @param useFn - Callback invoked for each value.
+ *
+ * @example
+ * ```ts
+ * await iterate([1, 2, 3], async (value) => {
+ *   await processItem(value);
+ * });
+ * ```
  */
 export declare function iterate<T>(values: T[], useFn: IterateFn<T>): Promise<void>;

package/src/lib/key.d.ts

@@ -34,27 +34,49 @@ export type ReadMultipleKeysFunction<T, K extends PrimativeKey = PrimativeKey> =
  */
 export type ReadKeysFunction<T, K extends PrimativeKey = PrimativeKey> = MapFunction<ArrayOrValue<T>, K[]>;
 /**
- * Creates a ReadKeysFromFunction using a ReadKeyFunction.
+ * Creates a {@link ReadKeysFunction} from a key-reading function. Handles both single and array inputs,
+ * filtering out null/undefined keys.
  *
- * @param read
+ * @param readKey - Function that extracts one or more keys from a value.
+ * @returns A function that reads keys from a single value or array of values.
+ *
+ * @example
+ * ```ts
+ * const fn = readKeysFunction<string>((x) => x);
+ * fn(['a', 'b', 'c']); // ['a', 'b', 'c']
+ * ```
  */
 export declare function readKeysFunction<T, K extends PrimativeKey = PrimativeKey>(readKey: ReadKeyFunction<T, K> | ReadMultipleKeysFunction<T, K>): ReadKeysFunction<T, K>;
 /**
- * Convenience function for reading all the keys for the input values.
- * @param readKey
- * @param values
- * @returns
+ * Convenience function that reads all keys from an array of values using the provided key-reading function.
+ *
+ * @param readKey - Function that extracts one or more keys from a value.
+ * @param values - Values to read keys from.
+ * @returns An array of all extracted keys.
  */
 export declare function readKeysFrom<T, K extends PrimativeKey = PrimativeKey>(readKey: ReadKeyFunction<T, K> | ReadMultipleKeysFunction<T, K>, values: T[]): K[];
 /**
  * Reads all defined keys from the input objects to a Set.
  */
 export type ReadKeysSetFunction<T, K extends PrimativeKey = PrimativeKey> = MapFunction<T[], Set<K>>;
+/**
+ * Creates a {@link ReadKeysSetFunction} from a key-reading function. Like {@link readKeysFunction} but returns a Set, deduplicating keys.
+ *
+ * @param readKey - Function that extracts one or more keys from a value.
+ * @returns A function that reads keys from values into a Set.
+ *
+ * @example
+ * ```ts
+ * const fn = readKeysSetFunction<string>((x) => x);
+ * fn(['a', 'b', 'a']); // Set { 'a', 'b' }
+ * ```
+ */
 export declare function readKeysSetFunction<T, K extends PrimativeKey = PrimativeKey>(readKey: ReadKeyFunction<T, K> | ReadMultipleKeysFunction<T, K>): ReadKeysSetFunction<T, K>;
 /**
- * Convenience function for reading all the keys for the input values.
- * @param readKey
- * @param values
- * @returns
+ * Convenience function that reads all keys from an array of values into a Set using the provided key-reading function.
+ *
+ * @param readKey - Function that extracts one or more keys from a value.
+ * @param values - Values to read keys from.
+ * @returns A Set of all extracted keys.
  */
 export declare function readKeysSetFrom<T, K extends PrimativeKey = PrimativeKey>(readKey: ReadKeyFunction<T, K> | ReadMultipleKeysFunction<T, K>, values: T[]): Set<K>;

package/src/lib/lifecycle.d.ts

@@ -16,7 +16,16 @@ export interface Destroyable {
  */
 export type DestroyFunction = () => void;
 /**
- * Retains a reference to a single destroy function. When replaced, the previous destroy function is removed.
+ * Retains a reference to a single destroy function. When a new function is set via {@link setDestroyFunction},
+ * the previous one is called first. Useful for managing cleanup of subscriptions or resources that change over time.
+ *
+ * @example
+ * ```ts
+ * const obj = new DestroyFunctionObject();
+ * obj.setDestroyFunction(() => console.log('cleanup A'));
+ * obj.setDestroyFunction(() => console.log('cleanup B')); // logs 'cleanup A'
+ * obj.destroy(); // logs 'cleanup B'
+ * ```
  */
 export declare class DestroyFunctionObject implements Destroyable {
     private _destroy?;

package/src/lib/map/map.d.ts

@@ -1,38 +1,39 @@
 import { type ArrayOrValue } from '../array/array';
 import { type Maybe } from '../value/maybe.type';
 /**
+ * Combines multiple Maps into a single Map. Later maps override earlier values for the same key.
  *
- * @param maps
- * @returns
+ * @param maps - The maps to combine (null/undefined maps are skipped)
+ * @returns A new Map containing all entries
  */
 export declare function combineMaps<K, T>(...maps: Maybe<Map<K, T>>[]): Map<K, T>;
 /**
- * Sets the value to all of the input keys.
+ * Sets the same value for one or more keys in a Map.
  *
- * @param map
- * @param key
- * @param value
- * @returns
+ * @param map - The map to set values on
+ * @param key - A single key or array of keys to set
+ * @param value - The value to set for all keys
+ * @returns The modified map
  */
 export declare function setKeysOnMap<K, T>(map: Map<K, T>, key: ArrayOrValue<K>, value: T): Map<K, T>;
 /**
- * Returns the array of entries from the map as tuples.
+ * Converts a Map to an array of key-value tuples.
  *
- * @param map
- * @returns
+ * @param map - The map to convert
+ * @returns An array of [key, value] tuples
  */
 export declare function mapToTuples<K, T>(map: Map<K, T>): [K, T][];
 /**
- * Expands a map that has array values into key/value tuples.
+ * Expands a Map with array values into individual key/value tuples.
  *
- * @param map
- * @returns
+ * @param map - A Map where values are arrays
+ * @returns An array of [key, value] tuples, one for each element in each array
  */
 export declare function expandArrayMapTuples<K, T>(map: Map<K, T[]>): [K, T][];
 /**
- * Expands the input tuples that may be an ArrayOrValue into tuples that are only key/value tuples.
+ * Expands tuples where values may be arrays into individual key/value tuples.
  *
- * @param values
- * @returns
+ * @param values - Array of [key, ArrayOrValue] tuples to expand
+ * @returns An array of [key, value] tuples
  */
 export declare function expandArrayValueTuples<K, T>(values: [K, ArrayOrValue<T>][]): [K, T][];

package/src/lib/map/map.intersection.d.ts

@@ -6,10 +6,11 @@ export interface MapKeysIntersectionObject<T> {
     [key: string]: ArrayOrValue<T>;
 }
 /**
- * Builds an array from intersection of the input object and input keys that correspond to values that should be part of the result.
+ * Builds an array from the intersection of an object's keys with the provided keys.
+ * For each matching key, the associated value (or values) are added to the result array.
  *
- * @param object
- * @param keys
- * @returns
+ * @param object - The object mapping keys to values
+ * @param keys - The keys to intersect with the object
+ * @returns An array of values from the matching keys
  */
 export declare function mapKeysIntersectionObjectToArray<T>(object: MapKeysIntersectionObject<T>, keys: Iterable<string>): T[];

package/src/lib/map/map.key.d.ts

@@ -8,33 +8,34 @@ import { type Maybe } from '../value/maybe.type';
  */
 export type KeyValueMapFactory<T, K extends PrimativeKey = PrimativeKey> = (values: T[]) => Map<K, T>;
 /**
- * Creates a KeyValueMapFactory with the input ReadKeyFunction.
+ * Creates a KeyValueMapFactory that maps values by their key using a ReadKeyFunction.
  *
- * @param read
- * @returns
+ * @param read - Function that extracts a key from each value
+ * @returns A factory that creates Maps from arrays of values
  */
 export declare function keyValueMapFactory<T, K extends PrimativeKey = PrimativeKey>(read: ReadKeyFunction<T, K>): KeyValueMapFactory<T, K>;
 /**
  * Reads keys off the input values and places them in a Map using a ReadKeyFunction.
  *
- * @param values
- * @param read
- * @returns
+ * @param values - The array of values to map
+ * @param read - Function that extracts a key from each value
+ * @returns A Map keyed by the extracted keys
  */
 export declare function readKeysToMap<T, K extends PrimativeKey = PrimativeKey>(values: T[], read: ReadKeyFunction<T, K>): Map<K, T>;
 /**
- * Creates a KeyValueMapFactory with the input ReadMultipleKeysFunction.
+ * Creates a KeyValueMapFactory that maps values by multiple keys using a ReadMultipleKeysFunction.
+ * Each value can appear under multiple keys.
  *
- * @param read
- * @returns
+ * @param read - Function that extracts multiple keys from each value
+ * @returns A factory that creates Maps from arrays of values
  */
 export declare function multiKeyValueMapFactory<T, K extends PrimativeKey = PrimativeKey>(read: ReadMultipleKeysFunction<T, K>): KeyValueMapFactory<T, K>;
 /**
- * Reads keys off the input values and places them in a Map using a ReadMultipleKeysFunction.
+ * Reads multiple keys off the input values and places them in a Map using a ReadMultipleKeysFunction.
  *
- * @param values
- * @param read
- * @returns
+ * @param values - The array of values to map
+ * @param read - Function that extracts multiple keys from each value
+ * @returns A Map keyed by the extracted keys
  */
 export declare function readMultipleKeysToMap<T, K extends PrimativeKey = PrimativeKey>(values: T[], read: ReadMultipleKeysFunction<T, K>): Map<K, T>;
 /**
@@ -102,9 +103,9 @@ export interface MultiValueMapBuilder<T, K extends PrimativeKey = PrimativeKey>
     get(key: Maybe<K>): T[];
 }
 /**
- * Creates a new MultiValueMapBuilder
+ * Creates a new MultiValueMapBuilder for building Maps where each key maps to an array of values.
  *
- * @returns
+ * @returns A new MultiValueMapBuilder instance
  */
 export declare function multiValueMapBuilder<T, K extends PrimativeKey = PrimativeKey>(): MultiValueMapBuilder<T, K>;
 /**

package/src/lib/misc/host.d.ts

@@ -1,12 +1,15 @@
 import { type Maybe } from '../value/maybe.type';
+/**
+ * Configuration for joining a host and port into a connection string.
+ */
 export interface JoinHostAndPortConfig {
     readonly host: string;
     readonly port: number | string;
 }
 /**
- * Joins the host and port into a string.
+ * Joins the host and port into a "host:port" string.
  *
- * @param config
- * @returns
+ * @param config - The host and port configuration, or null/undefined
+ * @returns The joined string, or null/undefined if config is null/undefined
  */
 export declare function joinHostAndPort(config: Maybe<JoinHostAndPortConfig>): Maybe<string>;

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

@@ -29,9 +29,13 @@ export interface IdBatchFactoryConfig<T, K extends PrimativeKey = PrimativeKey>
  */
 export type IdBatchFactory<T> = AsyncArrayFactory<T>;
 /**
- * Creates an IdBatchFactory
+ * Creates an {@link IdBatchFactory} that generates batches of unique, verified identifiers.
  *
- * @param config
- * @returns
+ * The factory generates identifiers in batches, filters them for uniqueness, and verifies each batch
+ * using the configured verifier. Throws if uniqueness generation fails repeatedly (after 20 attempts).
+ *
+ * @param config - Configuration with the base factory for generating candidates and the verifier for validating them
+ * @returns An async factory function that produces the requested number of valid identifiers
+ * @throws Error if the factory cannot produce enough unique values after repeated attempts
  */
 export declare function idBatchFactory<T, K extends PrimativeKey = PrimativeKey>(config: IdBatchFactoryConfig<T, K>): IdBatchFactory<T>;

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

@@ -35,6 +35,21 @@ export interface SequentialIncrementingNumberStringModelIdFactoryConfig {
     readonly increaseBy?: number;
 }
 /**
- * Creates a ModelIdFactory that generates sequential incrementing encoded NumberStringDencoderString values using the input configuration.
+ * Creates a {@link ModelIdFactory} that generates sequential incrementing encoded string identifiers.
+ *
+ * Each call to the returned factory produces the next identifier in the sequence, encoded using the configured
+ * {@link NumberStringDencoder} (defaults to base-64). Supports starting from a specific index or continuing
+ * from a current index, and an optional transform for post-processing (e.g., padding).
+ *
+ * @param config - Configuration for the starting index, increment step, dencoder, and transform
+ * @returns A factory function that returns the next encoded string identifier on each call
+ * @throws Error if `increaseBy` is 0
+ *
+ * @example
+ * ```ts
+ * const factory = sequentialIncrementingNumberStringModelIdFactory({ startAt: 0 });
+ * const first = factory(); // encoded representation of 0
+ * const second = factory(); // encoded representation of 1
+ * ```
  */
 export declare function sequentialIncrementingNumberStringModelIdFactory(config?: SequentialIncrementingNumberStringModelIdFactoryConfig): ModelIdFactory;

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

@@ -15,6 +15,14 @@ export interface ModelMapFunctions<V extends object, D extends object> {
     from: ModelMapFromFunction<V, D>;
     to: ModelMapToFunction<V, D>;
 }
+/**
+ * Creates bidirectional map functions (`from` and `to`) from a set of {@link ModelFieldConversions}.
+ *
+ * The `to` function converts from the model (V) to data (D), while `from` converts back from data (D) to model (V).
+ *
+ * @param fields - Field conversion definitions for each key in the model
+ * @returns Object with `from` and `to` mapping functions
+ */
 export declare function makeModelMapFunctions<V extends object, D extends object>(fields: ModelFieldConversions<V, D>): ModelMapFunctions<V, D>;
 export type ModelConversionFieldTuple<I extends object> = [keyof I, ModelFieldMapFunction<unknown, unknown>];
 export type ModelConversionFieldValuesConfig<I extends object> = ModelConversionFieldTuple<I>[];
@@ -32,6 +40,14 @@ export interface ModelConversionOptions<I extends object> {
  * A model conversion function. Performs a conversion on all non-null values.
  */
 export type ModelConversionFieldValuesFunction<I extends object, O extends object> = ApplyMapFunctionWithOptions<Maybe<I>, O, ModelConversionOptions<I>>;
+/**
+ * Creates a conversion function that maps fields from an input object to an output object using per-field conversion functions.
+ *
+ * Supports optional filtering by field names and skipping undefined values via {@link ModelConversionOptions}.
+ *
+ * @param fields - Array of `[key, convertFn]` tuples defining how each field is converted
+ * @returns A function that converts an input object to an output object
+ */
 export declare function makeModelConversionFieldValuesFunction<I extends object, O extends object>(fields: ModelConversionFieldValuesConfig<I>): ModelConversionFieldValuesFunction<I, O>;
 /**
  * An object map containing a ModelFieldMapFunctions entry for each key (required and optional) from the generic object.
@@ -45,6 +61,12 @@ export type ModelFieldConversions<V extends object, D extends object> = Required
 export type ModelFieldConversionsConfig<V extends object, D extends object> = Required<{
     [K in keyof V]: ModelFieldMapFunctionsConfig<V[K], TypedMappedModelData<V, D>[K]>;
 }>;
+/**
+ * Converts a {@link ModelFieldConversionsConfig} (with raw config per field) into resolved {@link ModelFieldConversions} (with compiled map functions per field).
+ *
+ * @param config - Configuration object with a conversion config for each model field
+ * @returns Resolved field conversions with compiled `from` and `to` functions
+ */
 export declare function modelFieldConversions<V extends object, D extends object>(config: ModelFieldConversionsConfig<V, D>): ModelFieldConversions<V, D>;
 export type ModelFieldMapFunctions<I = unknown, O = unknown> = {
     readonly from: ModelFieldMapFromFunction<I, O>;
@@ -58,6 +80,12 @@ export type ModelFieldMapFunctionsWithDefaultsConfig<I = unknown, O = unknown> =
     readonly from: ModelFieldMapFromWithDefaultConfig<I, O>;
     readonly to: ModelFieldMapToWithDefaultConfig<I, O>;
 };
+/**
+ * Compiles a {@link ModelFieldMapFunctionsConfig} into resolved {@link ModelFieldMapFunctions} with `from` and `to` mapping functions.
+ *
+ * @param config - Configuration with `from` and `to` field map configs
+ * @returns Compiled field map functions
+ */
 export declare function modelFieldMapFunctions<I = unknown, O = unknown>(config: ModelFieldMapFunctionsConfig<I, O>): ModelFieldMapFunctions<I, O>;
 /**
  * ModelFieldMapFunction configuration that can convert a MaybeValue to the target value.
@@ -91,10 +119,15 @@ export type ModelFieldMapFunction<I = unknown, O = unknown> = MapFunction<Maybe<
 export type ModelFieldMapFromFunction<I, O> = ModelFieldMapFunction<O, I>;
 export type ModelFieldMapToFunction<I, O> = ModelFieldMapFunction<I, O>;
 /**
- * Creates a ModelFieldMapFunction.
+ * Creates a {@link ModelFieldMapFunction} from a config that handles Maybe input values.
+ *
+ * The function handles three cases:
+ * - Non-null input: uses `convert` to transform the value
+ * - Null/undefined input with `convertMaybe`: delegates to that function
+ * - Null/undefined input with `default` or `defaultInput`: uses the appropriate fallback
  *
- * @param config
- * @returns
+ * @param config - Configuration specifying how to convert values and handle null/undefined
+ * @returns A function that maps Maybe input values to output values
  */
 export declare function modelFieldMapFunction<I, O>(config: ModelFieldMapConfig<I, O>): ModelFieldMapFunction<I, O>;
 export type ModelFieldConversionsConfigRef<T extends object, O extends object> = {
@@ -105,14 +138,24 @@ export type ModelFieldConversionsRef<T extends object, O extends object> = {
 };
 export type ToModelFieldConversionsInput<T extends object, O extends object> = ModelFieldConversionsConfigRef<T, O> | ModelFieldConversionsRef<T, O>;
 /**
- * Converts the input to a ModelFieldConversions value.
+ * Resolves a {@link ToModelFieldConversionsInput} to a {@link ModelFieldConversions} value.
  *
- * @param input
- * @returns
+ * Accepts either a pre-built `fieldConversions` reference or a `fields` config that will be compiled.
+ *
+ * @param input - Either a config ref or a pre-built conversions ref
+ * @returns Resolved field conversions
  */
 export declare function toModelFieldConversions<T extends object, O extends object>(input: ToModelFieldConversionsInput<T, O>): Required<{ [K in keyof T]: ModelFieldMapFunctions<T[K], ReplaceType<T, O, any>[K]>; }>;
 export type ModelMapFunctionsRef<T extends object, O extends object> = {
     readonly mapFunctions: ModelMapFunctions<T, O>;
 };
 export type ToModelMapFunctionsInput<T extends object, O extends object> = ToModelFieldConversionsInput<T, O> | ModelMapFunctionsRef<T, O>;
+/**
+ * Resolves a {@link ToModelMapFunctionsInput} to {@link ModelMapFunctions}.
+ *
+ * Accepts a pre-built `mapFunctions` reference, a `fieldConversions` ref, or a `fields` config.
+ *
+ * @param input - Input that can be resolved to model map functions
+ * @returns Bidirectional model map functions
+ */
 export declare function toModelMapFunctions<T extends object, O extends object>(input: ToModelMapFunctionsInput<T, O>): ModelMapFunctions<T, O>;

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

@@ -1,8 +1,18 @@
 import { type ModelFieldMapFunctionsConfig } from './model.conversion';
 /**
- * Field conversion that copies the same value across.
+ * Creates a bidirectional field conversion config that copies values unchanged in both directions.
  *
- * @param defaultValue
- * @returns
+ * When the input is null/undefined, the provided default value is used instead.
+ *
+ * @param defaultOutput - Default value to use when the source value is null/undefined
+ * @returns A {@link ModelFieldMapFunctionsConfig} with identity `from` and `to` conversions
+ *
+ * @example
+ * ```ts
+ * const nameField = copyField('');
+ * // nameField.from.convert('hello') === 'hello'
+ * // nameField.to.convert('hello') === 'hello'
+ * // When input is undefined, returns ''
+ * ```
  */
 export declare function copyField<T>(defaultOutput: T): ModelFieldMapFunctionsConfig<T, T>;

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

@@ -13,4 +13,15 @@ export interface CopyModelFieldConfig<V = unknown> {
  * Used for copying one field from one partial object to a target object.
  */
 export type CopyModelFieldFunction<T> = (from: Partial<T>, target: Partial<T>) => void;
+/**
+ * Creates a function that copies a single field from a partial source object to a partial target object.
+ *
+ * If the field exists on the source, its value (or the configured default if null) is assigned to the target.
+ * If the field does not exist on the source but a default is configured, the default is used.
+ * Otherwise, the target is left unchanged.
+ *
+ * @param key - The property key to copy
+ * @param inputConfig - Optional config with a default value for the field
+ * @returns A function that copies the field from source to target
+ */
 export declare function makeCopyModelFieldFunction<T extends object>(key: keyof T, inputConfig?: Maybe<CopyModelFieldConfig>): CopyModelFieldFunction<T>;