@1nkvi/utils 0.1.3 → 0.3.0

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/array/createArray.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Creates array from `startIndex` to `length¨
+ *
+ * Useful for quickly creating skeleton placeholders
+ *
+ * @param length size of the array
+ * @param startIndex defaults to 0
+ */
+export declare function createArray(length: number, startIndex?: number): number[];

package/build/artifacts/src/array/createArray.js

@@ -0,0 +1,11 @@
+/**
+ * Creates array from `startIndex` to `length¨
+ *
+ * Useful for quickly creating skeleton placeholders
+ *
+ * @param length size of the array
+ * @param startIndex defaults to 0
+ */
+export function createArray(length, startIndex = 0) {
+    return Array.from({ length }, (_, i) => i + startIndex);
+}

package/build/artifacts/src/array/createRangeArray.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Returns array of numbers from interval `<min, max>`
+ * @param min min value (inclusive)
+ * @param max max value (inclusive)
+ * @example ```tsx
+ * createRangeArray(-2, 1) // [-2, -1, 0, 1]
+ * ```
+ */
+export declare function createRangeArray(min: number, max: number): number[];

package/build/artifacts/src/array/createRangeArray.js

@@ -0,0 +1,11 @@
+/**
+ * Returns array of numbers from interval `<min, max>`
+ * @param min min value (inclusive)
+ * @param max max value (inclusive)
+ * @example ```tsx
+ * createRangeArray(-2, 1) // [-2, -1, 0, 1]
+ * ```
+ */
+export function createRangeArray(min, max) {
+    return Array.from({ length: max - min + 1 }, (_, i) => min + i);
+}

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

@@ -0,0 +1,3 @@
+export * from "./tuplify";
+export * from "./createArray";
+export * from "./createRangeArray";

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

@@ -0,0 +1,3 @@
+export * from "./tuplify";
+export * from "./createArray";
+export * from "./createRangeArray";

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

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

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

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

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

@@ -0,0 +1,14 @@
+/**
+ * Used for checking that all values are accounted for in a switch
+ * ```typescript
+ * type Test = "a"|"b"|"c"
+ * switch(test) {
+ *   case "a": ...
+ *   case "b": ...
+ *   default: triggerExhaustiveSwitch(test, "My component name")
+ * }
+ * ```
+ * @param value value in switch
+ * @param componentName name used for debugging purposes. Usually name of the component where switch lives
+ */
+export declare function triggerExhaustiveSwitch(value: never, componentName: string): never;

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

@@ -0,0 +1,17 @@
+/**
+ * Used for checking that all values are accounted for in a switch
+ * ```typescript
+ * type Test = "a"|"b"|"c"
+ * switch(test) {
+ *   case "a": ...
+ *   case "b": ...
+ *   default: triggerExhaustiveSwitch(test, "My component name")
+ * }
+ * ```
+ * @param value value in switch
+ * @param componentName name used for debugging purposes. Usually name of the component where switch lives
+ */
+export function triggerExhaustiveSwitch(value, componentName) {
+    // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+    throw new Error(`Unhandled ${componentName} type for value [${value}]`);
+}

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

@@ -0,0 +1,4 @@
+export declare function isPlainObject(v: unknown): v is Record<string, unknown>;
+export declare function isEmptyObject(v: unknown): v is object;
+export declare function isEmptyArray(v: unknown): v is Array<unknown>;
+export declare function isInvalidNumber(v: unknown): boolean;

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

@@ -0,0 +1,14 @@
+export function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+export function isEmptyObject(v) {
+    if (!isPlainObject(v))
+        return false;
+    return Object.keys(v).length === 0;
+}
+export function isEmptyArray(v) {
+    return Array.isArray(v) && v.length === 0;
+}
+export function isInvalidNumber(v) {
+    return typeof v === "number" && (!Number.isFinite(v) || Number.isNaN(v));
+}

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

