Skip to content
Notation

Getting Started

Install

Section titled “Install”
Terminal window
npm i notation

Notation v3 is ESM and ships TypeScript types.

import { Notation } from 'notation';

Notation.create(source) is shorthand for new Notation(source). With no argument it starts from an empty object.

Other Runtimes

Section titled “Other Runtimes”

v3 is pure ESM with no Node-only dependencies, so it runs beyond Node.js (≥ 20):

  • Bun — bun add notation, then import exactly as above.
  • Deno — import via the npm: specifier: import { Notation } from 'npm:notation'.
  • Browser — bundle it like any ESM dependency.

The API is identical across runtimes — only the install/import line differs.

Read a Value

Section titled “Read a Value”

Reach into a nested property without manual guard chains. A default value is returned when the path doesn’t exist:

const obj = { car: { brand: 'Dodge', model: 'Charger' } };


Notation.create(obj).get('car.model');              // » "Charger"
Notation.create(obj).get('car.color', 'red');       // » "red" (not present)

Build & Modify

Section titled “Build & Modify”

Methods that change the source are chainable; read the result from .value:

const obj = { car: { brand: 'Dodge' } };


Notation.create(obj)
  .set('car.model', 'Charger')   // create nested path
  .set('car.year', 1970)
  .remove('car.brand')
  .value;
// » { car: { model: "Charger", year: 1970 } }

Filter with Globs

Section titled “Filter with Globs”

filter() is the one method that takes glob patterns — * to include, ! to exclude — and returns a new object without mutating the source:

const car = { brand: 'Ford', model: { name: 'Mustang', year: 1970 } };


Notation.create(car).filter(['*', '!model.year']).value;
// » { brand: "Ford", model: { name: "Mustang" } }

Where Next

Section titled “Where Next”