Nutrias Punching Marmots

    deep-props.get

    0.1.6 • Public • Published

    deep-props.get

    NPM

    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:

    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

    Install

    npm i deep-props.get

    DownloadsWeekly Downloads

    8

    Version

    0.1.6

    License

    MIT

    Unpacked Size

    59.3 kB

    Total Files

    6

    Last publish

    Collaborators

    • jpcx