@dereekb/util 13.0.5 → 13.0.7

package/src/lib/object/object.filter.pojo.d.ts

@@ -2,18 +2,53 @@ import { type ArrayOrValue } from './../array/array';
 import { type Maybe } from '../value/maybe.type';
 import { type FilterKeyValueTuplesInput, type KeyValueTuple, type KeyValueTupleFilter, KeyValueTypleValueFilter } from './object.filter.tuple';
 /**
- * Assigns all undefined values from one or more objects into the target object.
+ * Assigns all non-filtered values from one or more source objects into the target object.
  *
- * @param object
+ * Builds a template from the source objects (in order, so later sources win) and applies it to the target.
+ * By default, undefined values in the source objects are excluded from the template, so they will not override existing target values.
+ *
+ * @param target - The object to override values on.
+ * @param config - Configuration for the override operation.
+ * @param config.copy - Whether to return a shallow copy instead of mutating the target. Defaults to `false`.
+ * @param config.from - One or more source objects whose values will be applied to the target.
+ * @param config.filter - Optional filter to control which key/value pairs from sources are included. Defaults to filtering out `undefined` values.
+ * @returns The modified target (or a copy if `copy` is `true`).
+ *
+ * @example
+ * ```typescript
+ * const target = { a: 1, b: 2 };
+ * overrideInObject(target, { from: [{ a: 10, c: 3 }] });
+ * // target is now { a: 10, b: 2, c: 3 }
+ *
+ * // undefined values in source are ignored by default:
+ * overrideInObject(target, { from: [{ a: undefined, b: 99 }] });
+ * // target.a remains 10, target.b becomes 99
+ * ```
  */
 export declare function overrideInObject<T extends object>(target: Partial<T>, { copy, from, filter }: {
     copy?: boolean;
     from: ArrayOrValue<Partial<T>>;
     filter?: KeyValueTupleFilter<T>;
 }): Partial<T>;
+/**
+ * Applies a pre-built template of values to a target object, returning the modified target.
+ */
 export type OverrideInObjectFunction<T> = (target: Partial<T>) => Partial<T>;
+/**
+ * Factory that takes an array of source objects and produces an {@link OverrideInObjectFunction}
+ * that applies the merged template to any target.
+ */
 export type OverrideInObjectFunctionFactory<T> = (from: Partial<T>[]) => OverrideInObjectFunction<T>;
+/**
+ * Configuration for {@link overrideInObjectFunctionFactory}.
+ */
 export interface OverrideInObjectFunctionFactoryConfig<T extends object> {
+    /**
+     * Filter controlling which key/value pairs from sources are included in the template.
+     *
+     * Accepts a {@link KeyValueTypleValueFilter} enum value or a {@link KeyValueTupleFilter} object.
+     * When not provided, the default filter removes `undefined` values (i.e., `KeyValueTypleValueFilter.UNDEFINED`).
+     */
     filter?: FilterKeyValueTuplesInput<T>;
     /**
      * Whether or not to return a copy of the input value, rather than change it directly.
@@ -32,183 +67,562 @@ export interface OverrideInObjectFunctionFactoryConfig<T extends object> {
      */
     dynamic?: boolean;
 }
