@1nkvi/utils 0.2.0 → 0.3.1

package/README.md

@@ -1,206 +1,36 @@
 # @1nkvi/utils
 
-Helper functions for **deeply merging** partial objects and arrays, plus a few small array/value utilities. Give it a
-list of partial objects and it composes them into one — overriding primitives, concatenating and de-duplicating arrays,
-and merging nested objects recursively — while filtering out "empty" values like `null`, `undefined` and `""`.
-
-## Quick start
-
-```ts
-import { merge } from "@1nkvi/utils"
-
-merge([{ id: 1 }, { name: "Ada" }, { name: "Ada Lovelace" }])
-// → { id: 1, name: "Ada Lovelace" }
-```
-
-Every export is available from the package root:
-
-```ts
-import {
-	merge,
-	mergeArrays,
-	filterValidPrimitiveArrayValues,
-	tuplify,
-	isPlainObject,
-	isEmptyObject,
-	isEmptyArray,
-	isInvalidNumber,
-} from "@1nkvi/utils"
-```
-
----
-
-## `merge(values, options?)`
-
-Deeply merges an array of partial objects (left to right) into a single object.
-
-```ts
-merge<TData>(values: Array<Partial<TData>>, options?: MergeOptions): Partial<TData>
+```shell
+pnpm i @1nkvi/utils
 ```
 
-The result is a _deep partial_ of `TData` — it contains every key seen across the inputs that passed validation, but no
-field is guaranteed to be present.
+A small collection of TypeScript helper functions and utility types. Its centerpiece is **deeply merging** partial
+objects and arrays — composing a list of partials into one while overriding primitives, concatenating and de-duplicating
+arrays, and merging nested objects recursively, all while filtering out "empty" values like `null`, `undefined` and
+`""`. Alongside it are a handful of array, map, randomness, and type-guard utilities, plus reusable object/path utility
+types.
 
-### How it merges
+## Changelog
 
-- **Primitives** — the last _valid_ value wins. Invalid values (see [Invalid primitives](#invalid-primitives)) are
-  skipped, so a later `""` or `null` won't clobber an earlier real value.
-- **Arrays** — concatenated, then primitive values are de-duplicated. (Objects/arrays nested inside an array are kept
-  as-is.)
-- **Objects** — merged recursively, to any depth.
-- **Mixed primitive vs. array** for the same key — the array wins by default. With `enableSingleValueArrays`, the single
-  value is wrapped into the array instead so nothing is lost.
-- Inputs are **never mutated**; a new object is returned.
+[Changelog link](./CHANGELOG.md)
 
-### Examples
-
-```ts
-// Compose keys from several partials
-merge([{ int: 1 }, { float: 2.3 }, { text: "Hello" }])
-// → { int: 1, float: 2.3, text: "Hello" }
-
-// Later valid primitives override earlier ones; "" is ignored
-merge([{ int: 1, text: "Hello" }, { int: 2, text: "" }, { int: 3 }])
-// → { int: 3, text: "Hello" }
-
-// Arrays concatenate and de-duplicate
-merge([{ nums: [1, 2, 3] }, { nums: [4] }])
-// → { nums: [1, 2, 3, 4] }
-
-// Primitive vs. array on the same key — the array wins
-merge([{ text: "first" }, { text: ["second", "third"] }])
-// → { text: ["second", "third"] }
-
-// ...unless you opt into folding the single value in
-merge([{ text: "first" }, { text: ["second", "third"] }], { enableSingleValueArrays: true })
-// → { text: ["first", "second", "third"] }
-
-// Nested objects and arrays of objects merge recursively
-merge([{ node: [{ text: "A", children: [{ text: "A.1" }] }] }, { node: [{ int: 20 }] }])
-// → { node: [{ text: "A", children: [{ text: "A.1" }] }, { int: 20 }] }
-```
-
-### `MergeOptions`
-
-| Option                           | Default | Effect                                                                                                                        |
-| -------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `enableSingleValueArrays`        | `false` | When a key mixes a single value and an array, wrap the single value into the array (instead of letting the array replace it). |
-| `disableDistinctPrimitiveFilter` | `false` | Keep duplicate primitives in merged arrays instead of de-duplicating.                                                         |
-| `nullIsValid`                    | `false` | Treat `null` as a valid value (don't filter it out).                                                                          |
-| `undefinedIsValid`               | `false` | Treat `undefined` as a valid value.                                                                                           |
-| `emptyStringIsValid`             | `false` | Treat `""` as a valid value.                                                                                                  |
-| `validators`                     | `[]`    | Extra predicates `(value) => boolean`; returning `true` marks a value **invalid** and filters it out.                         |
-
----
-
-## `mergeArrays(arrays, options?)`
-
-Flattens several arrays into one. By default, primitive values are de-duplicated and invalid primitives are dropped.
-
-```ts
-mergeArrays<TData>(arrays: TData[][], options?: MergeArraysOptions): TData[]
-```
-
-```ts
-mergeArrays([["first"], ["second"], ["third", "fourth"]])
-// → ["first", "second", "third", "fourth"]
-
-// Duplicates removed
-mergeArrays([["first"], ["first", "second"]])
-// → ["first", "second"]
-
-// Invalid primitives ("" here) are filtered out
-mergeArrays([["first"], [""]])
-// → ["first"]
-
-// Keep everything as-is
-mergeArrays([["first"], ["first", ""]], { disableDistinctPrimitiveFilter: true })
-// → ["first", "first", ""]
-```
-
-### `MergeArraysOptions`
-
-| Option                           | Default | Effect                                                               |
-| -------------------------------- | ------- | -------------------------------------------------------------------- |
-| `disableDistinctPrimitiveFilter` | `false` | Keep duplicates and invalid primitives instead of filtering.         |
-| `nullIsValid`                    | `false` | Treat `null` as valid.                                               |
-| `undefinedIsValid`               | `false` | Treat `undefined` as valid.                                          |
-| `emptyStringIsValid`             | `false` | Treat `""` as valid.                                                 |
-| `validators`                     | `[]`    | Extra `(value) => boolean` predicates; `true` marks a value invalid. |
-
----
-
-## `filterValidPrimitiveArrayValues(flatArray, options?)`
-
-Takes a single flat array, removes invalid primitives, and de-duplicates the rest.
-
-```ts
-filterValidPrimitiveArrayValues<TData>(flatArray: TData[], options?): TData[]
-```
-
-```ts
-filterValidPrimitiveArrayValues(["first", "", null, "second", "second"])
-// → ["first", "second"]
-```
-
-Accepts the same validity overrides as above (`nullIsValid`, `undefinedIsValid`, `emptyStringIsValid`).
-
----
-
-## Invalid primitives
-
-The merge/filter functions skip values considered "empty" or "meaningless". By default these are:
-
-- `null`
-- `undefined`
-- empty string `""`
-- `NaN`
-- `Infinity` and `-Infinity`
-- empty array `[]`
-- empty object `{}`
-
-Note that **`0` and `false` are valid** — they are kept. You can relax the defaults per call with `nullIsValid` /
-`undefinedIsValid` / `emptyStringIsValid`, or add your own rules via `validators`:
+## Quick start
 
 ```ts
