Deepdash

eachDeep, filterDeep, findDeep, someDeep, omitDeep, pickDeep, keysDeep etc.. Tree traversal library written in Underscore/Lodash fashion. Standalone or as a Lodash mixin extension

Deepdash lib is used in PlanZed.org - awesome cloud mind map app created by the author of deepdash.
Plz check it, it's free and I need feedback 😉

Installation

In a browser

Load script after Lodash, then pass a lodash instance to the deepdash function:

<script src="https://cdn.jsdelivr.net/npm/lodash/lodash.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/deepdash/browser/deepdash.min.js"></script>
<script>
  deepdash(_);
  console.log(_.eachDeep); // --> new methods mixed into Lodash
</script>

If you don't use Lodash - there is a standalone version:

<script src="https://cdn.jsdelivr.net/npm/deepdash/browser/deepdash.standalone.min.js"></script>
<script>
  console.log(deepdash.eachDeep); // --> all the methods just work
</script>

Standalone Deepdash weighs more then "dry" version, because it includes some of cherry-picked Lodash methods it depends on. But it's better to use Standalone version, than include full Lodash just as dependency, if you don't need Lodash.

Using npm:

npm i --save deepdash

In Node.js:

// load Lodash if you need it
const _ = require('lodash');
//mixin all the methods into Lodash object
require('deepdash')(_);
// or cherry-pick method you only need and mix it into lodash
require('deepdash/addFilterDeep')(_);
// or cherry-pick method separately if you don't want to mutate Lodash instance
const filterDeep = require('deepdash/getFilterDeep')(_);
// If you don't need Lodash - there is standalone version
const deepdash = require('deepdash/standalone'); // full
const filterDeep = require('deepdash/filterDeep'); // or separate standalone methods

There is also deepdash as ES6 module

npm i --save deepdash-es

import lodash from 'lodash-es';
import deepdash from 'deepdash-es';
const _ = deepdash(lodash);

in the ES package there are same cherry-pick and/or standalone methods as in the main package.

import filterDeep from 'deepdash-es/filterDeep';

or

import { filterDeep } from 'deepdash-es/standalone';

or

import _ from 'lodash-es';
import getFilterDeep from 'deepdash-es/getFilterDeep';
const filterDeep = getFilterDeep(_);

or

import _ from 'lodash-es';
import addFilterDeep from 'deepdash-es/addFilterDeep';
addFilterDeep(_);// --> _.filterDeep

Demo

Example react+redux app with nested comments filtered by Deepdash.(source is here)

Methods

eachDeep (forEachDeep)

› iterate over all the children and sub-children 📚 see docs

  function displayField(val, key, parent, context) {
      if (_.isArray(parent)) {
        key = '[' + key + ']';
      }
      console.log(
        _.repeat('   ', context.depth) +
          '→ ' +
          key +
          ': ' +
          (_.isArray(val)
            ? '[' + val.length + ']'
            : _.isObject(val)
            ? '{' + (val.name || '') + '}'
            : val)
      );
    }

    console.log('\n = Iterate over tree (each child object) = \n');

    _.eachDeep(children, displayField, { childrenPath: 'children' });

    console.log('\n = Iterate over object (each field) = \n');

    _.eachDeep(children, displayField);

Try it yourself ›››

filterDeep

› deep filter object 📚 see docs

  console.log('\n = Filter tree (good children) = \n');

  console.log(
    _.filterDeep(children, 'good', { childrenPath: 'children' })
  );

  console.log('\n = Filter object (names of good children) = \n');

  console.log(
      _.filterDeep(children, (val, key, parent) => {
        if (key == 'name' && parent.good) return true;
      })
  );

Try it yourself ›››

findDeep

› find first matching deep meta-value 📚 see docs

// sorry

Try it yourself (no yet) ›››

findValueDeep

› find first matching deep value 📚 see docs

// sorry

Try it yourself (no yet) ›››

findPathDeep

› find the path of the first matching deep value 📚 see docs

// sorry

Try it yourself (no yet) ›››

mapDeep

› get array of values processed by iteratee. 📚 see docs

Try it yourself (no yet) ›››

mapValuesDeep

› get the object with same structure, but transformed values. 📚 see docs

Try it yourself ›››

mapKeysDeep

› get the object with same values, but transformed keys. 📚 see docs

Try it yourself (no yet) ›››

reduceDeep

› like reduce, but deep 📚 see docs

Try it yourself ›››

someDeep

› returns true if some matching deep value found 📚 see docs

// sorry

Try it yourself (no yet) ›››

pickDeep

› pick values by paths specified by endings or regexes 📚 see docs

  console.log('\n = Pick name and description only = \n');

  console.log(
    _.pickDeep(children, ['name', 'description'])
  );

Try it yourself ›››

omitDeep

› get object without paths specified by endings or regexes 📚 see docs

  console.log('\n = Omit paths not ending with "e" = \n');

  console.log(
    _.omitDeep(children, /[^e]$/i, { onMatch: { skipChildren: false } }),
  );

Try it yourself ›››

index

› get an object with all the paths as keys and corresponding values 📚 see docs

Try it yourself ›››

paths (keysDeep)

› get an array of paths 📚 see docs

Try it yourself ›››

condense

› condense sparse array 📚 see docs

Try it yourself ›››

condenseDeep

› condense all the nested arrays 📚 see docs

Try it yourself ›››

exists

› like a _.has but returns false for empty array slots 📚 see docs

Try it yourself ›››

pathToString

› convert an array to string path (opposite to _.toPath) 📚 see docs

Try it yourself ›››

