deep-props.get

deep-props.get

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

Any unsupported data structure may be accessed by supplying a customizer function. See this example.

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

Nested object extraction

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

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

Nested Map extraction

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

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

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(data, ['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]', {
  customizer: (target, key) => {
    if (target instanceof NonNativeDataStructure) {
      return target.retrieve(next)
    }
    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, 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~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 241

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~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