+/**
+ * Creates an {@link OverrideInObjectFunctionFactory} that merges source objects into a template,
+ * then applies that template to target objects.
+ *
+ * The template is built by iterating the source objects in order (later sources override earlier ones),
+ * filtering each through the configured filter. When applied to a target, the template's values overwrite
+ * corresponding keys on the target.
+ *
+ * By default, `undefined` values in sources are excluded from the template.
+ *
+ * @param config - Configuration controlling filtering, copying, and caching behavior.
+ * @returns A factory function that accepts source objects and returns an override function.
+ *
+ * @example
+ * ```typescript
+ * const factory = overrideInObjectFunctionFactory({ copy: true });
+ * const overrideFn = factory([{ color: 'red' }, { size: 10 }]);
+ * const result = overrideFn({ color: 'blue', size: 5 });
+ * // result is { color: 'red', size: 10 } (a new copy)
+ * ```
+ */
 export declare function overrideInObjectFunctionFactory<T extends object>({ filter, copy, dynamic }: OverrideInObjectFunctionFactoryConfig<T>): OverrideInObjectFunctionFactory<T>;
 /**
- * Merges all input objects into one.
+ * Merges all input objects into a single object.
+ *
+ * Objects are applied left-to-right, so the right-most (last) item in the array has the highest priority.
+ * `Maybe` values (null/undefined entries in the array) are silently ignored.
+ *
+ * By default, `undefined` values within each source object are excluded from the merge,
+ * meaning an `undefined` value will not overwrite a previously set value.
  *
- * The order of overrides is kept, so the right-most item in the array will have priority over all objects before it.
+ * @param objects - Array of objects (or null/undefined) to merge together.
+ * @param filter - Optional filter controlling which key/value pairs are included. Defaults to filtering out `undefined` values (`KeyValueTypleValueFilter.UNDEFINED`).
+ * @returns A new object containing the merged result.
  *
- * @param objects
+ * @example
+ * ```typescript
+ * const result = mergeObjects([{ a: 1, b: 2 }, { b: 3, c: 4 }]);
+ * // result is { a: 1, b: 3, c: 4 }
+ *
+ * // undefined values in sources do not override:
+ * const result2 = mergeObjects([{ a: 1 }, { a: undefined, b: 2 }]);
+ * // result2 is { a: 1, b: 2 }
+ * ```
  */
 export declare function mergeObjects<T extends object>(objects: Maybe<Partial<T>>[], filter?: FilterKeyValueTuplesInput<T>): Partial<T>;
 /**
- * Merges all values from the input objects into a single object.
- *
- * The order of overrides is kept, so the right-most item in the array will have priority over all objects before it.
+ * Function that merges an array of partial objects into a single object.
+ * Objects are applied left-to-right, so the last item in the array has the highest priority.
  */
 export type MergeObjectsFunction<T extends object> = (objects: Maybe<Partial<T>>[]) => Partial<T>;
