@dereekb/util 13.36.0 → 13.37.0

package/oidc/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@dereekb/util/oidc",
-  "version": "13.36.0",
+  "version": "13.37.0",
   "peerDependencies": {
-    "@dereekb/util": "13.36.0"
+    "@dereekb/util": "13.37.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/util",
-  "version": "13.36.0",
+  "version": "13.37.0",
   "sideEffects": false,
   "exports": {
     "./test": {

package/src/lib/object/index.d.ts

@@ -1,5 +1,6 @@
 export * from './object.array.delta';
 export * from './object.array';
+export * from './object.copy';
 export * from './object.empty';
 export * from './object.equal';
 export * from './object.key';

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

@@ -0,0 +1,139 @@
+import { type Maybe } from '../value/maybe.type';
+import { type POJOKey } from './object';
+import { type FilterKeyValueTuplesInput } from './object.filter.tuple';
+/**
+ * How a {@link CopyValueDeepFunction} handles a value within an array that the filter removes.
+ *
+ * - `remove`: the value is left out of the copied array, shortening it.
+ * - `retain`: the value is copied as-is. Effectively exempts array values from filtering.
+ * - `nullify`: the value is replaced with `null`, retaining the array's length and indexes.
+ */
+export type CopyValueDeepArrayValuesMode = 'remove' | 'retain' | 'nullify';
+/**
+ * Transform applied to a value before it is filtered and copied.
+ *
+ * The transform's result is what gets recursed into, so returning an object/array from a primitive (or
+ * vice-versa) is allowed. The key is the key/index the value was read from, and is `undefined` for the
+ * root value.
+ */
+export type CopyValueDeepTransformFunction = (value: unknown, key: Maybe<POJOKey>) => unknown;
+/**
+ * Configuration for {@link copyValueDeep} and {@link copyValueDeepFunction}.
+ */
+export interface CopyValueDeepConfig {
+    /**
+     * Filter that decides which key/value pairs are retained. Applied to every object and array
+     * encountered, at every depth.
+     *
+     * Defaults to {@link KeyValueTypleValueFilter.UNDEFINED}, which removes `undefined` values.
+     */
+    readonly filter?: FilterKeyValueTuplesInput<Record<string, unknown>>;
+    /**
+     * How a filtered value within an array is handled. Defaults to `remove`.
+     */
+    readonly arrayValues?: CopyValueDeepArrayValuesMode;
+    /**
+     * Whether an object/array that the copy leaves empty is itself filtered out of its parent.
+     *
+     * Defaults to `false`, so `{ a: { b: undefined } }` copies to `{ a: {} }`. When `true` it copies to
+     * `{}` instead, since the nested object carries nothing once `b` is gone.
+     */
+    readonly filterEmptyValues?: boolean;
+    /**
+     * Transform applied to each value before it is filtered and copied.
+     */
+    readonly transform?: CopyValueDeepTransformFunction;
+}
+/**
+ * Recursively copies a value, filtering values as it goes.
+ */
+export type CopyValueDeepFunction = <T>(value: T) => T;
+/**
+ * Creates a reusable {@link CopyValueDeepFunction}.
+ *
+ * Plain objects and arrays are copied recursively. Every other value is retained by reference:
+ * primitives have nothing to copy, and a `Date`/`Map`/`Set`/class instance is a value in its own right,
+ * not a bag of keys to rebuild — copying one key-by-key would replace a `Date` with `{}`. This is what
+ * makes the function safe to use on data that carries such instances (a Firestore `Timestamp`, a
+ * `DocumentReference`) alongside plain json.
+ *
+ * The root value itself is never filtered — only the values found within an object or array are, since
+ * the filter is a decision about a key/value pair. A root `undefined` therefore copies to `undefined`.
+ *
+ * Repeated and cyclical references are tracked, so a value referenced twice is copied once and a cycle
+ * terminates rather than overflowing the stack.
+ *
+ * @param config - Filter, array handling, and transform configuration. Defaults to removing `undefined` values.
+ * @returns Recursively copies any input value.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory object
+ * @dbxUtilKind factory
+ * @dbxUtilTags object, copy, clone, deep, recursive, filter, transform, undefined, factory
+ * @dbxUtilRelated copy-value-deep, filter-from-pojo-function, copy-object
+ *
+ * @example
+ * ```ts
+ * // remove undefined values at any depth
+ * const copyFn = copyValueDeepFunction();
+ * copyFn({ a: 1, b: undefined, c: { d: undefined, e: [1, undefined] } });
+ * // { a: 1, c: { e: [1] } }
+ *
+ * // remove null and undefined values, and prune anything left empty
+ * const copyCleanFn = copyValueDeepFunction({ filter: KeyValueTypleValueFilter.NULL, filterEmptyValues: true });
+ * copyCleanFn({ a: 1, b: { c: null } });
+ * // { a: 1 }
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function copyValueDeepFunction(config?: Maybe<CopyValueDeepConfig>): CopyValueDeepFunction;
+/**
+ * Recursively copies a value, filtering values as it goes.
+ *
+ * See {@link copyValueDeepFunction} for the copy/filter semantics. Prefer the factory when copying more
+ * than one value with the same configuration.
+ *
+ * @param value - The value to copy.
+ * @param config - Filter, array handling, and transform configuration. Defaults to removing `undefined` values.
+ * @returns A recursive copy of the value.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory object
+ * @dbxUtilTags object, copy, clone, deep, recursive, filter, transform, undefined
+ * @dbxUtilRelated copy-value-deep-function, filter-from-pojo, copy-object
+ *
+ * @example
+ * ```ts
+ * copyValueDeep({ a: 1, b: { c: undefined } });
+ * // { a: 1, b: {} }
+ * ```
+ */
+export declare function copyValueDeep<T>(value: T, config?: Maybe<CopyValueDeepConfig>): T;
+/**
+ * Pre-built {@link CopyValueDeepFunction} that recursively copies a value, removing every `undefined`
+ * value at every depth.
+ *
+ * This is the deep counterpart to {@link filterOnlyUndefinedValues}, and is what a consumer that rejects
+ * `undefined` outright (Firestore, `JSON.stringify` in a strict schema) needs before a write.
+ *
+ * @example
+ * ```ts
+ * copyValueWithoutUndefinedValues({ a: 1, b: undefined, c: [{ d: undefined }] });
+ * // { a: 1, c: [{}] }
+ * ```
+ */
+export declare const copyValueWithoutUndefinedValues: CopyValueDeepFunction;
+/**
+ * Pre-built {@link CopyValueDeepFunction} that recursively copies a value, removing every `null` and
+ * `undefined` value at every depth.
+ *
+ * This is the deep counterpart to {@link filterNullAndUndefinedValues}.
+ *
+ * @example
+ * ```ts
+ * copyValueWithoutNullAndUndefinedValues({ a: 1, b: null, c: [{ d: undefined }] });
+ * // { a: 1, c: [{}] }
+ * ```
+ */
+export declare const copyValueWithoutNullAndUndefinedValues: CopyValueDeepFunction;

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

@@ -87,6 +87,23 @@ export declare function applyToMultipleFields<T extends object, X = unknown>(val
 export declare function mapToObject<T, K extends PropertyKey>(map: Map<K, T>): {
     [key: PropertyKey]: T;
 };
+/**
+ * Checks whether the value is a "plain" object, meaning an object literal or an object created with a
+ * null prototype.
+ *
+ * Arrays, `Date`, `RegExp`, `Map`, `Set`, and class instances are NOT plain objects. This is the check
+ * to use before recursing into a value's keys: a class instance's keys are an implementation detail and
+ * copying them key-by-key produces a lifeless imitation of the original (a `Date` becomes `{}`).
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is an object literal or has a null prototype.
+ *
+ * @dbxUtil
+ * @dbxUtilCategory object
+ * @dbxUtilTags object, pojo, plain, literal, type-guard, check
+ * @dbxUtilRelated object-has-no-keys, copy-value-deep
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
 /**
  * Returns a copy of the input object.
  */

package/test/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@dereekb/util/test",
-  "version": "13.36.0",
+  "version": "13.37.0",
   "peerDependencies": {
-    "@dereekb/util": "13.36.0",
+    "@dereekb/util": "13.37.0",
     "make-error": "^1.3.6"
   },
   "exports": {