A light, cursor-like tree data structure
JavaScript Makefile
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
docs
src
.babelrc
.gitignore
CHANGELOG.md
CONTRIBUTING.md
LICENSE.md
Makefile
README.md
karma.conf.js
package.json

README.md

Foliage

Foliage is lightweight tree that operates on a tree of JavaScript primitives. It is inspired by many Cursors libraries/frameworks (see prior art), however it is not nearly as ambitious. It sacrifices robustness and purity for the sake of embeddability.

Circle CI


Goals

  1. Easier testing. Decouple React components from rest of app. Foliage makes it easier to "branch" off a subset of data while still having the ability to reference the root.
  2. Easy data traversal. It is simple to traverse object keys, however JavaScript objects aren't good at enumeration. Foliage provides some helpers out of the box for this.
  3. Keep it less than 1kb gzipped. Foliage isn't trying to do too much or be too smart.

Opinions

  1. Keep a naming convention similar to ES6 maps
  2. Don't do too much, but provide a platform for extension

Working with Foliage

Foliage can retrieve and set data similarly to an ES6 map

let plant = new Foliage({ berries: true })

// retrieve state
plant.get('berries') // true

// set state
plant.set('berries', false)

// remove state
plant.remove('berries')

Working with subsets of data

refine will clone an instance of Foliage and place a cursor to a point within its tree:

let plant = new Foliage({ berries: true })

plant.refine('berries').valueOf() // => true
let oak = new Foliage({
  squirrels: {
    squeakem: { weight: 2, height: 12 }
    chatters: { weight: 5, height: 8 }
  }
})

let squirrels = oak.refine('squirrels')

In this example, squirrels is a subset of oak focused on the squirrels key. Under the hood, they point to the same underlying data. This means if you set in squirrel, oak will be modified as well:

squirrels.set(['squeakem', 'weight'], 5)
oak.get(['squirrels', 'squeakem', 'weight']) // => 5

A couple of things are going on here. First, set is used to modify data. Second, both get and set accept an array of keys. When given an array, they will traverse the tree for the leaf value instead of just returning the key from the most immediate level.

Prior art

There is nothing novel about Foliage, it shamelessly mimics:


Code At Viget

Visit code.viget.com to see more projects from Viget.