See full docs for details.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Raz Sinay 💻 📓 🤔	Florent 🐛 📓	JoeSchr 🤔 📓	Matt Black 🤔	Lukas Siemon 🤔 📓 💻 📢 ⚠️	crapthings 🤔	Corrado Masciullo 🐛 🤔
Jed Richards 🚇	Kolja Zuelsdorf 🐛 📓 💡	Noval Agung Prayogo 💬	Nathan Tomsic 🤔	madflow 💬	Matthew Kirkley 🐛 🤔	Torma Gábor 🐛 🤔 📓
Andreas Richter 🐛 📓	James 🐛 💻 📖 📓	rxliuli 🐛 💻 📖	TeleMediaCC 🐛	Nicolas Coutin 💵 📓	barrct 🐛 📖	casamia918 🐛 💻 📖
ferreirix 🤔	John Camden 🐛	Joshua 💻 📖

This project follows the all-contributors specification. Contributions of any kind welcome!

Change Log

v5-1-0

(2020-06-07)

Features added

• mapValuesDeep - context.skipChildren added to let user override default behavior

Bugs fixed

• mapValuesDeep - method will skip children if value changed type from/to array and use given value as is (#60)

v5-0-0

(2020-03-21)

Breaking Changes

• mapDeep renamed to mapValuesDeep to conform to Lodash map/mapValues/mapKeys family of methods.
• mapDeep re-implemented to return an array of deep values processed by iteratee (same as _.map in Lodash)

Features added

• mapKeysDeep implemented - returns object with same values but keys modified by iteratee (same as _.mapKeys in Lodash)

v4-6-0

(2020-03-21) Features added

• pathToString prefixes args added to prepend result path correctly. (Used internally to optimize a bit by re-using already stringified paths)
• TypeScript definitions added, see this "discussion" for details.

v4-5-0

(2020-02-16)

Features added

• findDeep implemented - returns first meta-value {value, key, parent, context}, iteratee agree with, if none - returns undefined.
• findValueDeep implemented - returns first value, iteratee agree with, if none - returns undefined. Be carefull, some deep value may exists but also be undefined.
• findPathDeep implemented - returns first path, iteratee agree with, if none - returns undefined. Be carefull with includeRoot, object itself, passed as data source, also has path undefined.
• someDeep implemented - returns true if found some deep value, iteratee agree with, if none - return false (just shorthand wrapper for findDeep)

v4-4-0

(2019-12-16)

Features added

• message field (if exists) of error thrown by iteratee will be appended by current path, to speed up debug.

v4-3-0

(2019-12-7)

Features added

• eachDeep now supports break.(as context.break function passed into iteratee)

Bugs fixed

• filterDeep didn't use onUndefined options for parents skipped due leavesOnly mode.

v4-2-0

(2019-04-19)

Features added

• mapDeep implemented

v4-1-0

(2019-04-05)

Features added

• reduceDeep implemented

v4-0-0

(2019-04-05)

Breaking Changes

• in the browser deepdash doesn't try to patch existing global _ variable. It now exposes global deepdash function and user should pass a lodash instance to this function manually.
• source object will be passed to the iteratee/predicate as a very first value with undefined key/path/parent (see includeRoot option)
• indexate renamed to index.
• in case of completely rejected object filterDeep returns null instead of empty {}/[]
• if not an object passed as a source to filterDeep source will be returned if it passes the filter, otherwise null.
• context.treeChildrenPath renamed to childrenPath.
• isTreeChildren, isTreeNode iteratee sub-parameters deprecated (since they are always true in 'tree' mode and false in the 'object' mode)
• regexp children path support dropped to optimise tree walking
• tree sub-object option deprecated, tree.children renamed to childrenPath, tree.rootIsChildren renamed to rootIsChildren

Features added

• cherry-pick separate methods now available as standalone functions or as a lodash mixins.
• standalone version now available
• deepdash-es package created for importing as es6 module. It's just a content of es folder from main repo.
• includeRoot option added to eachDeep, index, paths (keysDeep) and filterDeep methods.
• leavesOnly implemented for tree mode. eachDeep now also has leavesOnly option.

v3-1-0

(2019-03-08) ✿❃❀

Breaking Changes

• keepUndefined option removed from the filterDeep method. Use onUndefined:{keepIfEmpty:true}, instead.
• keys argument of the omitDeep and pickDeep methods became paths

Features added

• tree option added to the filterDeep method.
• tree option added to the indexate method.
• tree option added to the paths (keysDeep) method.
• predicate option of the filterDeep method is Lodash _.iteratee.
• cloneDeep option of the filterDeep now can be set to false.
• callbackAfterIterate option added to the eachDeep method.
• onTrue onUndefined and onFalse options added to the filterDeep method. cloneDeep, keepIfEmpty, skipChildren default values can be overwritten for each condition.
• onMatched and onNotMatched options added to the omitDeep and pickDeep methods.
• custom object replies from filterDeep iteratee, with cloneDeep, keepIfEmpty, skipChildren and empty fields now are supported.

Bugs fixed

• filterDeep method continues to iterate over object's children if it passed the filter.

v2-1-0

(2019-03-02)

Features added

• tree option added to the eachDeep method. Now it's much easier to iterate over tree with known children collection field name / path

Bugs fixed

• Circular reference detector false positive for similar parent/child structure

v2-0-0

(2019-02-21)

Breaking Changes

• iteratee/predicate arguments order/structure changed to mimic native js array predicates

Features added

• checkCircular option added to the eachDeep method.
• pickDeep method implemented.

v1-9-5

(2019-02-09)

no changelog earlier, sorry