+/**
+ * Creates a reusable {@link MergeObjectsFunction} with a pre-configured filter.
+ *
+ * Useful when you need to merge objects multiple times with the same filter configuration.
+ * By default, `undefined` values are filtered out of the result (`KeyValueTypleValueFilter.UNDEFINED`).
+ *
+ * @param filter - Optional filter controlling which key/value pairs are included. Defaults to filtering out `undefined` values.
+ * @returns A reusable merge function.
+ *
+ * @example
+ * ```typescript
+ * const merge = mergeObjectsFunction();
+ * const result = merge([{ a: 1 }, { b: 2 }, { a: 3 }]);
+ * // result is { a: 3, b: 2 }
+ *
+ * // With null filter to also exclude null values:
+ * const mergeNoNulls = mergeObjectsFunction(KeyValueTypleValueFilter.NULL);
+ * ```
+ */
 export declare function mergeObjectsFunction<T extends object>(filter?: FilterKeyValueTuplesInput<T>): MergeObjectsFunction<T>;
 /**
- * Returns a copy of the input object with all undefined (and null values if filterNull=true) values filtered/removed from it.
+ * Returns a copy of the input object with all `undefined` values removed.
+ * When `filterNull` is `true`, `null` values are also removed.
  *
- * @param obj
- * @returns
+ * This is a convenience wrapper around {@link filterOnlyUndefinedValues} and {@link filterNullAndUndefinedValues}.
+ *
+ * @param obj - The object to filter.
+ * @param filterNull - If `true`, both `null` and `undefined` values are removed. Defaults to `false`.
+ * @returns A shallow copy of the object with filtered values removed.
+ *
+ * @example
+ * ```typescript
+ * filterUndefinedValues({ a: 1, b: undefined, c: null });
+ * // { a: 1, c: null }
+ *
+ * filterUndefinedValues({ a: 1, b: undefined, c: null }, true);
+ * // { a: 1 }
+ * ```
  */
 export declare function filterUndefinedValues<T extends object>(obj: T, filterNull?: boolean): T;
 /**
- * Returns a copy of the input object with all undefined values filtered from it.
+ * Pre-built filter that returns a copy of the input object with all `undefined` values removed.
+ * Keys with `null` or other falsy values are retained.
  *
- * @param obj
- * @returns
+ * @example
+ * ```typescript
+ * filterOnlyUndefinedValues({ a: 1, b: undefined, c: null });
+ * // { a: 1, c: null }
+ * ```
  */
 export declare const filterOnlyUndefinedValues: GeneralFilterFromPOJOFunction;
 /**
- * Returns a copy of the input object with all null and undefined values filtered from it.
+ * Pre-built filter that returns a copy of the input object with all `null` and `undefined` values removed.
+ * Keys with other falsy values (0, false, '') are retained.
  *
- * @param obj
- * @returns
+ * @example
+ * ```typescript
+ * filterNullAndUndefinedValues({ a: 1, b: undefined, c: null, d: 0 });
+ * // { a: 1, d: 0 }
+ * ```
  */
 export declare const filterNullAndUndefinedValues: GeneralFilterFromPOJOFunction;
 /**
- * Returns a copy of the input object with all empty values filtered from it.
+ * Pre-built filter that returns a copy of the input object with all empty values removed.
+ * Empty values include `null`, `undefined`, empty strings (`''`), empty arrays (`[]`), and empty objects (`{}`).
  *
- * @param obj
- * @returns
+ * @example
+ * ```typescript
+ * filterEmptyPojoValues({ a: 1, b: '', c: [], d: null, e: 'hello' });
+ * // { a: 1, e: 'hello' }
+ * ```
  */
 export declare const filterEmptyPojoValues: GeneralFilterFromPOJOFunction;
 /**
- * Returns a copy of the input object with all falsy and empty filtered from it.
+ * Pre-built filter that returns a copy of the input object with all falsy and empty values removed.
+ * Removes `null`, `undefined`, `0`, `false`, `''`, empty arrays, and empty objects.
  *
- * @param obj
- * @returns
+ * @example
+ * ```typescript
+ * filterFalsyAndEmptyValues({ a: 1, b: false, c: 0, d: '', e: 'hello' });
+ * // { a: 1, e: 'hello' }
+ * ```
  */
 export declare const filterFalsyAndEmptyValues: GeneralFilterFromPOJOFunction;
 /**
- * Returns all keys that are not associated with an undefined value.
+ * Pre-built function that returns all keys from a POJO whose values are not `undefined`.
+ * Keys with `null` or other falsy values are included in the result.
  *
- * @param obj
- * @returns
+ * @example
+ * ```typescript
+ * allNonUndefinedKeys({ a: 'test', b: undefined, c: null, d: 0 });
+ * // ['a', 'c', 'd']
+ * ```
  */
 export declare const allNonUndefinedKeys: GeneralFindPOJOKeysFunction;
 /**
- * Returns all keys that are not associated with a falsy or empty value.
+ * Pre-built function that returns all keys from a POJO whose values are not falsy or empty.
+ * Excludes keys with `null`, `undefined`, `0`, `false`, `''`, empty arrays, or empty objects.
  *
- * @param obj
- * @returns
+ * @example
+ * ```typescript
+ * allFalsyOrEmptyKeys({ a: 'test', b: false, c: 0, d: null });
+ * // ['a']
+ * ```
  */
 export declare const allFalsyOrEmptyKeys: GeneralFindPOJOKeysFunction;
 /**
- * Returns all keys that are not associated with a null/undefined value.
+ * Pre-built function that returns all keys from a POJO whose values are not `null` or `undefined`.
+ * Keys with other falsy values (0, false, '') are included.
  *
- * @param obj
- * @returns
+ * @example
+ * ```typescript
+ * allMaybeSoKeys({ a: 'test', b: undefined, c: null, d: 0 });
+ * // ['a', 'd']
+ * ```
  */
 export declare const allMaybeSoKeys: GeneralFindPOJOKeysFunction;
 /**
- * Finds keys from the POJO that meet the filter.
+ * Finds and returns keys from the POJO whose values pass the given filter.
+ *
+ * The filter determines which values are considered "matching" — matched values have their keys included in the result.
+ * For example, using `KeyValueTypleValueFilter.UNDEFINED` returns all keys whose values are NOT `undefined`.
  *
- * @param obj
- * @param filter
- * @returns
+ * @param obj - The object to inspect.
+ * @param filter - A {@link FilterKeyValueTuplesInput} controlling which key/value pairs match. Required (no default).
+ * @returns Array of keys whose values pass the filter.
+ *
+ * @example
+ * ```typescript
+ * findPOJOKeys({ a: 1, b: undefined, c: null }, KeyValueTypleValueFilter.NULL);
+ * // ['a'] — only 'a' has a non-null, non-undefined value
+ * ```
  */
 export declare function findPOJOKeys<T extends object>(obj: T, filter: FilterKeyValueTuplesInput<T>): (keyof T)[];
 /**
- * Finds and finds the number of keys from the POJO that meet the filter.
+ * Function that returns an array of keys from a POJO whose values pass a pre-configured filter.
  */
 export type FindPOJOKeysFunction<T> = (obj: T) => (keyof T)[];
