@cutticat/objects

Object utility library.

Contents

• Overview
• Installation
• Quick start
• API
• Documentation
• Requirements

Overview

The library provides checks (isPlainObject, isEmpty), object transformations (mapKeys, mapValues, mapEntries), merging (deepMerge), and deep comparison (deepEqual). Uses types from @cutticat/types.

Installation

pnpm i @cutticat/objects

Quick start

import {
  isPlainObject,
  isEmpty,
  mapKeys,
  mapValues,
  mapEntries,
  deepMerge,
  deepEqual,
  pick,
  omit,
  pickBy,
  omitBy,
  compact,
  deepCompact,
} from "@cutticat/objects"

// Checks
isPlainObject({ a: 1 })   // true
isEmpty("")                // true

// Transformations
mapKeys({ foo: 1 }, k => k.toUpperCase())  // { FOO: 1 }
mapValues({ a: 1, b: 2 }, v => (v as number) * 2)  // { a: 2, b: 4 }
deepMerge([{ a: 1, b: { x: 1 } }, { b: { y: 2 } }])  // { a: 1, b: { x: 1, y: 2 } }
deepEqual({ a: 1 }, { a: 1 })                        // true
deepEqual({ a: 1 }, { a: 2 })                        // false

// Selection and filtering
pick({ a: 1, b: 2, c: 3 }, ["a", "c"])  // { a: 1, c: 3 }
omit({ a: 1, b: 2, c: 3 }, ["b"])       // { a: 1, c: 3 }
compact({ a: 1, b: null, c: undefined })  // { a: 1 }
deepCompact({ a: { b: undefined, c: 1 } })  // { a: { c: 1 } }

API

Checks

• isPlainObject(value) — checks whether the value is a plain object (excludes Date, RegExp, arrays)
• isEmpty(value, options?) — checks emptiness (strings, arrays, objects; recursively — empty only if all elements are empty)
• IsEmptyOptions — options: ignore, count, noRecursive

Functional

• mapKeys(object, callback) — transforms keys
• mapValues(object, callback) — transforms values
• mapEntries(object, callback) — transforms key-value pairs
• deepMerge(objects, options?) — recursively merges objects from an array objects (left to right, last wins); null/undefined entries in the array are skipped
  • by default arrays in values are replaced entirely (as in v2)
  • options.arrayMergePolicy: "merge" — merge arrays by index (objects in elements — recursively; primitives — right operand wins)
  • for tuples of 2–4 objects, the result type is inferred as an intersection (T1 & T2 & …)
  • types: DeepMergeOptions, ArrayDeepMergePolicy
• deepEqual(a, b, options?) — recursively compares values; plain objects and arrays — by content, Date — by getTime(), other objects — by reference only
  • options.nullAsUndefined — null and undefined are equal
  • options.missingKeyAsUndefined — a missing key in a plain object equals an explicit undefined
  • type: DeepEqualOptions
• pick(object, keys) — selects specified keys
• omit(object, keys) — excludes specified keys
• pickBy(object, predicate) — selects pairs matching the predicate
• omitBy(object, predicate) — excludes pairs matching the predicate
• compact(object) — removes null and undefined only at the top level of the object
• deepCompact(object) — recursively removes null and undefined in plain objects; in arrays, drops null/undefined elements

Documentation

Further documentation:

• Project structure
• Scripts
• Style guide
• Contributing

Full API documentation is available in JSDoc comments. Use IDE autocomplete to browse.

Requirements

• Node.js >= 22.0.0
• pnpm >= 10.17.0
• TypeScript >= 5.9.0