@dereekb/util 13.11.14 → 13.11.15

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

@@ -3,37 +3,37 @@ 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 - The maps to combine (null/undefined maps are skipped)
- * @returns A new Map containing all entries
+ * @param maps - Lookups to merge; nullish entries are skipped.
+ * @returns Combined lookup with later entries overriding earlier ones per key.
  */
 export declare function combineMaps<K, T>(...maps: Maybe<Map<K, T>>[]): Map<K, T>;
 /**
  * Sets the same value for one or more keys in a Map.
  *
- * @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
+ * @param map - Lookup that receives the writes in place.
+ * @param key - One or more keys to associate with `value`.
+ * @param value - Payload assigned to every supplied key.
+ * @returns Same `map` reference after the assignments.
  */
 export declare function setKeysOnMap<K, T>(map: Map<K, T>, key: ArrayOrValue<K>, value: T): Map<K, T>;
 /**
  * Converts a Map to an array of key-value tuples.
  *
- * @param map - The map to convert
- * @returns An array of [key, value] tuples
+ * @param map - Lookup whose entries should be flattened.
+ * @returns Tuple list mirroring the lookup's entry iteration order.
  */
 export declare function mapToTuples<K, T>(map: Map<K, T>): [K, T][];
 /**
  * Expands a Map with array values into individual key/value tuples.
  *
- * @param map - A Map where values are arrays
- * @returns An array of [key, value] tuples, one for each element in each array
+ * @param map - Lookup whose values are arrays to expand.
+ * @returns Flattened tuples — one per element across every keyed array.
  */
 export declare function expandArrayMapTuples<K, T>(map: Map<K, T[]>): [K, T][];
 /**
  * Expands tuples where values may be arrays into individual key/value tuples.
  *
- * @param values - Array of [key, ArrayOrValue] tuples to expand
- * @returns An array of [key, value] tuples
+ * @param values - Tuples whose right-hand side may be a single value or an array.
+ * @returns Flattened tuples emitting one entry per element on each input tuple.
  */
 export declare function expandArrayValueTuples<K, T>(values: [K, ArrayOrValue<T>][]): [K, T][];

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