+/**
+ * Generic version of {@link FindPOJOKeysFunction} that accepts any object type.
+ */
 export type GeneralFindPOJOKeysFunction = <T extends object>(obj: T) => (keyof T)[];
+/**
+ * Creates a reusable {@link FindPOJOKeysFunction} with a pre-configured filter.
+ *
+ * The returned function inspects each key/value pair on the input object and collects keys
+ * whose values pass the filter.
+ *
+ * @param filter - A {@link FilterKeyValueTuplesInput} controlling which values match. Required (no default).
+ * @returns A reusable function that returns matching keys from any input object.
+ *
+ * @example
+ * ```typescript
+ * const findDefinedKeys = findPOJOKeysFunction(KeyValueTypleValueFilter.UNDEFINED);
+ * findDefinedKeys({ a: 1, b: undefined, c: 'hello' });
+ * // ['a', 'c']
+ * ```
+ */
 export declare function findPOJOKeysFunction<T extends object>(filter: FilterKeyValueTuplesInput<T>): FindPOJOKeysFunction<T>;
 /**
- * Finds and counts the number of keys from the POJO that meet the filter.
+ * Counts the number of keys on the POJO whose values pass the given filter.
  *
- * @param obj
- * @param filter
- * @returns
+ * By default, counts all keys whose values are not `undefined` (`KeyValueTypleValueFilter.UNDEFINED`).
+ *
+ * @param obj - The object to inspect.
+ * @param filter - A {@link FilterKeyValueTuplesInput} controlling which values are counted. Defaults to `KeyValueTypleValueFilter.UNDEFINED`.
+ * @returns The number of keys whose values pass the filter.
+ *
+ * @example
+ * ```typescript
+ * countPOJOKeys({ a: 1, b: undefined, c: null });
+ * // 2 — 'a' and 'c' are not undefined
+ *
+ * countPOJOKeys({ a: 1, b: undefined, c: null }, KeyValueTypleValueFilter.NULL);
+ * // 1 — only 'a' is not null or undefined
+ * ```
  */
 export declare function countPOJOKeys<T extends object>(obj: T, filter?: FilterKeyValueTuplesInput<T>): number;
 /**
- * Finds and counts the number of keys from the POJO that meet the filter.
+ * Function that counts the number of keys on an object whose values pass a pre-configured filter.
  */
 export type CountPOJOKeysFunction<T> = (obj: T) => number;
+/**
+ * Creates a reusable {@link CountPOJOKeysFunction} with a pre-configured filter.
+ *
+ * By default, counts all keys whose values are not `undefined` (`KeyValueTypleValueFilter.UNDEFINED`).
+ *
+ * @param filter - A {@link FilterKeyValueTuplesInput} controlling which values are counted. Defaults to `KeyValueTypleValueFilter.UNDEFINED`.
+ * @returns A reusable function that counts matching keys on any input object.
+ *
+ * @example
+ * ```typescript
+ * const countDefined = countPOJOKeysFunction();
+ * countDefined({ a: 1, b: undefined, c: 'test' });
+ * // 2
+ * ```
+ */
 export declare function countPOJOKeysFunction<T extends object>(filter?: FilterKeyValueTuplesInput<T>): CountPOJOKeysFunction<T>;
