README
DotDotty
(of a person, action, or idea) somewhat mad or eccentric.
DotDotty provides a very simple wrapper around a provided object that allows for lazy dot-syntax access via the []
accessor.
Usage
const DotDotty = require('dot-dotty')
let myData = {a: true, b: false}
let dot = DotDotty(myData)
dot['a'] // true
dot['c'] = 'maybe' // 'maybe'
dot['d.0.first'] = 'expansion!' // 'expansion
// dot now is {a: true: b: false, c: 'maybe', d: [{first: 'expansion!'}]}
A given object can be made immutable or denied expansion by providing an additional options object.
If isExpandable is true(default), new arrays, objects, and keys are created when set access is attempted. Arrays will be created if the value at a given key is not an object or array already and the target key can evaluate to a number. If the target key cannot evaluate as a number, the value at the given key is created as an object. Arrays will attempt to remain as arrays unless a non-number is used as the key, in which case the array will be non-destructively converted to an object.
API
Table of contents
function DotDotty
DotDotty return a Proxy against the given target object that can access properties via dot-syntax.
Parameter | Type | Description |
---|---|---|
target |
Object | The target object to proxy DotDotty against. |
options |
Object | |
options.isImmutable |
Boolean? = false |
Whether or not the target object should be changeable. |
options.isExpandable |
Boolean? = true |
Whether or not new values may be placed into the object. These include new array entries and new object entries. |
options.expandOverNull |
Boolean? = false |
Whether or not null values should be treated as nonexistent for the purposes of expansion. |
options.throwErrors |
Boolean? = true |
Whether or not to throw errors when invalid access or expansion occurs. If false, invalid access or expansion will return undefined. |
options.throwTraps |
Boolean? = true |
Whether or not to throw trap errors for set and delete. If false, invalid sets or deletes will be silently ignored. |
options.preventPrototypeKeywords |
Boolean? = true |
Whether or not prototype keywords should be allowed within keys. If true, "proto", "constructor", and "prototype" will be silently truncated. If throwErrors is true, an error will be thrown. |
options.removeLeadingDots |
Boolean? = true |
Whether or not to remove leading dots from the target. The effectively cleans ".prop.a" => "prop.a". |
options.prefix |
String? = '' |
A prefix to add to the dot-notation string. |
options.suffix |
String? = '' |
A suffix to add to the dot-notation string. |
Returns: Proxy — A proxy to the target object that can use dot-notation to access or create properties.
Examples
const DotDotty = require('dot-dotty')
let myData = {a: 1, b: 2}
let dot = DotDotty(myData)
dot["a"] // returns 1
dot["c.cA"] = true // returns true
// dot now contains {a: 1, b:2, c: {cA: true}}
dot["d.0.a"] = "test" // returns "test"
// dot now contains {a: 1, b:2, c: {cA: true}, d: [{a: test}]}