Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »

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

2

Version

0.1.6

License

MIT

Unpacked Size

79.6 kB

Total Files

6

Last publish

Collaborators

  • avatar