+/**
+ * Configuration for {@link filterFromPOJO} and {@link filterFromPOJOFunction}.
+ */
 export interface FilterFromPOJO<T extends object> {
+    /**
+     * Whether to return a shallow copy of the object instead of mutating the original.
+     * Defaults to `false` when used via {@link filterFromPOJOFunction}, but the pre-built
+     * constants (e.g., {@link filterOnlyUndefinedValues}) use `true`.
+     */
     copy?: boolean;
+    /**
+     * Filter determining which values to remove. Accepts a {@link KeyValueTypleValueFilter} enum or a {@link KeyValueTupleFilter} object (without `inverse`).
+     * Defaults to `{ valueFilter: KeyValueTypleValueFilter.UNDEFINED }`, which removes `undefined` values.
+     */
     filter?: Omit<FilterKeyValueTuplesInput<T>, 'inverse'>;
 }
 /**
- * Removes values, per the the filter config, from the input object.
+ * Removes values from the input object based on the filter configuration.
+ *
+ * By default, removes `undefined` values and does NOT copy the object (mutates in place).
+ * Pass `{ copy: true }` to get a new object without modifying the original.
+ *
+ * @param obj - The POJO to filter values from.
+ * @param config - Configuration for filtering and copying behavior. Defaults to removing `undefined` values without copying.
+ * @returns The filtered object (either the mutated original or a shallow copy, depending on `config.copy`).
  *
- * @param obj POJO to remove undefined values from.
- * @param copy Whether or not to return a copy of the input object. Default is true.
+ * @example
+ * ```typescript
+ * // Remove undefined values (default):
+ * filterFromPOJO({ a: 1, b: undefined, c: 'hello' });
+ * // { a: 1, c: 'hello' }
+ *
+ * // Remove null and undefined values:
+ * filterFromPOJO({ a: 1, b: null, c: undefined }, { filter: { valueFilter: KeyValueTypleValueFilter.NULL } });
+ * // { a: 1 }
+ * ```
  */
 export declare function filterFromPOJO<T extends object>(obj: T, config?: FilterFromPOJO<T>): T;
 /**
- * Removes values from the input object.
- *
- * @param obj POJO to remove undefined values from.
- * @param copy Whether or not to return a copy of the input object. Default is true.
+ * Function that removes filtered values from an input object.
+ * Accepts an optional `copyOverride` parameter to control copy behavior per-call.
  */
 export type FilterFromPOJOFunction<T> = (input: T, copyOverride?: Maybe<boolean>) => T;
+/**
+ * Generic version of {@link FilterFromPOJOFunction} that accepts any object type.
+ */
 export type GeneralFilterFromPOJOFunction<X = object> = <T extends X>(input: T) => T;
+/**
+ * Creates a reusable {@link FilterFromPOJOFunction} with a pre-configured filter and copy behavior.
+ *
+ * The returned function removes key/value pairs that match the filter from the input object.
+ * Internally, the filter is inverted so that matching values are deleted while non-matching values are retained.
+ *
+ * By default, removes `undefined` values (`KeyValueTypleValueFilter.UNDEFINED`) and does not copy (`copy: false`).
+ *
+ * @param config - Configuration for filtering and copying. Defaults to `{ copy: false, filter: { valueFilter: KeyValueTypleValueFilter.UNDEFINED } }`.
+ * @returns A reusable filter function. The returned function also accepts a `copyOverride` argument to override the copy behavior per-call.
+ *
+ * @example
+ * ```typescript
+ * // Default: removes undefined values, mutates in place
+ * const filterUndef = filterFromPOJOFunction();
+ * const obj = { a: 1, b: undefined };
+ * filterUndef(obj); // obj is now { a: 1 }
+ *
+ * // With copy and null filter:
+ * const filterNulls = filterFromPOJOFunction({ copy: true, filter: { valueFilter: KeyValueTypleValueFilter.NULL } });
+ * const result = filterNulls({ a: 1, b: null, c: undefined });
+ * // result is { a: 1 }, original is unchanged
+ * ```
+ */
 export declare function filterFromPOJOFunction<T extends object>({ copy, filter: inputFilter }?: FilterFromPOJO<T>): FilterFromPOJOFunction<T>;
 /**
- * Convenience function from filterFromPOJOFunction with copy set to false and using the default filter.
+ * Pre-built {@link FilterFromPOJOFunction} that removes `undefined` values by mutating the input object (no copy).
+ *
+ * Used internally as the default filter for {@link overrideInObjectFunctionFactory} when no filter is provided.
+ *
+ * @example
+ * ```typescript
+ * const obj = { a: 1, b: undefined };
+ * defaultFilterFromPOJOFunctionNoCopy(obj);
+ * // obj is now { a: 1 }
+ * ```
  */
 export declare const defaultFilterFromPOJOFunctionNoCopy: FilterFromPOJOFunction<object>;
