vino v0.0.1

vino

Experimental component for efficient reactive programming in ~150 LOC. Inspired by React. Browser and server support.

Motivation

The genius behind React was not the virtual DOM, but the Component lifecycle. The idea that every time you make a change to the state, you run render() from that Component down.

This pattern forces you to have all the state you need to ready when the render() function is called. That restraint makes it much easier to keep all your updates located in one place.

Vino is a simplified version of this Component lifecycle that is not tied to the DOM, Views, or anything else really, meaning that you can use it as a base for models or even data structures.

Vino is good for efficiently managing changes over time, while making it easy to keep your state under control.

I would use React when...

• I'm writing an application from scratch and I want the structure in place for other engineers
• I want to leverage the community for React Components

I would use Vino when...

• I need something small, but want the some of React's good ideas and constraints
• I want to use React's ideas outside the context of views
• I'm plugging a component into an existing application
• I'm using D3, since D3's "enter-exit" pattern greatly reduces the need for React's virtual DOM, but leaves you in the dark for managing state.

Constraints

From the outset, you'll notice there are some constraints on how you do things. Most obviously:

• No getters: In the same way that you cannot extract values out of React components, you cannot get values out of Vino. Everything should be done from inside the update functions.

• No return values: update functions do not have return values. While this may seem "impure", it allows seamless support of both synchronous and asynchronous functions. It also ensures that everything is present from the parent and sibling components do not depend on each other.

API

vino = Vino(schema)

Create a Vino instance with a schema. This schema is enforced on both the properties passed in as well as the computed properties

var vino = Vino({
  template: String,
  view: Reactive,
  height: Number,
  width: Number,
  area: Number,
  x: Number,
  y: Number
})

vino(updates, [fn])

Update the state of the vino.

Examples:

• vino({ x: 10, y: 20 })
• vino({ width: 25, height: 100 })

vino(function update(state, [fn]) { ... }, [ mutation_keys ])

Add an update handler. This function will only be run if the state the update function uses has changes, making these update functions cheap and rendering efficient.

Like React, you can expect all state needed to update available in the state object, but unlike React, you have can multiple "render" functions that handle different types of changes.

For example, here's one way you could handle resize events:

vino(function resize(state) {
  var height = state.height
  var width = state.width
  var view = state.view

  view.set({
    height: height,
    width: width
  })
})

Note that resize will only be run if the height, width, or view state changes. This allows you to efficiently update only what actually needs updating.

Let's add another function:

vino(function move(state) {
  var view = state.view
  var x = state.x
  var y = state.y

  view.set({
    x: x,
    y: y
  })
})

vino.defaults(props)

Sets default properties on the instance. These will be set if they are not provided initially. Note that defaults is only called once, but can be overwritten over time.

vino.defaults({
  height: 400,
  width: 1000
})

vino.initial(prop, function(state, [fn]) { ... })

Specifies the initial properties. This is only called once and after the defaults are set. Each function in here will be called exactly once regardless of whether or not the state is used.

vino.initial('view', function(state) {
  var template = state.template
  return reactive(template)
})

vino.compute(prop, function(state, [fn]) { ... }, [ mutation_keys ])

Computes properties based on the state. Unlike initial, these are called whenever the state changes. Like the update handlers, computed values will only be re-computed if the state used within the function has changed.

vino.compute('area', function(state) {
  return state.height * state.width;
})

area will only be computed if the height or the width change.

You can also use compute to update existing properties:

vino.compute('width', function(state) {
  return Number(state.width);
})

vino(null, [fn])

Signal to destroy the component, calling vino.destroy(fn).

vino.destroy(function(state, [fn]) { ... })

Destroys the instance. Useful for cleaning up timers, unbinding event listeners, etc.

License

(The MIT License)

Copyright (c) 2015 Matthew Mueller <mattmuelle@gmail.com>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.