@@ -1,5 +1,7 @@
-export * from "./merge/merge";
-export * from "./merge/mergeArrays";
-export * from "./merge/utils";
-export * from "./merge/filterValidPrimitiveArrayValues";
-export * from "./tuplify";
+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

@@ -1,5 +1,7 @@
-export * from "./merge/merge";
-export * from "./merge/mergeArrays";
-export * from "./merge/utils";
-export * from "./merge/filterValidPrimitiveArrayValues";
-export * from "./tuplify";
+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/map/index.d.ts

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

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

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

package/build/artifacts/src/map/upsert.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Upserts existing map by `value`, following the `fn` behavior
+ * @param map existing map
+ * @param key key to be upserted
+ * @param value value to be upserted
+ * @param fn function used when value exists in the map
+ * @example ```tsx
+ *   const map = new Map<string, string[]>()
+ *   map.set("a", ["1", "2"])
+ *   upsert(map, "a", ["3"], (prev, value) => [...prev, ...value])
+ *   // output: ["1", "2", "3"]
+ * ```
+ * @remarks if key does not exist, sets the value
+ */
+export declare function upsert<TKey, TValue>(map: Map<TKey, TValue>, key: TKey, value: TValue, fn: (prev: TValue, value: TValue) => TValue): TValue;

package/build/artifacts/src/map/upsert.js

@@ -0,0 +1,24 @@
+/**
+ * Upserts existing map by `value`, following the `fn` behavior
+ * @param map existing map
+ * @param key key to be upserted
+ * @param value value to be upserted
+ * @param fn function used when value exists in the map
+ * @example ```tsx
+ *   const map = new Map<string, string[]>()
+ *   map.set("a", ["1", "2"])
+ *   upsert(map, "a", ["3"], (prev, value) => [...prev, ...value])
+ *   // output: ["1", "2", "3"]
+ * ```
+ * @remarks if key does not exist, sets the value
+ */
+export function upsert(map, key, value, fn) {
+    if (map.has(key)) {
+        const prev = map.get(key);
+        const next = fn(prev, value);
+        map.set(key, next);
+        return next;
+    }
+    map.set(key, value);
+    return value;
+}

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

@@ -1,3 +1,6 @@
+/**
+ * Expects json object. Walks through the children and makes all keys optional
+ */
 export type DeepPartial<T> = T extends Array<infer U> ? Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends object ? {
     [K in keyof T]?: DeepPartial<T[K]>;
 } : T;

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

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

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

@@ -0,0 +1,3 @@
+export * from "./merge";
+export * from "./mergeArrays";
+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,6 +1,6 @@
 import { isInvalidPrimitive } from "../merge/isInvalidPrimitive";
-import { isPlainObject } from "../merge/utils";
-import { tuplify } from "../tuplify";
+import { isPlainObject } from "../guard/utils";
+import { tuplify } from "../array/tuplify";
 import { mergeArrays } from "../merge/mergeArrays";
 /**
  * Deeply merges inputs into new object. Generally goes through the following steps:

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/random/index.d.ts

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

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

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

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

@@ -0,0 +1,63 @@
+export interface RandomOptions {
+    excludeMin?: true;
+    excludeMax?: true;
+}
+/**
+ * Returns random integer number between `min` and `max` based on the `options`
+ * @param min min value (inclusive by default). Must be less than `max`
+ * @param max max value (inclusive by default). Must be greater than `min`
+ * @param options further options for modifying generator behavior
+ *
+ * @example ```tsx
+ * random(1, 10)
+ * // returns single value from  inclusive interval <1, 10>
+ * ```
+ */
+export declare function random(min: number, max: number, options?: RandomOptions): number;
+export interface RandomMarginalChangeOptions {
+    /**
+     * Value added to the `min` in the random function
+     * @default 0
+     */
+    minFixed?: number;
+    /**
+     * Value added to the `max` in the random function
+     * @default 0
+     */
+    maxFixed?: number;
+    /**
+     * Percentage value (as decimal) multiplied the resulting `min` in the random function
+     * @default 1.00
+     */
+    minPercentage?: number;
+    /**
+     * Percentage value (as decimal) multiplied the resulting `max` in the random function
+     * @default 1.00
+     */
+    maxPercentage?: number;
+    /**
+     * Return this number if computed result is less than absolute minimum
+     */
+    absoluteMin?: number;
+    /**
+     * Return this number if computed result is greater than absolute maximum
+     */
+    absoluteMax?: number;
+}
+/**
+ * Takes initial value and creates marginal change based on options values.
+ *
+ * Insert percentages as decimals - 100% = 1.00; 1% = 0.01 calculated from initial value.
+ * @example
+ * ```typescript
+ *  randomMarginalChange(100, {minFixed: -10, maxFixed: 10, minPercentage: 0.9, maxPercentage: 1.1})
+ *  // results in interval  min: (100 - 10) * 0.9; max: (100 + 10) * 1.1
+ *  // where result will be <89; 121>
+ *
+ * ```
+ * @remark Returns floored random value
+ *
+ * @param value initial value to be derived
+ * @param options fixed values default to 0, percentage values defaults to 1
+ */
+export declare function randomMarginalChange(value: number, options: RandomMarginalChangeOptions): number;