+/**
+ * Assigns filtered values from `obj` onto `target`.
+ *
+ * By default, only non-`undefined` values from `obj` are assigned, and a copy of `target` is returned (the original is not mutated).
+ *
+ * @param target - The object to assign values onto.
+ * @param obj - The source object whose matching values will be assigned.
+ * @param input - Optional filter/copy configuration. Defaults to `KeyValueTypleValueFilter.UNDEFINED` with `copy: true`.
+ * @returns The target with values assigned (either a copy or the original, depending on configuration).
+ *
+ * @example
+ * ```typescript
+ * const target = { a: 1, b: 2 };
+ * const result = assignValuesToPOJO(target, { a: 10, b: undefined });
+ * // result is { a: 10, b: 2 } (copy), target unchanged
+ * ```
+ */
 export declare function assignValuesToPOJO<T extends object, K extends keyof T = keyof T>(target: T, obj: T, input?: AssignValuesToPOJOFunctionInput<T, K>): T;
+/**
+ * Overload that always returns a copy of the target with values assigned.
+ */
 export type AssignValuesToPOJOCopyFunction<T> = (target: T, obj: T, returnCopy: true) => T;
+/**
+ * Overload that mutates and returns the original target with values assigned.
+ */
 export type AssignValuesToPOJONoCopyFunction<T> = <I extends T>(target: I, obj: T, returnCopy: false) => I;
 /**
- * Assigns values from the object to the target based on the configuration, and returns the result.
+ * Function that assigns filtered values from a source object onto a target object.
  *
- * Additional argument available to return a copy instead of assigning to the input value.
+ * Accepts an optional third argument `returnCopy` to override the default copy behavior per-call.
+ * The `_returnCopyByDefault` property indicates the configured default copy behavior.
  */
 export type AssignValuesToPOJOFunction<T> = ((target: T, obj: T, returnCopy?: boolean) => T) & AssignValuesToPOJOCopyFunction<T> & AssignValuesToPOJONoCopyFunction<T> & {
     readonly _returnCopyByDefault: boolean;
 };
+/**
+ * Configuration for {@link assignValuesToPOJOFunction}.
+ *
+ * Can be a simple {@link KeyValueTypleValueFilter} enum value, or a {@link KeyValueTupleFilter} object
+ * with an additional `copy` property. When a simple enum value is provided, `copy` defaults to `true`.
+ */
 export type AssignValuesToPOJOFunctionInput<T extends object = object, K extends keyof T = keyof T> = KeyValueTypleValueFilter | (KeyValueTupleFilter<T, K> & {
     /**
-     * Whether or not to copy the object before assigning values, and returning the new object.
+     * Whether or not to copy the target object before assigning values, returning the new object.
      *
      * True by default.
      */
     copy?: boolean;
 });
 /**
- * Creates a AssignValuesToPOJOFunction from the input values.
+ * Creates a reusable {@link AssignValuesToPOJOFunction} with a pre-configured filter and copy behavior.
+ *
+ * The returned function assigns key/value pairs from a source object onto a target, skipping pairs
+ * that are filtered out. By default, `undefined` values are filtered out (`KeyValueTypleValueFilter.UNDEFINED`)
+ * and the target is copied before assignment (`copy: true`).
+ *
+ * @param input - Filter and copy configuration. Defaults to `KeyValueTypleValueFilter.UNDEFINED` (filter undefined, copy target).
+ * @returns A reusable assign function with a `_returnCopyByDefault` property indicating the configured copy behavior.
  *
- * @param input
- * @returns
+ * @example
+ * ```typescript
+ * // Default: filters undefined, returns a copy
+ * const assign = assignValuesToPOJOFunction();
+ * const target = { a: 1, b: 2 };
+ * const result = assign(target, { a: 10, b: undefined });
+ * // result is { a: 10, b: 2 }, target is unchanged
+ *
+ * // With NULL filter and no copy:
+ * const assignNoNulls = assignValuesToPOJOFunction({ valueFilter: KeyValueTypleValueFilter.NULL, copy: false });
+ * ```
  */
 export declare function assignValuesToPOJOFunction<T extends object, K extends keyof T = keyof T>(input?: AssignValuesToPOJOFunctionInput<T, K>): AssignValuesToPOJOFunction<T>;
 /**
- * Reads values from matching keys based on the filter and puts them into an array.
+ * Extracts values from the POJO whose key/value pairs pass the given filter, returning them as an array.
+ *
+ * By default, only non-`undefined` values are included (`KeyValueTypleValueFilter.UNDEFINED`).
+ *
+ * @param target - The object to extract values from.
+ * @param filter - A {@link FilterKeyValueTuplesInput} controlling which values are included. Defaults to `KeyValueTypleValueFilter.UNDEFINED`.
+ * @returns Array of values whose key/value pairs passed the filter.
+ *
+ * @example
+ * ```typescript
+ * valuesFromPOJO({ a: 1, b: undefined, c: 'hello' });
+ * // [1, 'hello']
+ *
+ * valuesFromPOJO({ a: 1, b: null, c: 'hello' }, KeyValueTypleValueFilter.NULL);
+ * // [1, 'hello']  — null excluded
+ * ```
  */
 export declare function valuesFromPOJO<O = unknown, I extends object = object>(target: I, filter?: FilterKeyValueTuplesInput<I>): O[];
 /**
- * Reads values from matching keys based on the filter and puts them into an array.
+ * Function that extracts values from a POJO whose key/value pairs pass a pre-configured filter.
  */
 export type ValuesFromPOJOFunction<O = unknown, I extends object = object> = (obj: I) => O[];
