foliage

---

---

Foliage

Foliage is lightweight tree that operates on a tree of JavaScript primitives. It is modeled loosely on Om's Cursor and OmniscientJS's immstruct, however it is not nearly as ambitious. It compromises on robustness and purity for the benefit of build size.

Foliage makes it easier to work with data in component-oriented frameworks such as React by allowing data to be passed around in terms of references to locations in a global application state object. This means that state can be maintained in a single location, however that entire structure isn't necessary for an individual component.

Goals

1. Easier testing. Decouple React components from rest of app. Our Flux-like framework, Microcosm, keeps all state in a single app instance. It can be troublesome to pass down this context to child components that need to modify state. 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 accepts a seed:

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

Querying records

get pulls data out of a "plant."

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

plant.get('berries').valueOf() // => true

Take out that valueOf must be called to retrieve the value out of a plant. This is because get returns a branch. Now let's dig into that.

Branches

Calling get returns a branch. Technically, this is called a cursor, but let's keep with the dendrology theme.

let oak = new Foliage({
  squirrels: {
    squeakem: { weight: 2, height: 12 }
    chatters: { weight: 5, height: 8 }
  }
})

let squirrels = oak.get('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']).valueOf() // => 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:

• Sprout
• OmnicientJS
• OmnicientJS Immstruct
• Om
• Functional Zippers
• React Cursor
• Baobab