shake-tree

Shake the tastiest fruits from your deep object tree

Why?

This module is used by the Electron team to help internationalize our documentation. We parse all of our API docs into a structured format that looks a bit like this:

{
  name: 'BrowserWindow',
  description: 'Create and control browser windows.',
  process: {
    main: true,
    renderer: false
  },
  type: 'Class',
  instanceName: 'win',
  slug: 'browser-window',
  websiteUrl: 'http://electron.atom.io/docs/api/browser-window',
  repoUrl: 'https://github.com/electron/electron/blob/v1.4.0/docs/api/browser-window.md',
  staticMethods: ['...'],
  instanceMethods: ['...'],
  instanceProperties: ['...'],
  instanceEvents: ['...']
}

Some parts of this structured data (like method names and arguments) needs to stay in English, whereas other parts of it (like descriptions) need to extracted for translation into other languages.

That's where shake-tree comes in. It gives us a way to extract just the content we need from this deep object.

Installation

With npm:

npm install shake-tree --save

With Yarn:

yarn add shake-tree

Usage

const shakeTree = require('shake-tree')

// Given some arbitrarily-shaped object tree:
const input = {
  a: 'just a string',
  b: {
    description: 'this is b description'
  },
  c: {
    title: 'this is c title',
    description: 'this is c description',
    descriptionExtended: 'this is the extended description'
  }
}

// You can pull out just the values you want by key:
const output = shakeTree(input, 'description')

console.log(output)
// { b: { description: 'this is b description' },
//   c: { description: 'this is c description' } }

// You can also specify multiple keys to match:
shakeTree(input, ['description', 'title'])

Flattening

In some cases you might want the result as flat key-value object with period-delimited strings as keys. In this case, set the flat option to true:

This is useful if you want to preserve array indexes in the shaken tree.

const input = {
  a: [
    {description: 'first a'},
    {description: 'second a'}
  ]
}

const output = shakeTree(input, 'description', {flat: true})

console.log(output)
// {
//   'a.0.description': 'first a',
//   'a.1.description': 'second a'
// }

API

This module exports a single function.

`shakeTree(tree, targetKeys[, options])

• tree - Object (required)
• targetKeys - String or Array of Strings (required)
• options - Object (optional)
  • flat - Boolean (defaults to false)

Tests

npm install
npm test

Dependencies

• flat: Take a nested Javascript object and flatten it, or unflatten an object with delimited keys
• lodash.set: The lodash method _.set exported as a module.

Dev Dependencies

• chai: BDD/TDD assertion library for node.js and the browser. Test framework agnostic.
• electron-api-docs: Electron's API documentation in a structured JSON format
• mocha: simple, flexible, fun test framework
• standard: JavaScript Standard Style
• standard-markdown: Test your Markdown files for Standard JavaScript Style™

License

MIT