+/**
+ * Creates a reusable {@link ValuesFromPOJOFunction} with a pre-configured filter.
+ *
+ * The returned function iterates each key/value pair on the input object, collects values
+ * from pairs that pass the filter, and returns them as an array.
+ *
+ * By default, only non-`undefined` values are included (`KeyValueTypleValueFilter.UNDEFINED`).
+ *
+ * @param filter - A {@link FilterKeyValueTuplesInput} controlling which values are included. Defaults to `KeyValueTypleValueFilter.UNDEFINED`.
+ * @returns A reusable function that extracts matching values from any input object.
+ *
+ * @example
+ * ```typescript
+ * const getDefinedValues = valuesFromPOJOFunction();
+ * getDefinedValues({ a: 1, b: undefined, c: 'test' });
+ * // [1, 'test']
+ *
+ * const getNonNullValues = valuesFromPOJOFunction(KeyValueTypleValueFilter.NULL);
+ * getNonNullValues({ a: 1, b: null, c: undefined });
+ * // [1]
+ * ```
+ */
 export declare function valuesFromPOJOFunction<O = unknown, I extends object = object>(filter?: FilterKeyValueTuplesInput<I>): ValuesFromPOJOFunction<O, I>;
 /**
- * Returns a FilterTuplesOnPOJOFunction that returns an object that contains only the input keys, or does not contain the input keys if invertFilter is true.
+ * Creates a {@link FilterTuplesOnPOJOFunction} that retains only keys present in `keysToFilter`,
+ * or excludes them if `invertFilter` is `true`.
  *
- * @param keysToFilter
- * @returns
+ * Always returns a new object (never mutates the input).
+ *
+ * @param keysToFilter - The set of keys to include (or exclude when inverted).
+ * @param invertFilter - When `true`, keys in `keysToFilter` are excluded instead of included. Defaults to `false`.
+ * @returns A function that filters keys on any input POJO.
+ *
+ * @example
+ * ```typescript
+ * const pickAB = filterKeysOnPOJOFunction(['a', 'b']);
+ * pickAB({ a: 1, b: 2, c: 3 });
+ * // { a: 1, b: 2 }
+ *
+ * const omitAB = filterKeysOnPOJOFunction(['a', 'b'], true);
+ * omitAB({ a: 1, b: 2, c: 3 });
+ * // { c: 3 }
+ * ```
  */
 export declare function filterKeysOnPOJOFunction<T extends object>(keysToFilter: Iterable<string>, invertFilter?: boolean): FilterTuplesOnPOJOFunction<T>;
+/**
+ * Filter predicate type used with {@link Object.entries} to filter key/value pairs.
+ */
 export type FilterTuplesOnPOJOFilter<T extends object> = Parameters<ReturnType<typeof Object.entries<T>>['filter']>['0'];
 /**
- * Function that filters keys/values on a POJO using the pre-configured function.
+ * Function that returns a new object containing only the key/value pairs that pass a pre-configured filter.
+ * For `Record<string, V>` types, returns `Record<string, V>`. For other object types, returns `Partial<T>`.
  */
 export type FilterTuplesOnPOJOFunction<T extends object> = T extends Record<string, infer I> ? (input: T) => Record<string, I> : (input: T) => Partial<T>;