-// Drop any string that starts with a hash
-merge([{ tag: "release" }, { tag: "#draft" }], {
-	validators: [(v) => typeof v === "string" && v.startsWith("#")],
-})
-// → { tag: "release" }
-```
-
----
-
-## `tuplify(value)`
-
-Wraps a single value into a one-element array, and leaves an existing array untouched. Handy for normalizing a `T | T[]`
-value into `T[]`.
+import { merge } from "@1nkvi/utils"
 
-```ts
-tuplify("a") // → ["a"]
-tuplify(["a", "b"]) // → ["a", "b"]
-tuplify([]) // → []
+merge([{ id: 1 }, { name: "Ada" }, { name: "Ada Lovelace" }])
+// → { id: 1, name: "Ada Lovelace" }
 ```
 
----
-
-## Small value helpers
+## Modules
 
-Type-guards and number checks used internally, exposed for convenience:
-
-| Function             | Returns `true` when…                                      |
-| -------------------- | --------------------------------------------------------- |
-| `isPlainObject(v)`   | `v` is a non-null object that isn't an array              |
-| `isEmptyObject(v)`   | `v` is a plain object with no own keys (`{}`)             |
-| `isEmptyArray(v)`    | `v` is an array of length `0` (`[]`)                      |
-| `isInvalidNumber(v)` | `v` is a number that is `NaN` or not finite (`±Infinity`) |
-
-```ts
-isPlainObject({ a: 1 }) // → true
-isPlainObject([]) // → false
-isEmptyObject({}) // → true
-isEmptyArray([]) // → true
-isInvalidNumber(NaN) // → true
-isInvalidNumber(42) // → false
-```
+| Module                     | What it does                                                                                                                                            |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [array](./docs/array.md)   | Create and normalize arrays: `tuplify` a value into an array, or build index/range arrays with `createArray` and `createRangeArray`.                    |
+| [guard](./docs/guard.md)   | Type guards and runtime checks: `isPlainObject`, `isEmptyObject`, `isEmptyArray`, `isInvalidNumber`, plus `triggerExhaustiveSwitch` for exhaustiveness. |
+| [map](./docs/map.md)       | `upsert` a `Map` entry — insert a value, or combine it with the existing one via a callback.                                                            |
+| [merge](./docs/merge.md)   | Deeply `merge` partial objects, `mergeArrays` with de-duplication, and `filterValidPrimitiveArrayValues`, all skipping "empty" values.                  |
+| [object](./docs/object.md) | `replace` a single deeply nested value by dot-notation path — immutably and type-safely, without touching its siblings.                                 |
+| [random](./docs/random.md) | Random integers: `random` within inclusive/exclusive bounds, and `randomMarginalChange` to nudge a value by fixed and percentage margins.               |
+| [types](./docs/types.md)   | Utility types for nested objects: `DeepPartial`, `DotPaths`, `LeafDotPaths`, `DotPathsWithArrayIndex`, `FlatObject`, `IsPlainObject`.                   |

package/build/artifacts/src/guard/index.d.ts

@@ -1 +1,2 @@
 export * from "./triggerExhaustiveSwitch";
+export * from "./utils";

package/build/artifacts/src/guard/index.js

@@ -1 +1,2 @@
 export * from "./triggerExhaustiveSwitch";
+export * from "./utils";

package/build/artifacts/src/index.d.ts

@@ -2,4 +2,6 @@ export * from "./array";
 export * from "./merge";
 export * from "./guard";
 export * from "./map";
+export * from "./object";
 export * from "./random";
+export * from "./types";

package/build/artifacts/src/index.js

@@ -2,4 +2,6 @@ export * from "./array";
 export * from "./merge";
 export * from "./guard";
 export * from "./map";
+export * from "./object";
 export * from "./random";
+export * from "./types";

package/build/artifacts/src/merge/index.d.ts

@@ -1,4 +1,3 @@
 export * from "./merge";
 export * from "./mergeArrays";
-export * from "./utils";
 export * from "./filterValidPrimitiveArrayValues";

package/build/artifacts/src/merge/index.js

@@ -1,4 +1,3 @@
 export * from "./merge";
 export * from "./mergeArrays";
-export * from "./utils";
 export * from "./filterValidPrimitiveArrayValues";

package/build/artifacts/src/merge/isInvalidPrimitive.js

@@ -1,4 +1,4 @@
-import { isEmptyArray, isEmptyObject, isInvalidNumber } from "../merge/utils";
+import { isEmptyArray, isEmptyObject, isInvalidNumber } from "../guard/utils";
 export function isInvalidPrimitive(value, options) {
     if (options?.validators) {
         const customValidatorResult = options.validators?.some((validator) => validator(value));

package/build/artifacts/src/merge/merge.d.ts

@@ -1,5 +1,5 @@
 import { type MergeArraysOptions } from "../merge/mergeArrays";
-import type { DeepPartial } from "../merge/DeepPartial";
+import type { DeepPartial } from "../types/DeepPartial";
 export type MergeOptions<TData> = Omit<MergeArraysOptions<TData>, "validators"> & {
     /**
      * If `true` - merging  `TValue | TValue[]` results in `TValue[]`

package/build/artifacts/src/merge/merge.js

@@ -1,5 +1,5 @@
 import { isInvalidPrimitive } from "../merge/isInvalidPrimitive";
-import { isPlainObject } from "../merge/utils";
+import { isPlainObject } from "../guard/utils";
 import { tuplify } from "../array/tuplify";
 import { mergeArrays } from "../merge/mergeArrays";
 /**

package/build/artifacts/src/merge/mergeArrays.js

@@ -1,4 +1,4 @@
-import { isPlainObject } from "../merge/utils";
+import { isPlainObject } from "../guard/utils";
 import { filterValidPrimitiveArrayValues } from "../merge/filterValidPrimitiveArrayValues";
 export function mergeArrays(arrays, options) {
     const merged = arrays.flat();

package/build/artifacts/src/object/index.d.ts

@@ -0,0 +1 @@
+export * from "./replace";

package/build/artifacts/src/object/index.js

@@ -0,0 +1 @@
+export * from "./replace";

package/build/artifacts/src/object/replace.d.ts

@@ -0,0 +1,7 @@
+import type { FlatObject } from "../../src";
+/**
+ * Replaces a single deeply nested value, addressed by a dot‑notation path, and
+ * returns a new object — the input is left untouched. The `value` type is
+ * derived from {@link FlatObject}, so it must match the type at `key`.
+ */
+export declare function replace<TObject, TKey extends keyof FlatObject<TObject> & string>(object: TObject, key: TKey, value: FlatObject<TObject>[TKey]): TObject;

package/build/artifacts/src/object/replace.js

@@ -0,0 +1,27 @@
+/**
+ * Replaces a single deeply nested value, addressed by a dot‑notation path, and
+ * returns a new object — the input is left untouched. The `value` type is
+ * derived from {@link FlatObject}, so it must match the type at `key`.
+ */
+export function replace(object, key, value) {
+    return setDeep(object, key.split("."), value);
+}
+/**
+ * Immutably sets `value` at the dot‑notation `path`, cloning every container
+ * along the way. Numeric segments create/clone arrays, everything else objects,
+ * so a single element or key can be replaced without touching its siblings.
+ */
+function setDeep(target, path, value) {
+    const [head, ...rest] = path;
+    const clone = Array.isArray(target)
+        ? [...target]
+        : { ...target };
+    if (rest.length === 0) {
+        clone[head] = value;
+        return clone;
+    }
+    const child = target?.[head];
+    const nextSegmentIsIndex = /^\d+$/.test(rest[0]);
+    clone[head] = setDeep(child ?? (nextSegmentIsIndex ? [] : {}), rest, value);
+    return clone;
+}

package/build/artifacts/src/types/DotPaths.d.ts

@@ -0,0 +1,14 @@
+import type { IsPlainObject } from "../types/IsPlainObject";
+/**
+ * Recursively builds a union of all nested property paths in dot‑notation.
+ * Only plain objects are traversed; primitives, arrays, and functions
+ * produce their key directly without recursion.
+ *
+ * @example ```tsx
+ *   { a: string, b: { c: { d: number } } }
+ *   // "a" | "b.c.d"
+ * ```
+ */
+export type DotPaths<TObject> = {
+    [TKey in keyof TObject]-?: IsPlainObject<TObject[TKey]> extends true ? (TKey & string) | `${TKey & string}.${DotPaths<TObject[TKey]>}` : TKey & string;
+}[keyof TObject];

package/build/artifacts/src/types/DotPaths.js

@@ -0,0 +1 @@
+export {};

package/build/artifacts/src/types/DotPathsWithArrayIndex.d.ts

@@ -0,0 +1,21 @@
+import type { IsPlainObject } from "../types/IsPlainObject";
+/**
+ * Recursively builds dot‑notation paths, including numeric indices for arrays.
+ *
+ * @typeParam T - The object or array type to extract paths from.
+ *
+ * @example
+ * ```tsx
+ * type Example = {
+ *   users: [
+ *     { name: string }
+ *   ];
+ * };
+ *
+ * type Paths = DotPathsWithArrayIndex<Example>;
+ * // "users" | "users.0" | "users.0.name"
+ * ```
+ */
+export type DotPathsWithArrayIndex<TObject> = TObject extends unknown[] ? TObject extends (infer TElement)[] ? TElement extends unknown[] ? `${number}` | `${number}.${DotPathsWithArrayIndex<TElement>}` : IsPlainObject<TElement> extends true ? `${number}` | `${number}.${DotPathsWithArrayIndex<TElement>}` : `${number}` : never : {
+    [TKey in keyof TObject]-?: TObject[TKey] extends unknown[] ? (TKey & string) | `${TKey & string}.${DotPathsWithArrayIndex<TObject[TKey]>}` : IsPlainObject<TObject[TKey]> extends true ? (TKey & string) | `${TKey & string}.${DotPathsWithArrayIndex<TObject[TKey]>}` : TKey & string;
+}[keyof TObject];

package/build/artifacts/src/types/DotPathsWithArrayIndex.js

@@ -0,0 +1 @@
+export {};

package/build/artifacts/src/types/FlatObject.d.ts

@@ -0,0 +1,59 @@
+import type { IsPlainObject } from "../types/IsPlainObject";
+/**
+ * Collapses a union of objects into a single intersected object so that the
+ * per‑key results below merge into one flat lookup map instead of a union.
+ */
+type UnionToIntersection<TUnion> = (TUnion extends unknown ? (arg: TUnion) => void : never) extends (arg: infer TIntersection) => void ? TIntersection : never;
+/**
+ * Produces a flattened object type where keys are dot‑notation paths and
+ * values are the corresponding values. Both intermediate paths (objects and
+ * arrays) and leaf paths are emitted, so a whole nested object/array can be
+ * addressed just as safely as a leaf. Arrays are descended using a generic
+ * numeric index (`${number}`), so element paths remain type‑safe.
+ *
+ * @typeParam T - The object type to flatten.
+ *
+ * @example
+ * ```tsx
+ * type Example = {
+ *   a: string;
+ *   b: { c: number };
+ *   items: { id: string }[];
+ * };
+ *
+ * type Flat = FlatObject<Example>;
+ * // {
+ * //   "a": string;
+ * //   "b": { c: number };
+ * //   "b.c": number;
+ * //   "items": { id: string }[];
+ * //   [k: `items.${number}`]: { id: string };
+ * //   [k: `items.${number}.id`]: string;
+ * // }
+ * ```
+ */
+export type FlatObject<T> = T extends readonly (infer TElement)[] ? IsPlainObject<TElement> extends true ? {
+    [Index in `${number}`]: TElement;
+} & {
+    [SubKey in keyof FlatObject<TElement> & string as `${number}.${SubKey}`]: FlatObject<TElement>[SubKey];
+} : TElement extends readonly unknown[] ? {
+    [Index in `${number}`]: TElement;
+} & {
+    [SubKey in keyof FlatObject<TElement> & string as `${number}.${SubKey}`]: FlatObject<TElement>[SubKey];
+} : {
+    [Index in `${number}`]: TElement;
+} : FlatObjectFromKeys<Required<T>>;
+type FlatObjectFromKeys<T> = UnionToIntersection<{
+    [Key in keyof T & string]: IsPlainObject<T[Key]> extends true ? {
+        [FlatKey in Key]: T[Key];
+    } & {
+        [SubKey in keyof FlatObject<T[Key]> & string as `${Key}.${SubKey}`]: FlatObject<T[Key]>[SubKey];
+    } : T[Key] extends readonly unknown[] ? {
+        [FlatKey in Key]: T[Key];
+    } & {
+        [SubKey in keyof FlatObject<T[Key]> & string as `${Key}.${SubKey}`]: FlatObject<T[Key]>[SubKey];
+    } : {
+        [FlatKey in Key]: T[Key];
+    };
+}[keyof T & string]>;
+export {};

package/build/artifacts/src/types/FlatObject.js

@@ -0,0 +1 @@
+export {};

package/build/artifacts/src/types/IsPlainObject.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Determines whether a type is a plain object suitable for recursive traversal.
+ *
+ * A "plain object" in this context means:
+ * - It is an object type
+ * - It is **not** an array
+ * - It is **not** a function
+ *
+ * This prevents recursion from descending into prototypes of arrays, functions,
+ * primitives, or built‑in objects, ensuring that only object literals are walked.
+ *
+ * @typeParam T - The type being checked.
+ * @returns `true` if `TObject` is a non‑array, non‑function object; otherwise `false`.
+ */
+export type IsPlainObject<TObject> = TObject extends object ? TObject extends unknown[] ? false : TObject extends (...args: unknown[]) => unknown ? false : true : false;

package/build/artifacts/src/types/IsPlainObject.js

@@ -0,0 +1 @@
+export {};

package/build/artifacts/src/types/LeafDotPaths.d.ts

@@ -0,0 +1,20 @@
+import type { IsPlainObject } from "../types/IsPlainObject";
+/**
+ * Extracts only leaf property paths (deepest keys) in dot‑notation.
+ *
+ * @typeParam T - The object type whose leaf paths should be extracted.
+ *
+ * @example
+ * ```tsx
+ * type Example = {
+ *   a: string;
+ *   b: { c: { d: number } };
+ * };
+ *
+ * type Paths = LeafDotPaths<Example>;
+ * // "a" | "b.c.d"
+ * ```
+ */
+export type LeafDotPaths<TObject> = {
+    [TKey in keyof TObject]-?: IsPlainObject<TObject[TKey]> extends true ? `${TKey & string}.${LeafDotPaths<TObject[TKey]>}` : TKey & string;
+}[keyof TObject];

package/build/artifacts/src/types/LeafDotPaths.js

@@ -0,0 +1 @@
+export {};

package/build/artifacts/src/types/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./DeepPartial";
+export * from "./DotPaths";
+export * from "./DotPathsWithArrayIndex";
+export * from "./FlatObject";
+export * from "./IsPlainObject";
+export * from "./LeafDotPaths";

package/build/artifacts/src/types/index.js

@@ -0,0 +1,6 @@
+export * from "./DeepPartial";
+export * from "./DotPaths";
+export * from "./DotPathsWithArrayIndex";
+export * from "./FlatObject";
+export * from "./IsPlainObject";
+export * from "./LeafDotPaths";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1nkvi/utils",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Helper functions",
   "keywords": [
     "merge"