@@ -9,8 +9,8 @@ export interface MapKeysIntersectionObject<T> {
  * 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 - The object mapping keys to values
- * @param keys - The keys to intersect with the object
- * @returns An array of values from the matching keys
+ * @param object - Lookup whose entries should be activated when their keys are requested.
+ * @param keys - Requested key set restricting which entries contribute values.
+ * @returns Flattened values drawn from entries whose key was requested.
  */
 export declare function mapKeysIntersectionObjectToArray<T>(object: MapKeysIntersectionObject<T>, keys: Iterable<string>): T[];

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

@@ -10,46 +10,48 @@ export type KeyValueMapFactory<T, K extends PrimativeKey = PrimativeKey> = (valu
 /**
  * Creates a KeyValueMapFactory that maps values by their key using a ReadKeyFunction.
  *
+ * @param read - Function that extracts a key from each value.
+ * @returns A factory that creates Maps from arrays of values.
+ *
  * @dbxUtil
  * @dbxUtilCategory value
  * @dbxUtilKind factory
  * @dbxUtilTags map, key, factory, lookup, index
  * @dbxUtilRelated multi-key-value-map-factory, read-keys-to-map
  *
- * @param read - Function that extracts a key from each value
- * @returns A factory that creates Maps from arrays of values
  * @__NO_SIDE_EFFECTS__
  */
 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 - The array of values to map
- * @param read - Function that extracts a key from each value
- * @returns A Map keyed by the extracted keys
+ * @param values - Source items whose keys are derived during indexing.
+ * @param read - Resolver that extracts the comparison key from each value.
+ * @returns Lookup keyed by derived key; the last entry per key wins.
  */
 export declare function readKeysToMap<T, K extends PrimativeKey = PrimativeKey>(values: T[], read: ReadKeyFunction<T, K>): Map<K, T>;
 /**
  * Creates a KeyValueMapFactory that maps values by multiple keys using a ReadMultipleKeysFunction.
  * Each value can appear under multiple keys.
  *
+ * @param read - Function that extracts multiple keys from each value.
+ * @returns A factory that creates Maps from arrays of values.
+ *
  * @dbxUtil
  * @dbxUtilCategory value
  * @dbxUtilKind factory
  * @dbxUtilTags map, key, multi, factory, lookup, index
  * @dbxUtilRelated key-value-map-factory, read-multiple-keys-to-map
  *
- * @param read - Function that extracts multiple keys from each value
- * @returns A factory that creates Maps from arrays of values
  * @__NO_SIDE_EFFECTS__
  */
 export declare function multiKeyValueMapFactory<T, K extends PrimativeKey = PrimativeKey>(read: ReadMultipleKeysFunction<T, K>): KeyValueMapFactory<T, K>;
 /**
  * Reads multiple keys off the input values and places them in a Map using a ReadMultipleKeysFunction.
  *
- * @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
+ * @param values - Source items whose keys are derived during indexing.
+ * @param read - Resolver that extracts every comparison key from each value.
+ * @returns Lookup keyed by every derived key; the last entry per key wins.
  */
 export declare function readMultipleKeysToMap<T, K extends PrimativeKey = PrimativeKey>(values: T[], read: ReadMultipleKeysFunction<T, K>): Map<K, T>;
 /**
@@ -119,14 +121,14 @@ export interface MultiValueMapBuilder<T, K extends PrimativeKey = PrimativeKey>
 /**
  * Creates a new MultiValueMapBuilder for building Maps where each key maps to an array of values.
  *
- * @returns A new MultiValueMapBuilder instance
+ * @returns A new MultiValueMapBuilder instance.
  */
 export declare function multiValueMapBuilder<T, K extends PrimativeKey = PrimativeKey>(): MultiValueMapBuilder<T, K>;
 /**
  * Determines if two maps have the same keys.
  *
- * @param a - The first map
- * @param b - The second map
- * @returns true if the maps have the same keys, false otherwise
+ * @param a - The first map.
+ * @param b - The second map.
+ * @returns True if the maps have the same keys, false otherwise.
  */
 export declare function mapsHaveSameKeys<K>(a: Map<K, unknown>, b: Map<K, unknown>): boolean;

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

@@ -9,7 +9,7 @@ export interface JoinHostAndPortConfig {
 /**
  * Joins the host and port into a "host:port" string.
  *
- * @param config - The host and port configuration, or null/undefined
- * @returns The joined string, or null/undefined if config is null/undefined
+ * @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

@@ -34,15 +34,16 @@ export type IdBatchFactory<T> = AsyncArrayFactory<T>;
  * 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.
+ *
  * @dbxUtil
  * @dbxUtilCategory model
  * @dbxUtilKind factory
  * @dbxUtilTags model, id, batch, factory, async, unique, identifier
  * @dbxUtilRelated sequential-incrementing-number-string-model-id-factory
  *
- * @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
  * @__NO_SIDE_EFFECTS__
  */
 export declare function idBatchFactory<T, K extends PrimativeKey = PrimativeKey>(config: IdBatchFactoryConfig<T, K>): IdBatchFactory<T>;

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

@@ -41,9 +41,9 @@ export interface SequentialIncrementingNumberStringModelIdFactoryConfig {
  * {@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
+ * @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.
  *
  * @dbxUtil
  * @dbxUtilCategory model
@@ -57,6 +57,7 @@ export interface SequentialIncrementingNumberStringModelIdFactoryConfig {
  * const first = factory(); // encoded representation of 0
  * const second = factory(); // encoded representation of 1
  * ```
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function sequentialIncrementingNumberStringModelIdFactory(config?: SequentialIncrementingNumberStringModelIdFactoryConfig): ModelIdFactory;

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

@@ -20,14 +20,15 @@ export interface ModelMapFunctions<V extends object, D extends object> {
  *
  * 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.
+ *
  * @dbxUtil
  * @dbxUtilCategory model
  * @dbxUtilKind factory
  * @dbxUtilTags model, conversion, map, factory, bidirectional, fields
  * @dbxUtilRelated to-model-map-functions, modify-model-map-functions, model-field-conversions
  *
- * @param fields - Field conversion definitions for each key in the model
- * @returns Object with `from` and `to` mapping functions
  * @__NO_SIDE_EFFECTS__
  */
 export declare function makeModelMapFunctions<V extends object, D extends object>(fields: ModelFieldConversions<V, D>): ModelMapFunctions<V, D>;
@@ -52,14 +53,15 @@ export type ModelConversionFieldValuesFunction<I extends object, O extends objec
  *
  * 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 Reusable converter that applies the per-field transforms to any input record.
+ *
  * @dbxUtil
  * @dbxUtilCategory model
  * @dbxUtilKind factory
  * @dbxUtilTags model, conversion, factory, fields, map, transform
  * @dbxUtilRelated make-model-map-functions, model-field-map-functions
  *
- * @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
  * @__NO_SIDE_EFFECTS__
  */
 export declare function makeModelConversionFieldValuesFunction<I extends object, O extends object>(fields: ModelConversionFieldValuesConfig<I>): ModelConversionFieldValuesFunction<I, O>;
@@ -78,8 +80,8 @@ export type ModelFieldConversionsConfig<V extends object, D extends object> = Re
 /**
  * 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
+ * @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> = {
@@ -97,14 +99,15 @@ export type ModelFieldMapFunctionsWithDefaultsConfig<I = unknown, O = unknown> =
 /**
  * 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.
+ *
  * @dbxUtil
  * @dbxUtilCategory model
  * @dbxUtilKind factory
  * @dbxUtilTags model, field, map, factory, conversion, bidirectional
  * @dbxUtilRelated model-field-map-function, make-model-map-functions
  *
- * @param config - Configuration with `from` and `to` field map configs
- * @returns Compiled field map functions
  * @__NO_SIDE_EFFECTS__
  */
 export declare function modelFieldMapFunctions<I = unknown, O = unknown>(config: ModelFieldMapFunctionsConfig<I, O>): ModelFieldMapFunctions<I, O>;
@@ -147,14 +150,15 @@ export type ModelFieldMapToFunction<I, O> = ModelFieldMapFunction<I, O>;
  * - Null/undefined input with `convertMaybe`: delegates to that function
  * - Null/undefined input with `default` or `defaultInput`: uses the appropriate fallback
  *
+ * @param config - Configuration specifying how to convert values and handle null/undefined.
+ * @returns Reusable mapper that handles concrete and nullish inputs via the configured fallbacks.
+ *
  * @dbxUtil
  * @dbxUtilCategory model
  * @dbxUtilKind factory
  * @dbxUtilTags model, field, map, factory, maybe, default, convert
  * @dbxUtilRelated model-field-map-functions, make-model-map-functions
  *
- * @param config - Configuration specifying how to convert values and handle null/undefined
- * @returns A function that maps Maybe input values to output values
  * @__NO_SIDE_EFFECTS__
  */
 export declare function modelFieldMapFunction<I, O>(config: ModelFieldMapConfig<I, O>): ModelFieldMapFunction<I, O>;
@@ -170,8 +174,8 @@ export type ToModelFieldConversionsInput<T extends object, O extends object> = M
  *
  * 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
+ * @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> = {
@@ -183,14 +187,15 @@ export type ToModelMapFunctionsInput<T extends object, O extends object> = ToMod
  *
  * 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.
+ *
  * @dbxUtil
  * @dbxUtilCategory model
  * @dbxUtilKind factory
  * @dbxUtilTags model, conversion, map, factory, normalize, resolve
  * @dbxUtilRelated make-model-map-functions, to-model-field-conversions
  *
- * @param input - Input that can be resolved to model map functions
- * @returns Bidirectional model map functions
  * @__NO_SIDE_EFFECTS__
  */
 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

@@ -4,8 +4,8 @@ import { type ModelFieldMapFunctionsConfig } from './model.conversion';
  *
  * 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
+ * @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

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

@@ -7,7 +7,7 @@ export interface CopyModelFieldConfig<V = unknown> {
     /**
      * Default value if not presented. If default is not defined and there is no value, the key will be ignored entirely.
      */
-    default?: V;
+    readonly default?: V;
 }
 /**
  * Used for copying one field from one partial object to a target object.
@@ -20,15 +20,16 @@ export type CopyModelFieldFunction<T> = (from: Partial<T>, target: Partial<T>) =
  * 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 Reusable mapper that copies the configured field (or fills in the default) per pair.
+ *
  * @dbxUtil
  * @dbxUtilCategory model
  * @dbxUtilKind factory
  * @dbxUtilTags model, copy, field, factory, default
  * @dbxUtilRelated make-model-map-functions, modify-model-map-functions
  *
- * @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
  * @__NO_SIDE_EFFECTS__
  */
 export declare function makeCopyModelFieldFunction<T extends object>(key: keyof T, inputConfig?: Maybe<CopyModelFieldConfig>): CopyModelFieldFunction<T>;

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

@@ -74,8 +74,8 @@ export interface ModelKeyNamePair extends Pick<ModelKeyTypePair, 'key'> {
 export interface ModelKeyTypeNamePair<M extends ModelTypeString = ModelTypeString> extends ModelKeyNamePair, ModelKeyTypePair<M> {
 }
 export interface ReadModelKeyParams<T> {
-    required?: boolean;
-    read: ReadModelKeyFunction<T>;
+    readonly required?: boolean;
+    readonly read: ReadModelKeyFunction<T>;
 }
 export type ReadModelKeyFunction<T> = ReadKeyFunction<T, ModelKey>;
 export type ReadModelTypeFunction<T, M extends ModelTypeString = ModelTypeString> = ReadKeyFunction<T, M>;
@@ -84,15 +84,15 @@ 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
+ * @param model - Model to read the key from.
+ * @returns The model's `id` value.
  */
 export declare const readUniqueModelKey: (model: UniqueModel) => string | undefined;
 /**
  * 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
+ * @param keys - Array of model keys that may contain duplicates.
+ * @returns Array containing only unique keys.
  *
  * @example
  * ```ts
@@ -124,11 +124,11 @@ export declare function readModelKeysFromObjects<T extends UniqueModel>(input: T
 /**
  * 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
+ * @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>[];
 /**
@@ -172,14 +172,15 @@ export declare function makeModelMap<T>(input: T[], read: ReadModelKeyFunction<T
  *
  * 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.
+ *
  * @dbxUtil
  * @dbxUtilCategory model
  * @dbxUtilTags model, map, key, multi, relation, index, lookup
  * @dbxUtilRelated make-model-map, read-model-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
  * @__NO_SIDE_EFFECTS__
  */
 export declare function makeMultiModelKeyMap<T>(input: T[], read: ReadRelationKeysFunction<T>): MultiModelKeyMap<T>;
@@ -188,13 +189,13 @@ export declare function makeMultiModelKeyMap<T>(input: T[], read: ReadRelationKe
  *
  * 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
- * @param config.useModel - handler invoked when the input is a model object; if omitted, the model's key is passed to `useKey` instead
- * @param config.useKey - handler invoked when the input is a model key string
- * @param config.required - when true, throws an error if the input is nullish; defaults to false
- * @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
+ * @param input - A model object or a model key string.
+ * @param config - Handlers for model and key cases, plus whether input is required.
+ * @param config.useModel - Handler invoked when the input is a model object; if omitted, the model's key is passed to `useKey` instead.
+ * @param config.useKey - Handler invoked when the input is a model key string.
+ * @param config.required - When true, throws an error if the input is nullish; defaults to false.
+ * @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;
@@ -204,19 +205,19 @@ export declare function useModelOrKey<O, T extends UniqueModel>(input: ModelOrKe
 /**
  * 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
+ * @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>[];
+export declare function readModelKeys<T extends UniqueModel>(input: Maybe<ModelOrKey<T>>[], 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
+ * @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>;
+export declare function requireModelKey<T extends UniqueModel>(input: Maybe<ModelOrKey<T>>): Maybe<ModelKey>;
 /**
  * Reads a model key from a value that may be a model object, a key string, or undefined.
  *
@@ -227,36 +228,36 @@ export declare function requireModelKey<T extends UniqueModel>(input: ModelOrKey
  * @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>;
+export declare function readModelKey<T>(input: Maybe<ModelOrKey<T>>, params: ReadModelKeyParams<T>): Maybe<ModelKey>;
+export declare function readModelKey<T extends UniqueModel>(input: Maybe<ModelOrKey<T>>, 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
+ * @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
+ * @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
+ * @throws {Error} Always — this function never returns normally.
  */
 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
+ * @param pair - The type/key pair to encode.
+ * @returns Encoded string representation.
  *
  * @example
  * ```ts
@@ -268,8 +269,8 @@ 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
+ * @param linkKey - Encoded string to decode.
+ * @returns The decoded type/key pair.
  *
  * @example
  * ```ts
@@ -293,15 +294,16 @@ export type ModelTypeDataPairFactory<T, M extends ModelTypeString = ModelTypeStr
  *
  * 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.
+ *
  * @dbxUtil
  * @dbxUtilCategory model
  * @dbxUtilKind factory
  * @dbxUtilTags model, type, pair, factory, wrap
  * @dbxUtilRelated read-model-key, encode-model-key-type-pair
  *
- * @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
  * @__NO_SIDE_EFFECTS__
  */
 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

@@ -15,8 +15,8 @@ export type PartialModelModifier<V extends object, D extends object> = Partial<M
  *
  * 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
+ * @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> {
@@ -47,14 +47,15 @@ export interface ModifyModelMapFunctionsConfig<V extends object, D extends objec
  *
  * 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.
+ *
  * @dbxUtil
  * @dbxUtilCategory model
  * @dbxUtilKind factory
  * @dbxUtilTags model, map, modify, factory, modifier, copy
  * @dbxUtilRelated make-model-map-functions, modify-model-map-function
  *
- * @param config - Configuration with the base map functions, modifiers, and copy options
- * @returns New model map functions with modifiers applied before each conversion
  * @__NO_SIDE_EFFECTS__
  */
 export declare function modifyModelMapFunctions<V extends object, D extends object>(config: ModifyModelMapFunctionsConfig<V, D>): ModelMapFunctions<V, D>;
@@ -64,16 +65,17 @@ export declare function modifyModelMapFunctions<V extends object, D extends obje
  * 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 - 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.
+ *
  * @dbxUtil
  * @dbxUtilCategory model
  * @dbxUtilKind factory
  * @dbxUtilTags model, map, modify, factory, modifier, wrap
  * @dbxUtilRelated modify-model-map-functions, model-field-map-function
  *
- * @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
  * @__NO_SIDE_EFFECTS__
  */
 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

@@ -5,14 +5,15 @@ export type ReadableStreamToStringFunction = (stream: NodeJS.ReadableStream) =>
 /**
  * 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 Reusable consumer that drains a stream and resolves with its decoded contents.
+ *
  * @dbxUtil
  * @dbxUtilCategory nodejs
  * @dbxUtilKind factory
  * @dbxUtilTags nodejs, stream, readable, string, factory, encoding
  * @dbxUtilRelated readable-stream-to-buffer, readable-stream-to-base64
  *
- * @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
  * @__NO_SIDE_EFFECTS__
  */
 export declare function readableStreamToStringFunction(encoding: BufferEncoding): ReadableStreamToStringFunction;
@@ -23,8 +24,8 @@ export declare const readableStreamToBase64: ReadableStreamToStringFunction;
 /**
  * Reads all data from a Node.js ReadableStream and concatenates it into a single Buffer.
  *
- * @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
+ * @param stream - The readable stream to consume.
+ * @returns Promise resolving to a Buffer containing all stream data.
+ * @throws {Error} If the stream emits an error event; the returned promise rejects with that error.
  */
 export declare function readableStreamToBuffer(stream: NodeJS.ReadableStream): Promise<Buffer>;