deep-props.extract

    0.1.6 • Public • Published

    deep-props.extract

    NPM

    Non-recursively creates an array of deep paths and properties within an object. Optionally unpacks prototypes and non-enumerable property descriptors. Supports Objects, Arrays, Maps, and Sets.

    Endpoints may be previously discovered object references, primitives, or objects whose children are inaccessible due to settings or otherwise.

    Avoids recursion by using a task queue; very deep objects may be traversed without hitting the stack limit.

    Any unsupported data structure may be accessed by supplying a customizer function. See the global docs.

    Circular references or otherwise duplicate references to objects will be signified using a 'ref' property, rather than a value. See the return details.

    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 8.7.0 or above.

    Installing

    npm install deep-props.extract

    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.extract

    Deployment

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

    Usage

    Nested object extraction

    const data = { foo: { bar: { baz: 'qux' } } }
     
    // returns { path: [ 'foo', 'bar', 'baz' ], value: 'qux' }
    extract(data)

    Unrooting of Object Keys

    const data = new Map().set(
      { foo: 'bar' }, new Map().set(
        { baz: 'beh' }, new Map().set(
          { qux: 'quz' }, new Map().set(
            { quux: 'quuz' }, 'thud'
          )
        )
      )
    )
     
    // returns:
    // [
    //   {
    //     path: [ { foo: 'bar' }, { baz: 'beh' }, { qux: 'quz' }, { quux: 'quuz' } ],
    //     value: 'thud'
    //   },
    //   { host: { quux: 'quuz' }, path: ['quux'], value: 'quuz' },
    //   { host: { qux: 'quz' }, path: ['qux'], value: 'quz' },
    //   { host: { baz: 'beh' }, path: ['baz'], value: 'beh' },
    //   { host: { foo: 'bar' }, path: ['foo'], value: 'bar' }
    // ]
     
    extract(data)

    Extraction from complicated nests

    const data = {
      foo: [
        new Map().set(
          'bar', new Set([
            {
              baz: {
                qux: {
                  quz: [
                    'quux',
                    'quuz'
                  ]
                }
              }
            },
            {
              lorem: {
                ipsum: 'dolor'
              }
            }
          ])
        )
      ]
    }
     
    // returns:
    // [
    //   {
    //     path: [ 'foo', '0', 'bar', '0', 'baz', 'qux', 'quz', '0' ],
    //     value: 'quux' },
    //   { path: [ 'foo', '0', 'bar', '0', 'baz', 'qux', 'quz', '1' ],
    //     value: 'quuz' },
    //   { path: [ 'foo', '0', 'bar', '1', 'lorem', 'ipsum' ],
    //     value: 'dolor'
    //   }
    // ]
     
    extract(data)

    Verbose Options

    const data = { foo: { bar: 'baz' } }
    Object.freeze(data.foo)
     
    // returns:
    // [
    //   {
    //     path: ['foo'],
    //     value: { bar: 'baz' },
    //     writable: true,
    //     enumerable: true,
    //     configurable: true,
    //     parentIsFrozen: false,
    //     parentIsSealed: false,
    //     parentIsExtensible: true
    //   },
    //   {
    //     path: [ 'foo', 'bar' ],
    //     value: 'baz',
    //     writable: false,
    //     enumerable: true,
    //     configurable: false,
    //     parentIsFrozen: true,
    //     parentIsSealed: true,
    //     parentIsExtensible: false
    //   }
    // ]
     
    extract(data, { stepwise: true, descriptors: true, permissions: true })

    Documentation

    See:

    Module: extract

    Non-recursively creates an array of deep paths and properties within an object. Optionally unpacks prototypes and non-enumerable property descriptors. Supports Objects, Arrays, Maps, and Sets.

    Parameters:
    Name Type Attributes Default Description
    host deep-props.extract~Host Object to unpack.
    opt deep-props.extract~Options <optional> {} Execution settings.

    Source:

    Returns:

    Array of paths and values or references. Returns Search generator if opt.gen is true.

    Type

    Array.<deep-props.extract~PropAt> | deep-props.extract~ResultGenerator

    Options

    Execution-wide settings supplied to the module. Modifies types of data attached to results. Modifies types of children to extract.

    Type:
    • Object
    Properties:
    Name Type Attributes Default Description
    inherited boolean <optional> Whether or not to search for inherited properties. Attaches these keys behind a '__proto__' key.
    own boolean <optional> true Whether or not to search for own properties. Defaults to true.
    nonEnumerable boolean <optional> Whether or not to search for and return non-enumerable properties.
    permissions boolean <optional> Whether or not to attach Permissions to results.
    descriptors boolean <optional> Whether or not to attach property descriptors other than 'value' to results.
    stepwise boolean <optional> Whether or not to yield a PropAt object at every step down the chain.
    includeRefValues boolean <optional> Whether or not to attach a value to Props with Refs attached.
    gen boolean <optional> Whether or not to return a generator instead of executing the entire search.
    full boolean <optional> If true, replaces undefined Options with maximum search settings (All options except for propsCustomizer will be set to true). User supplied options supercede any changes here.
    propsCustomizer deep-props.extract~PropsCustomizer <optional> Function used for custom extraction of PropEntries from a Target.

    Source:

    PropAt

    Description of a given level of the chain. Transformed Prop Object with location attched.

    Type:
    • Object
    Properties:
    Name Type Attributes Description
    host deep-props.extract~Host <optional> When a non-primitive key has been encountered, a separate chain will be created with that key. Items on that chain will be labeled with a 'host' property to specify which host the path applies to. PropAt Objects lacking a 'host' property imply that the path applies to the initially supplied Host.
    path Array.<deep-props.extract~Key> Describes the steps taken from the Host in order to reach the Prop's value.
    value * <optional> Value described at the Prop's location (if any). In cases of a previously discovered reference (circular or otherwise), value will be replaced with a ref property (unless opt.showRefValues is true).
    writable boolean <optional> 'Writable' property descriptor of the value.
    enumerable boolean <optional> 'Enumerable' property descriptor of the value.
    configurable boolean <optional> 'Configurable' property descriptor of the value.
    parentIsFrozen boolean <optional> Frozen status of the parent object.
    parentIsSealed boolean <optional> Sealed status of the parent object.
    parentIsExtensible boolean <optional> Extensible status of the parent object.
    ref deep-props.extract~Ref <optional> If the value strictly equals a previously discovered Container, the path and Host (if applicable) of that Container will be provided.

    Source:

    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.extract

    DownloadsWeekly Downloads

    10

    Version

    0.1.6

    License

    MIT

    Unpacked Size

    79.6 kB

    Total Files

    6

    Last publish

    Collaborators

    • jpcx