README.md

pointer-props

JavaScript object manipulation (get/set/del) using JSON Pointer (RFC6901) syntax, and optional resolution of JSON References.

Install

The usual ways:

npm install pointer-props

Example

Get or set a property, either using the JSON Pointer string or with an array:

import { get, set } from 'pointer-props'
const obj = { foo: { bar: 3 } }
get(obj, '/foo/bar') // => 3
get(obj, [ 'foo', 'bar' ]) // => 3
set(obj, '/foo/bar', 4) // => { foo: { bar: 4 } }
set(obj, [ 'foo', 'bar' ], 5) // => { foo: { bar: 5 } }

Resolve JSON Reference paths to the final non-referenced path (as an array):

import { resolve } from 'pointer-props'
const obj = {
	foo: { $ref: '#/fizz/buzz' },
	fizz: { buzz: 3 }
}
resolve('#/foo/bar') // => [ 'fizz', 'buzz' ]

Handles escaped strings, as expected:

const obj = {
	'f/o/o': {
		'b~a~r': 3
	}
}
get(obj, '/f~1o~1o/b~0a~0r') // => 3

Generate escaped strings from a list of tokens, or a list of tokens from a string:

import { toPointer, toTokens } from 'pointer-props'
toPointer([ 'a/b', 'c~d' ]) // => "/a~1b/c~0d"
toTokens('/a~1b/c~0d') // => [ "a/b", "c~d" ]

API

Under the hood, the get/set functions use the amazing dset and dlv, which should be pretty familiar.

function get(obj: any, path: string | ArrayLike<string | number>): any

Get a property using either a JSON Pointer string, or an array of already-unescaped accessor tokens.

import { get } from 'pointer-props'
const obj = { foo: { bar: 3 } }
get(obj, '/foo/bar') // => 3
get(obj, [ 'foo', 'bar' ]) // => 3

function set<T extends object, V>(obj: T, path: string | ArrayLike<string | number>, value: V): T

Set a property using either a JSON Pointer string, or an array of already-unescaped accessor tokens.

For convenience, the modified object is also returned.

import { set } from 'pointer-props'
const obj = {}
set(obj, '/foo/bar', 3)
console.log(obj.foo.bar) // => 3
set(obj, [ 'foo', 'bar' ], 4)
console.log(obj.foo.bar) // => 4

function del<T extends object>(obj: T, path: string | ArrayLike<string | number>): T

Remove a property using either a JSON Pointer string, or an array of already-unescaped accessor tokens.

For convenience, the modified object is also returned.

import { set } from 'pointer-props'
const obj = {}
set(obj, '/foo/bar', 3)
console.log(obj.foo.bar) // => 3
set(obj, [ 'foo', 'bar' ], 4)
console.log(obj.foo.bar) // => 4

function toTokens(path: string): Array<string>

Convert a JSON Pointer string to a list of unescaped accessor tokens.

import { toTokens } from 'pointer-props'
toTokens('/a~1b/c~0d') // => [ "a/b", "c~d" ]

function toPointer(list: ArrayLike<string | number>): string

Convert a list of unescaped accessor tokens into a JSON Pointer string.

import { toPointer } from 'pointer-props'
toPointer([ 'a/b', 'c~d' ]) // => "/a~1b/c~0d"

export function resolve<T extends object>(obj: T, path: string | ArrayLike<string | number>): ArrayLike<string | number>

Given a JSON Pointer string and an object potentially containing JSON References (e.g. $ref), resolve all references and return the final path.

import { resolve } from 'pointer-props'
const obj = {
	foo: { $ref: '#/bar' },
	bar: { $ref: '#/fizz' },
	fizz: { $ref: '#/buzz' },
	buzz: 3
}
resolve('#/foo') // => [ 'buzz' ]

License

Published and released under the Very Open License.

If you need a commercial license, contact me here.