Package Exports

deep-entries

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (deep-entries) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

deep-entries

Comparable to: Object.entries()

A utility for returning deeply nested key-values as tuples of varying length.

exposes

deepEntries
=> ( input: Object | Array, map?: function ): Array[]
deepEntriesIterator
=> ( input: Object | Array, map?: function ): Iterator
delimitEntryBy
=> ( input: string ): function
delimitEntry
=> ( input: Array ): Array
rotateEntry
=> ( input: Array ): Array

examples

» RunKit

usage

const {
    deepEntries,
    deepEntriesIterator,
    delimitEntryBy,
    delimitEntry,
    rotateEntry
} = require('deep-entries')

A shape made up of both Objects or Arrays can be described in terms of deep entries. Only enumerable own-members will be returned and iteration will honour index and / or insertion order. The following examples will consume this input:

const input = {
    foo: 1,
    bar: {
        deep: {
            key: 2
        }
    },
    baz: [
        3,
        [4, 5],
        {
            key: 6
        }
    ]
}

deepEntries() will return nested entries as a variable-length array with the value trailing.

deepEntries(input)
// [
//     [ 'foo', 1 ],
//     [ 'bar', 'deep', 'key', 2 ],
//     [ 'baz', '0', 3 ],
//     [ 'baz', '1', '0', 4 ],
//     [ 'baz', '1', '1', 5 ],
//     [ 'baz', '2', 'key', 6 ]
// ]

deepEntries() will accept an optional map function as a second parameter.

Note that delimitEntry is equivalent to delimitEntryBy('.')

deepEntries(input, delimitEntry)
// [
//     [ 'foo', 1 ],
//     [ 'bar.deep.key', 2 ],
//     [ 'baz.0', 3 ],
//     [ 'baz.1.0', 4 ],
//     [ 'baz.1.1', 5 ],
//     [ 'baz.2.key', 6 ]
// ]

deepEntries() is a shorthand call that collects all entries from a deepEntriesIterator(), which is exposed separately to aid in performant iteration of larger structures. The rotateEntry() map function rotates the entry array by 1 (i.e. putting the value first), allowing for more convenient destructuring of an entry.

for (let [value, ...keys] of deepEntriesIterator(input, rotateEntry)) {
    console.log(keys, value)
}
// [ 'foo' ] 1
// [ 'bar', 'deep', 'key' ] 2
// [ 'baz', '0' ] 3
// [ 'baz', '1', '0' ] 4
// [ 'baz', '1', '1' ] 5
// [ 'baz', '2', 'key' ] 6

It's worth noting that objects can have assigned iterators too.

const { withIterator } = require('with-iterator')
const withDeepEntriesIterator = withIterator(function*() {
    yield* deepEntriesIterator(this, delimitEntryBy(':'))
})
withDeepEntriesIterator(input)
Array.from(input)
// [
//     [ 'foo', 1 ],
//     [ 'bar:deep:key', 2 ],
//     [ 'baz:0', 3 ],
//     [ 'baz:1:0', 4 ],
//     [ 'baz:1:1', 5 ],
//     [ 'baz:2:key', 6 ]
// ]

filtering

The map functions passed to deepEntries() and deepEntriesIterator() can effectively filter entries by not returning them - i.e. returning undefined.

const { last } = require('ramda')
deepEntries(input, entry => (last(entry) > 3 ? entry : undefined))
// [
//     [ 'baz', '1', '0', 4 ],
//     [ 'baz', '1', '1', 5 ],
//     [ 'baz', '2', 'key', 6 ]
// ]