deep-props.get

deep-props.get

Retrieves a nested property from a data source by iterating over a supplied path. Supports Objects, Arrays, Maps, Sets, WeakMaps, and JSON strings automatically. Supports the use of a custom extraction function to handle unsupported datasets.

See the usage examples for an overview of different types of data structures.

Getting Started

The following installation, testing, and deployment instructions assume that deep-props.extract will be installed as a standalone module. For instructions on how to install and test all deep-props modules, please refer to the main README. Functionality of the module remains the same in both cases.

Prerequisites

Node.JS version 6.0.0 or above.

Installing

npm install deep-props.get

Testing

The following command will test the package for errors. It prints a large selection of examples to the console; scroll through its output if you want to learn more about the utility.

npm test --prefix /path/to/node_modules/deep-props.get

Deployment

const get = require('deep-props.get')

Usage

Note: For string paths using standard settings, '.' is considered the same as '[' and ']'. See Options for instructions for customizing this behavior.

Nested Object Extraction

const nest = { foo: { bar: { baz: 'qux' } } }

// Both return 'qux'
get(nest, 'foo.bar.baz')
get(nest, [ 'foo', 'bar', 'baz' ])

Nested Array Extraction

const nest = [ [ [ 'foo' ] ] ]

// Both return 'foo'
get(nest, '0.0.0')
get(nest, [ '0', '0', '0' ])

Nested Map Extraction

const nest = new Map().set(
  'foo', new Map().set(
    'bar', new Map().set(
      'baz', new Map().set(
        'qux', 'quz'
      )
    )
  )
)

// All return 'quz'
// Note: either strict keys or insertion order may be used.
get(nest, 'foo.bar.baz.qux')
get(nest, [ 'foo', 'bar', 'baz', 'qux' ])
get(nest, 'foo.bar.baz.0')
get(nest, '0.0.0.0')
get(nest, [ 0, 0, 0, 0 ])

Nested Map Extraction with Non-Primitive Keys

const keyA = { foo: 'bar' }
const keyB = { qux: 'quz' }
const keyC = { quux: 'quuz' }

const nest = new Map().set(
  keyA, new Map().set(
    keyB, new Map().set(
      keyC, 'thud'
    )
  )
)

// All return 'thud'
// Note: this path must either be an array of Object references or descriptions of insertion order.
get(nest, [ keyA, keyB, keyC ])
get(nest, '0.0.0')
get(nest, [ 0, 0, 0 ])

Nested WeakMap Extraction

const keyA = { foo: 'bar' }
const keyB = { qux: 'quz' }
const keyC = { quux: 'quuz' }

const nest = new WeakMap().set(
  keyA, new WeakMap().set(
    keyB, new WeakMap().set(
      keyC, 'thud'
    )
  )
)

// Returns 'thud'
// Note: this path must be an array of Object references.
get(nest, [ keyA, keyB, keyC ])

Nested Set Extraction

const setA = new Set()
const setB = new Set()
const setC = new Set()

const nest = new Set().add(
  setA.add(
    setB.add(
      setC.add('foo')
    )
  )
)

// All return 'foo'
// Note: values may be accessed via insertion order or actual references.
get(nest, '0.0.0.0')
get(nest, [ 0, 0, 0, 0 ])
get(nest, [ setA, setB, setC, 0 ])

Extraction from JSON

const nest = JSON.stringify({ foo: { bar: { baz: 'qux' } } })

// returns 'qux'
get(nest, 'foo.bar.baz')

Extraction from multi-typed nest

const wmKey = { baz: 'baz' }

const nest = {
  foo: [
    new Map().set(
      'bar', new WeakMap().set(
        wmKey, JSON.stringify({
          baz: [
            {
              qux: 'quz'
            }
          ]
        })
      )
    )
  ]
}


// returns 'quz'
// Array path is required here, because wmKey needs to be a reference
get(nest, ['foo', 0, 'bar', wmKey, 'baz', 0, 'qux'])

Usage of a custom extraction function (see Options and GetCustomizer)

// Creation of a sample custom data structure which uses a 'retrieve' method for data access.
class NonNativeDataStructure {
  constructor(arr) {
    const values = [...arr]
    this.retrieve = i => values[i]
  }
}

// Addition of another data structure that, although native, requires custom extraction instructions
const testAB = new ArrayBuffer(16)
new Int16Array(testAB)[0] = 2

const nest = new NonNativeDataStructure([{ foo: { bar: testAB } }])

// returns undefined
get(nest, '0.foo.bar[0]')

// returns 2
get(nest, '0.foo.bar[0]', {
  getCustomizer: (target, key) => {
    if (target instanceof NonNativeDataStructure) {
      return target.retrieve(key)
    }
    if (target instanceof ArrayBuffer && target.byteLength === 16) {
      return new Int16Array(target)[key]
    }
  }
})

Documentation

See:

• API Docs
• Global Docs

Module: get

Retrieves a nested property from a data source by iterating over a supplied path. Supports Objects, Arrays, Maps, Sets, WeakMaps, and JSON strings automatically. Supports the use of a custom extraction function to handle unsupported datasets.

Parameters:

Name	Type	Attributes	Default	Description
host	deep-props.get~Host			Container to search within.
path	deep-props.get~Path			Path to desired property.
opt	deep-props.get~Options	<optional>	{}	Execution settings.

Source:

• deep-props.get/index.js, line 282

Returns:

Endpoint of path - the result of the search. Target is undefined if not found. If opt.gen === true, returns a generator that yields each search step.

Type

deep-props.get~Target | deep-props.get~ResultGenerator

Versioning

Versioned using SemVer. For available versions, see the Changelog.

Contribution

Please raise an issue if you find any. Pull requests are welcome!

Author

• Justin Collier - jpcx

License

This project is licensed under the MIT License - see the LICENSE file for details

Changelog

0.1.3 (2018-05-11)

Since: deep-props 0.2.5

| Changes since 0.1.2 | Release Notes | README | | --- | --- | --- |

| Source Code (zip) | Source Code (tar.gz) | | --- | --- |

Bugfixes

• docs: Updated JSDoc with new description.

<a name="0.1.2"></a>