property-expr

What is property-expr?

The property-expr package is a utility for working with property paths. It allows for accessing and manipulating properties on objects using string paths. It's particularly useful for operations like getting or setting nested properties without having to manually check each level of the object structure.

What are property-expr's main functionalities?

Accessing Nested Properties

This feature allows you to access deeply nested properties within an object using a string path. It's useful for retrieving values without having to write verbose and error-prone code to navigate object structures.

"var propertyExpr = require('property-expr');\nvar obj = { some: { nested: { property: 'value' } } };\nvar value = propertyExpr.getter('some.nested.property')(obj); // 'value'"

Setting Nested Properties

This feature enables setting the value of a deeply nested property by specifying its path as a string. It simplifies the process of modifying nested structures without manually traversing them.

"var propertyExpr = require('property-expr');\nvar obj = {};\npropertyExpr.setter('some.nested.property')(obj, 'new value');\nconsole.log(obj.some.nested.property); // 'new value'"

Compiling Expressions

Compiles a string path into a function that can be used to access or evaluate the specified property path on an object. This is useful for scenarios where the property path needs to be dynamically evaluated multiple times.

"var propertyExpr = require('property-expr');\nvar expr = propertyExpr.compile('some.nested.property');\nconsole.log(expr({ some: { nested: { property: 'value' } } })); // 'value'"

Other packages similar to property-expr

lodash.get

Lodash's get function offers similar functionality for accessing nested properties safely. It is part of the larger lodash library, which provides a wide range of utilities for working with arrays, numbers, objects, strings, etc. Unlike property-expr, lodash.get is part of a larger utility library and does not focus exclusively on property expressions.

dot-prop

Dot-prop is a small library that also allows for getting and setting properties on objects using dot notation. It provides a more focused utility similar to property-expr but does not offer the same level of expression parsing and manipulation capabilities.

README

expr

Tiny property path utilities, including path parsing and metadata and deep property setters and getters

npm install property-expr

Use

Setters and getters:

let expr = require('property-expr')
let obj = {
  foo: {
    bar: ['hi', { buz: { baz: 'found me!' } }]
  }
}

let getBaz = expr.getter('foo.bar[1]["buz"].baz')
let setBaz = expr.setter('foo.bar[1]["buz"].baz')

console.log(getBaz(obj)) // => 'found me!'
setBaz(obj, 'set me!')
console.log(obj.foo.bar[1].buz.baz) // => 'set me!'

getter(expression, [ safeAccess ])

Returns a function that accepts an obj and returns the value at the supplied expression. You can create a "safe" getter, which won't error out when accessing properties that don't exist, reducing existance checks befroe property access:

expr.getter('foo.bar.baz', true)({ foo: {} }) // => undefined
//instead of val = foo.bar && foo.bar.baz

setter(expression)

Returns a function that accepts an obj and a value and sets the property pointed to by the expression to the supplied value.

expr(expression, [ safeAccess], [ paramName = 'data'])

Returns a normalized expression string pointing to a property on root object paramName.

expr.expr("foo['bar'][0].baz", true, 'obj') // => "(((obj.foo || {})['bar'] || {})[0])"

split(path) -> Array

Returns an array of each path segment.

expr.split("foo['bar'][0].baz") // [ "foo", "'bar'", "0", "baz"]

forEach(path, iterator[, thisArg])

Iterate through a path but segment, with some additional helpful metadata about the segment. The iterator function is called with: pathSegment, isBracket, isArray, idx, segments

expr.forEach('foo["bar"][1]', function(
  pathSegment,
  isBracket,
  isArray,
  idx,
  segments
) {
  // 'foo'   -> isBracket = false, isArray = false, idx = 0
  // '"bar"' -> isBracket = true,  isArray = false, idx = 1
  // '0'     -> isBracket = false, isArray = true,  idx = 2
})

normalizePath(path)

Returns an array of path segments without quotes and spaces.

expr.normalizePath('foo["bar"][ "1" ][2][ " sss " ]')
// ['foo', 'bar', '1', '2', ' sss ']

new Cache(maxSize)

Just an utility class, returns an instance of cache. When the max size is exceeded, cache clears its storage.

var cache = new Cache(2)
cache.set('a', 123) // returns 123
cache.get('a') // returns 123
cache.clear()

cache.set('a', 1)
cache.set('b', 2) // cache contains 2 values
cache.set('c', 3) // cache was cleaned automatically and contains 1 value

CSP

This pacakge used to rely on new Function to compile setters and getters into fast reusable functions. Since new Function is forbidden by folks using Content Security Policy unsafe-eval we've moved away from that approach. I believe that for most cases the perf hit is not noticable but if it is in your case please reach out.

If you really want to use the old version require property-expr/compiler instead