NPM Package

A small, immutable object utility kit for TypeScript and modern ESM projects.

Requirements

• Node.js 18 or newer
• TypeScript projects should use module: "NodeNext" or an equivalent ESM setup.

Install

use npm to install

Development

npm install
npm run dev
npm test
npm run typecheck
npm run build

npm run dev executes examples/demo.ts directly with tsx.

API

All functions return new values where a transformation is required. Inputs are not mutated.

deepClone(value)

Clones arrays, plain objects, Date, RegExp, Map, and Set. Circular references are preserved. Functions and unsupported host objects remain references. Property descriptors and prototypes are retained for ordinary objects.

deepMerge(left, right)

Recursively merges plain objects. The right-hand value wins for arrays, dates, maps, sets, and primitives. Neither input is changed.

getPath(value, path, fallback?)

Reads a dotted path (user.profile.name) or a path array (['user', 'profile', 'name']). Missing paths and undefined values return fallback.

setPath(source, path, value)

Creates a new object or array path and sets the value. Numeric path segments create arrays. An empty path returns the supplied value.

omitPaths(source, paths)

Copies the source and removes each listed path. Array indexes are removed with splice, so later indexes shift.

pickPaths(source, paths)

Builds a new object from existing paths. Missing paths are ignored. Shared prefixes are combined.

objectDiff(left, right)

Returns the first difference in deterministic key order as { path, left, right }, or null when values are deeply equal. Array length differences are reported at the length path.

stableStringify(value)

Returns JSON with sorted object keys, making equivalent key orderings stable. Dates, maps, sets, bigint values, and cycles receive deterministic representations. It follows JSON behavior for unsupported values.

objectSchema(value, schema)

Validates a plain object. A schema is a nested object whose leaves are predicates. It returns { valid, errors } and never throws for invalid input. Predicates receive unknown values.

const result = objectSchema(input, {
	name: (value) => typeof value === 'string',
	profile: { age: (value) => typeof value === 'number' },
})

objectKit

A single object containing all utilities for consumers who prefer one import.

Design notes

The API intentionally has few options. Dotted paths use . as the separator, empty path segments are ignored, arrays are replaced during merge, and schema validation collects all errors instead of stopping at the first one.