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 =
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'
Nested Array Extraction
const nest = 'foo' // Both return 'foo'
Nested Map Extraction
const nest = // All return 'quz'// Note: either strict keys or insertion order may be used.
Nested Map Extraction with Non-Primitive Keys
const keyA = foo: 'bar' const keyB = qux: 'quz' const keyC = quux: 'quuz' const nest = // All return 'thud'// Note: path must either be an array of strict references or descriptions of insertion order.
Nested WeakMap Extraction
const keyA = foo: 'bar' const keyB = qux: 'quz' const keyC = quux: 'quuz' const nest = // Returns 'thud'// Note: this path must be an array of Object references.
Nested Set Extraction
const setA = const setB = const setC = const nest = // All return 'foo'// Note: values may be accessed via insertion order or strict references.
Nested WeakSet Extraction
const wsA = const wsB = const wsC = const obj = foo: 'bar' const nest = // Returns { foo: 'bar' }// Note: values may only be accessed via an array of strict references.
Extraction from JSON
const nest = JSON // returns 'qux'
Extraction from multi-typed nest
const wmKey = baz: 'baz' const nest = foo: const wsNest = // returns 'quz'// Array path containing strict references is required here
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. { const values = ...arr this valuesi } // Addition of another data structure that, although native, requires custom extraction instructionsconst testAB = 16testAB0 = 2 const nest = foo: bar: testAB // returns undefined // returns 2
Documentation
See:
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:
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