deep-props.get

Retrieves a nested property from a data source. Supports Objects, Arrays, Maps, Sets, WeakMaps, WeakSets, and JSON. 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.get 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 8.7.0 or above.

Installing

npm install deep-props.get

Testing

The following command will test the package for errors. It prints a 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: path must either be an array of strict 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 strict references.
get(nest, '0.0.0.0')
get(nest, [ 0, 0, 0, 0 ])
get(nest, [ setA, setB, setC, 0 ])

Nested WeakSet Extraction

const wsA = new WeakSet()
const wsB = new WeakSet()
const wsC = new WeakSet()
const obj = { foo: 'bar' }

const nest = new WeakSet().add(
  wsA.add(
    wsB.add(
      wsC.add(obj)
    )
  )
)

// Returns { foo: 'bar' }
// Note: values may only be accessed via an array of strict references.
get(nest, [ wsA, wsB, wsC, obj ])

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 Set([
        new WeakMap().set(
          wmKey, JSON.stringify({
            baz: [
              {
                qux: 'quz'
              }
            ]
          })
        )
      ])
    )
  ]
}

const wsNest = new WeakSet().add(nest)

// returns 'quz'
// Array path containing strict references is required here
get(wsNest, [ nest, 'foo', 0, 'bar', 0, 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. Supports Objects, Arrays, Maps, Sets, WeakMaps, WeakSets, and JSON. 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