@cutticat/properties

Library for working with object properties by paths.

Contents

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

Overview

The library provides functions for getting, setting, enumerating, and comparing object properties by paths (arrays of keys). Supports nested objects and arrays. Uses types from @cutticat/types.

Installation

pnpm i @cutticat/properties

Quick start

import {
  getProperty,
  setProperty,
  enumProperties,
  calculatePropertiesDiff,
  propertyPathToString,
  parsePropertyPath,
} from "@cutticat/properties"

const user = { name: "John", address: { city: "NYC" } }

// Get
getProperty(user, ["name"]) // "John"
getProperty(user, ["address", "city"]) // "NYC"

// Set
setProperty(user, ["age"], 30, { createMissing: true })
setProperty(user, ["address", "zip"], "10001", { createMissing: true })

// Enumerate paths
enumProperties(user) // [["name"], ["age"], ["address", "city"], ["address", "zip"]]
enumProperties(user, { withValues: true }) // [[["name"], "John"], [["age"], 30], ...]

// Diff between objects
calculatePropertiesDiff({ a: 1 }, { a: 2, b: 3 })
// { added: [["b"]], removed: [], changed: [["a"]], unchanged: [] }

// Paths: string ↔ array
propertyPathToString(["user", "profile", "name"]) // "user.profile.name"
parsePropertyPath("items[0].id") // ["items", 0, "id"]

API

Functions

• getProperty(object, path, throwOnMissing?) — gets a value by path; returns undefined or throws when missing
• setProperty(object, path, value, options?) — sets a value by path; mutates the object
• enumProperties(object, options?) — enumerates paths to all leaf properties; options: basePath, withValues
• calculatePropertiesDiff(oldObject, newObject) — computes the diff (added, removed, changed, unchanged)
• propertyPathToString(path) — converts a path to a string (user.profile.name, items[0])
• parsePropertyPath(path) — parses a path string into an array of keys

Types

• PropertyPath — property path (array of keys: (keyof any)[])
• Property<T, Path> — extracts the property type at a path in an object
• SetPropertyOptions — setProperty options (createMissing?, ignoreNonObjects?)
• EnumPropertiesOptions — enumProperties options (basePath?, withValues?)
• EnumPropertiesResult — enumProperties result (paths or [path, value] tuples)
• PropertiesDiff — calculatePropertiesDiff result (added, removed, changed, unchanged)

Documentation

See also:

• Project structure
• Scripts
• Style guide
• Contributing

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

Requirements

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