+/**
+ * Creates a {@link FilterTuplesOnPOJOFunction} from a raw entry filter predicate.
+ *
+ * The returned function iterates all entries of the input object, applies the predicate,
+ * and returns a new object containing only the entries that pass.
+ *
+ * @param filterTupleOnObject - Predicate applied to each `[key, value]` entry.
+ * @returns A function that filters entries on any input POJO.
+ *
+ * @example
+ * ```typescript
+ * const keepStrings = filterTuplesOnPOJOFunction(([, value]) => typeof value === 'string');
+ * keepStrings({ a: 'hello', b: 42, c: 'world' });
+ * // { a: 'hello', c: 'world' }
+ * ```
+ */
 export declare function filterTuplesOnPOJOFunction<T extends object>(filterTupleOnObject: FilterTuplesOnPOJOFilter<T>): FilterTuplesOnPOJOFunction<T>;
+/**
+ * Callback invoked for each matching key/value pair during iteration.
+ *
+ * @param tuple - The `[key, value]` pair.
+ * @param index - The index of the tuple among filtered results.
+ * @param object - The original object being iterated.
+ * @param context - An optional context value passed through from the caller.
+ */
 export type ForEachKeyValueOnPOJOTupleFunction<T extends object, C = unknown, K extends keyof T = keyof T> = (tuple: KeyValueTuple<T, K>, index: number, object: T, context: C) => void;
+/**
+ * Function that iterates filtered key/value pairs on a POJO.
+ * When context type `C` is `void`, no context argument is needed. Otherwise, a context must be provided.
+ */
 export type ForEachKeyValueOnPOJOFunction<T extends object, C = unknown> = C extends void ? ForEachKeyValueOnPOJOFunctionWithoutContext<T> : ForEachKeyValueOnPOJOFunctionWithContext<T, C>;
+/**
+ * Variant that takes only the object (no context).
+ */
 export type ForEachKeyValueOnPOJOFunctionWithoutContext<T extends object> = (object: T) => void;
+/**
+ * Variant that takes both the object and a context value.
+ */
 export type ForEachKeyValueOnPOJOFunctionWithContext<T extends object, C = unknown> = (object: T, context: C) => void;
+/**
+ * Configuration for {@link forEachKeyValueOnPOJOFunction}.
+ */
 export type ForEachKeyValueOnPOJOConfig<T extends object, C = unknown, K extends keyof T = keyof T> = {
+    /**
+     * Optional filter controlling which key/value pairs are iterated.
+     * When not provided, all key/value pairs are iterated.
+     */
     filter?: FilterKeyValueTuplesInput<T, K>;
+    /**
+     * Callback invoked for each matching key/value pair.
+     */
     forEach: ForEachKeyValueOnPOJOTupleFunction<T, C, K>;
 };
+/**
+ * Creates a reusable function that iterates over filtered key/value pairs of a POJO,
+ * invoking a callback for each matching pair.
+ *
+ * This is the low-level building block used by {@link filterFromPOJOFunction}, {@link findPOJOKeysFunction},
+ * {@link countPOJOKeysFunction}, {@link assignValuesToPOJOFunction}, and {@link valuesFromPOJOFunction}.
+ *
+ * When no filter is provided, all key/value pairs are iterated.
+ *
+ * @param config - The filter and forEach callback configuration.
+ * @returns A function that iterates matching key/value pairs on any input object.
+ *
+ * @example
+ * ```typescript
+ * const logDefined = forEachKeyValueOnPOJOFunction<Record<string, unknown>, void>({
+ *   filter: KeyValueTypleValueFilter.UNDEFINED,
+ *   forEach: ([key, value]) => console.log(key, value)
+ * });
+ * logDefined({ a: 1, b: undefined, c: 'test' });
+ * // logs: 'a' 1, 'c' 'test'
+ * ```
+ */
 export declare function forEachKeyValueOnPOJOFunction<T extends object, C = unknown, K extends keyof T = keyof T>({ forEach, filter }: ForEachKeyValueOnPOJOConfig<T, C, K>): ForEachKeyValueOnPOJOFunction<T, C>;