object-access

Access(read, write and delete) an object by hierarchical keys.

Usage no npm install needed!

<script type="module">
  import objectAccess from 'https://cdn.skypack.dev/object-access';
</script>

README

Build Status

object-access

Access(read, write and delete) an object by hierarchical keys. And it can be used as an alternative for the null propagation operator

Synopsis

const access = require('object-access')
const obj = {
  one: {
    two: 2
  }
}

If we use a null operator like many other languages and the tc39 proposal

// Use Null Propagation Operator
obj.one?.two                  // 2

// Use object-access
access(obj, 'one.two', 2))    // 2

Usage

// Get
access(obj, 'one.two')                    // 2
access(obj, ['one', 'two'])               // 2
access(obj, ['one', 'three'])             // undefined
access(obj, ['one', 'three', 'four'])     // undefined
access(obj, ['one', 'three', 'four'], 4)  // 4

// Set
access.set(obj, 'one.two', 3)             // 3
// then obj.one.two.three is 3

access.set(obj, ['one', 'two'], 4)        // 4
// then obj.one.two.three is 4

// If the subtle object is not found, it will create one
access.set(obj, ['three', 'four'], 6)     // 6
// then obj.three.four is 6

// If we try to set a property on a none-object value, it will thrown.
access.set(obj, 'one.two.tree', 3)        // Error thrown!

// Force setting
access.set(obj, 'one.two.tree', 3, true)  // true
// obj.one.two is {three: 3}

access.delete(obj, 'one.two.four')        // obj.one.two.four   -> undefined
access.delete(obj, 'one.two.tree')        // obj.one.two        -> {}
access.delete(obj, 'one.two')             // obj.one            -> {}

access(obj, key_list [, default_value])

access.get(obj, key_list [, default_value])

Get value

  • obj Object
  • key_list Array|string see the example above
  • default_value any= if key_list not found, then returns the default_value, if default_value is not specified, undefined will be returned.

access.set(obj, key_list, value [, force])

If the property already exists and is not an object, access.set() will throw an error whose code is SET_ON_NONE_OBJECT.

If you want to force setting new values on none object value and override it, or to prevent any errors, use force=true.

Returns value

access.delete(obj, key_list) : boolean

Removes a key by deleting it if exists.

Returns true if succeeded otherwise false

access.remove(obj, key_list) DEPRECATED in 1.2.0

Upgrade from 1.x to 2.x

Method 1.x 2.x
set no return value has return value if there is no error
set never thrown thrown if you try to set property on none object
remove no return value has return value

License

MIT