package/build/artifacts/src/random/random.js

@@ -0,0 +1,57 @@
+/**
+ * Returns random integer number between `min` and `max` based on the `options`
+ * @param min min value (inclusive by default). Must be less than `max`
+ * @param max max value (inclusive by default). Must be greater than `min`
+ * @param options further options for modifying generator behavior
+ *
+ * @example ```tsx
+ * random(1, 10)
+ * // returns single value from  inclusive interval <1, 10>
+ * ```
+ */
+export function random(min, max, options) {
+    if (min === max) {
+        return Math.floor(min);
+    }
+    if (min > max || max < min) {
+        throw new Error(`Min must be greater than max. Got min: ${min}, max: ${max}`);
+    }
+    if (Math.abs(Math.floor(min) - Math.floor(max)) === 1 && options?.excludeMin && options?.excludeMax) {
+        throw new Error(`Cannot generate random non-inclusive value from interval (${min}; ${max})`);
+    }
+    if (options?.excludeMin) {
+        return Math.floor(Math.random() * (max - min)) + min + 1;
+    }
+    if (options?.excludeMax) {
+        return Math.floor(Math.random() * (max - min)) + min;
+    }
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+/**
+ * Takes initial value and creates marginal change based on options values.
+ *
+ * Insert percentages as decimals - 100% = 1.00; 1% = 0.01 calculated from initial value.
+ * @example
+ * ```typescript
+ *  randomMarginalChange(100, {minFixed: -10, maxFixed: 10, minPercentage: 0.9, maxPercentage: 1.1})
+ *  // results in interval  min: (100 - 10) * 0.9; max: (100 + 10) * 1.1
+ *  // where result will be <89; 121>
+ *
+ * ```
+ * @remark Returns floored random value
+ *
+ * @param value initial value to be derived
+ * @param options fixed values default to 0, percentage values defaults to 1
+ */
+export function randomMarginalChange(value, options) {
+    const min = (value + (options.minFixed ?? 0)) * (options.minPercentage ?? 1);
+    const max = (value + (options.maxFixed ?? 0)) * (options.maxPercentage ?? 1);
+    const computedResult = Math.round(random(min, max));
+    if (options.absoluteMin && computedResult < options.absoluteMin) {
+        return options.absoluteMin;
+    }
+    if (options.absoluteMax && computedResult > options.absoluteMax) {
+        return options.absoluteMax;
+    }
+    return computedResult;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Expects json object. Walks through the children and makes all keys optional
+ */
+export type DeepPartial<T> = T extends Array<infer U> ? Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;

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

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

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,58 @@
+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;
+} : 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.1.3",
+  "version": "0.3.0",
   "description": "Helper functions",
   "keywords": [
     "merge"