@techforge/easy-set v1.0.0

Easy Set

Introduction

This project was created to simplify the process of manipulating data structures in JavaScript. It provides a simple API for setting nested object values, as well as a chainable mutator class for performing sequential data transformations.

Motivation

Working with nested structure containing optional fields can be a pain. It is often necessary to check for the existence of a field before setting it, and this can lead tu a lot of boilerplate code. I've often found myself wanting to write code like this:

data.x.y.z = "value";

But instead, due to the possibility of the intermediate fields being possibly null, I have to write this:

data.x ??= {};
data.x.y ??= {};
data.x.y.z = "value";    

To make life easier for myself, I created a utility function called easySet that allows you to set nested object values without having to check for the existence of intermediate fields.

Installation

To use this library in your project, install it via npm:

npm install easy-set

Features

Easy Set

To make it easy to manipulate object with potentially null field, this library provides the easySet function, which takes an object and a callback function. The callback function is passed a proxy of the object allowing for easy modification but once the callback is complete, the proxy is discarded and only the original object is available.

easySet(data, (o) => o.x.y.z = "value") // data = { x: { y: { z: "value" } } }

Easy Set Proxy

The easySetProxy function takes an object and returns a proxy of that object that will automatically initialize any fields that are accessed. This allows the easy data.x.y.z = "value" syntax to work regardless of whether the intermediate fields are set.

The original, unproxied object can be accessed via the easyOriginal property of the proxy.

A side effect of the proxy is that it becomes impossible to check for missing fields. If you attempt a check like:

if (data.x === undefined) {
  // do something
}

it will never evaluate to true, because the attempt to read x will populate it with an empty object. Because of this, it is likely you will want to stick with the easySet function.

Usage

JavaScript

import { easySet, easySetProxy } from "easy-set"

const data = {}
easySet(data, (o) => o.x.y.z = "value") // data = { x: { y: { z: "value" } } }

// or using a proxy
const data = easySetProxy({})
data.x.y.z = "value" // data = { x: { y: { z: "value" } } }

// get the original unproxied data
const originalData = data.easyOriginal

TypeScript

import { easySet, easySetProxy } from "easy-set"

// working with arbitrary data
const data = {}
easySet(data as any, (o) => o.x.y.z = "value") // data = { x: { y: { z: "value" } } }

// working with typed data
type MyType = {
  x?: {
    y?: {
      z?: string;
    }
  }
}
const myType: MyType = {}
easySet(myType, (o) => o.x.y.z = "value") // data = { x: { y: { z: "value" } } }

// this would generate a typescript error
// easySet(data, (d) => x.foo = "bar"); 

// using a proxy
const proxiedData = easySetProxy<MyType>({})
proxiedData.x.y.z = "value" // proxiedData = { x: { y: { z: "value" } } }

// get the original unproxied data
const originalData = proxiedData.easyOriginal

Immer

If you like immutability, easySet plays well with immer. If you pass an immer proxy to easySet, you can happily set any fields and immer will protect the original object from modification.

type Obj = {
  a?: { b?: { foo?: string } }
}
const original: Obj = {}
const modified = produce(original, (draft) => {
  easySet(draft, (d) => (d.a.b.foo = "bar"))
})