-
+## Table of Content
+- [Features](#features)
+- [Example](#example)
+- [Philosophy](#philosophy)
+- [Optimizations](#optimizations)
+- [FAQ](#faq)
+- [API](#api)
+- [Installation](#installation)
+- [See Also](#see-also)
+- [Support](#support)
## Features
-- __minimal size:__ weighing `5kb`, `choo` is a tiny little framework
-- __single state:__ immutable single state helps reason about changes
-- __small api:__ with only 6 methods, there's not a lot to learn
+- __minimal size:__ weighing `4kb`, `choo` is a tiny little framework
+- __event based:__ our performant event system makes writing apps easy
+- __small api:__ with only 6 methods there's not much to learn
- __minimal tooling:__ built for the cutting edge `browserify` compiler
-- __transparent side effects:__ using `effects` and `subscriptions` brings
- clarity to IO
-- __omakase:__ composed out of a balanced selection of open source packages
- __isomorphic:__ renders seamlessly in both Node and browsers
- __very cute:__ choo choo!
-## Demos
-- :truck: [Input example](http://requirebin.com/?gist=229bceda0334cf30e3044d5f5c600960)
- ([repo](examples/title/))
-- :water_buffalo: [HTTP effects example](https://fork-fang.hyperdev.space/)
- ([repo](https://hyperdev.com/#!/project/fork-fang))
-- :mailbox: [Mailbox routing](examples/mailbox/)
-- :ok_hand: [TodoMVC](http://shuheikagawa.com/todomvc-choo/)
- ([repo](https://github.com/shuhei/todomvc-choo))
-- :fire: [Choo-firebase](https://github.com/fyrkant/choo-firebase)
-- :seedling: [Grow](https://grow.static.land/)
- ([repo](https://github.com/sethvincent/grow))
-- :newspaper: [Hacker News Reader](https://hackernews-choo.surge.sh/) ([repo](https://github.com/kvnneff/hackernews-choo))
-- :earth_africa: [Thing Translator](https://oxism.com/thing-translator/) ([repo](https://github.com/dmotz/thing-translator))
-
-_note: If you've built something cool using `choo` or are using it in
-production, we'd love to hear from you!_
-
## Example
-Let's create an input box that changes the content of a textbox in real time.
-[Click here to see the app running](http://requirebin.com/?gist=229bceda0334cf30e3044d5f5c600960).
```js
-var html = require('choo/html')
-var choo = require('choo')
+var html = require('./html')
+var choo = require('./')
+
var app = choo()
+app.use(logger)
+app.use(countStore)
+app.route('/', mainView)
+app.mount('body')
-app.model({
- state: { title: 'Not quite set yet' },
- reducers: {
- update: function (state, data) {
- return { title: data }
- }
- }
-})
-
-function mainView (state, prev, send) {
+function mainView (state, emit) {
return html`
-
-
Title: ${state.title}
-
-
+
+
count is ${state.count}
+
+
`
- function update (e) {
- send('update', e.target.value)
+ function onclick () {
+ emit('increment', 1)
}
}
-app.router(['/', mainView])
+function logger (state, emitter) {
+ emitter.on('*', function (messageName, data) {
+ console.log('event', messageName, data)
+ })
+}
-var tree = app.start()
-document.body.appendChild(tree)
-```
-
-To run it, save it as `client.js` and run with [bankai][bankai]. `bankai` is
-convenient but any [browserify][browserify] based tool should do:
-```sh
-# run and reload on port 8080
-$ bankai client.js -p 8080 --open
-
-# compile to static files in `./dist/`
-$ bankai build index.js dist/
-
-# deploy to github pages using `tschaub/gh-pages`
-$ gh-pages -d dist/
+function countStore (state, emitter) {
+ state.count = 0
+ emitter.on('increment', function (count) {
+ state.count += count
+ emitter.emit('render')
+ })
+}
```
+Want to see more examples? Check out the [Choo handbook][handbook].
## Philosophy
We believe programming should be fun and light, not stern and stressful. It's
@@ -193,395 +163,42 @@ is laid out. And once an application is built, we want it to be small,
performant and easy to reason about. All of which makes for easy to debug code,
better results and super smiley faces.
-## Concepts
-`choo` cleanly structures internal data flow, so that all pieces of logic can
-be combined into a nice, cohesive machine. Roughly speaking there are two parts
-to `choo`: the views and the models. Models take care of state and logic, and
-views are responsible for displaying the interface and responding to user
-interactions.
+## Optimizations
+Choo is reasonably fast out of the box. But sometimes you might hit a scenario
+where a particular part of the UI slows down the application, and you want to
+speed it up. Here are some optimizations that are possible.
-All of `choo`'s state is contained in a single object and whenever it changes
-the views receive a new version of the state which they can use to safely
-render a complete new representation of the DOM. The DOM is efficiently updated
-using DOM diffing/patching.
+### Reordering lists
+To be implemented. (See [yoshuawuyts/nanomorph#8](https://github.com/yoshuawuyts/nanomorph/issues/8))
-The logic in choo exist in three different kinds of actions, each with their
-own role: `effects`, `subscriptions` and `reducers`.
-
-- __Effects__ makes an asynchronous operation and calls another action when
- it's done.
-
-- __Subscriptions__ (called once when the DOM loads) listens for external input
- like keyboard or WebSocket events and then calls another action.
-
-- __Reducers__ receives the current state and returns an updated version of the
- state which is then sent to the views.
-
-```txt
- ┌─────────────────┐
- │ Subscriptions ─┤ User ───┐
- └─ Effects ◀─────┤ ▼
- ┌─ Reducers ◀─────┴─────────── DOM ◀┐
- │ │
- └▶ Router ─────State ───▶ Views ────┘
-```
-
-### Models
-`models` are objects that contain initial `state`, `subscriptions`, `effects`
-and `reducers`. They're generally grouped around a theme (or domain, if you
-like). To provide some sturdiness to your `models`, they can either be
-namespaced or not. Namespacing means that only state within the model can be
-accessed. Models can still trigger actions on other models, though it's
-recommended to keep that to a minimum.
-
-So say we have a `todos` namespace, an `add` reducer and a `todos` model.
-Outside the model they're called by `send('todos:add')` and
-`state.todos.items`. Inside the namespaced model they're called by
-`send('todos:add')` and `state.items`. An example namespaced model:
-```js
-var app = choo()
-app.model({
- namespace: 'todos',
- state: { items: [] },
- reducers: {
- add: function (state, data) {
- return { items: state.items.concat(data.payload) }
- }
- }
-})
-```
-
-In most cases using namespaces is beneficial, as having clear boundaries makes
-it easier to follow logic. But sometimes you need to call `actions` that
-operate over multiple domains (such as a "logout" `action`), or have a
-`subscription` that might trigger multiple `reducers` (such as a `websocket`
-that calls a different `action` based on the incoming data).
-
-In these cases you probably want to have a `model` that doesn't use namespaces,
-and has access to the full application state. Try and keep the logic in these
-`models` to a minimum, and declare as few `reducers` as possible. That way the
-bulk of your logic will be safely shielded, with only a few points touching every
-part of your application.
-
-### Effects
-`effects` are similar to `reducers` except instead of modifying the state they
-cause side `effects` by interacting servers, databases, DOM APIs, etc. Often
-they'll call a reducer when they're done to update the state. For instance, you
-may have an effect called getUsers that fetches a list of users from a server
-API using AJAX. Assuming the AJAX request completes successfully, the effect
-can pass off the list of users to a reducer called receiveUsers which simply
-updates the state with that list, separating the concerns of interacting with
-an API from updating the application's state.
-
-This is an example `effect` that is called once when the application loads and
-calls the `'todos:add'` `reducer` when it receives data from the server:
+### Caching DOM elements
+Sometimes we want to tell the algorithm to not evaluate certain nodes (and its
+children). This can be because we're sure they haven't changed, or perhaps
+because another piece of code is managing that part of the DOM tree. To achieve
+this `nanomorph` evaluates the `.isSameNode()` method on nodes to determine if
+they should be updated or not.
```js
-var choo = require('choo')
-var http = require('xhr')
-var app = choo()
+var el = html`
node
`
-app.model({
- namespace: 'todos',
- state: { values: [] },
- reducers: {
- add: function (state, data) {
- return { todos: data }
- }
- },
- effects: {
- addAndSave: function (state, data, send, done) {
- var opts = { body: data.payload, json: true }
- http.post('/todo', opts, function (err, res, body) {
- if (err) return done(err)
- data.payload.id = body.id
- send('todos:add', data, function (err, value) {
- if (err) return done(err)
- done(null, value)
- })
- })
- }
- },
- subscriptions: {
- 'called-once-when-the-app-loads': function (send, done) {
- send('todos:addAndSave', done)
- }
- }
-})
-```
-
-### Subscriptions
-Subscriptions are a way of receiving data from a source. For example when
-listening for events from a server using `SSE` or `Websockets` for a
-chat app, or when catching keyboard input for a videogame.
-
-An example subscription that logs `"dog?"` every second:
-```js
-var choo = require('choo')
-
-var app = choo()
-app.model({
- namespace: 'app',
- effects: {
- print: function (state, data) {
- console.log(data.payload)
- }
- },
- subscriptions: {
- callDog: function (send, done) {
- setInterval(function () {
- var data = { payload: 'dog?', myOtherValue: 1000 }
- send('app:print', data, function (err) {
- if (err) return done(err)
- })
- }, 1000)
- }
- }
-})
-```
-
-If a `subscription` runs into an error, it can call `done(err)` to signal the
-error to the error hook.
-
-### Router
-The `router` manages which `views` are rendered at any given time. It also
-supports rendering a default `view` if no routes match.
-
-```js
-var app = choo()
-app.router({ default: '/404' }, [
- [ '/', require('./views/empty') ],
- [ '/404', require('./views/error') ],
- [ '/:mailbox', require('./views/mailbox'), [
- [ '/:message', require('./views/email') ]
- ]]
-])
-```
-
-Routes on the `router` are passed in as a nested array. This means that the
-entry point of the application also becomes a site map, making it easier to
-figure out how views relate to each other.
-
-Under the hood `choo` uses [sheet-router]. Internally the
-currently rendered route is kept in `state.location`. To access the route
-`:params` you can use `state.location.params`. If you want to modify
-the location programmatically the `reducer` for the location can be called
-using `send('location:set', href)`. This will not work
-from within namespaced `models`, and usage should preferably be kept to a
-minimum. Changing views all over the place tends to lead to messiness.
-
-### Views
-Views are pure functions that return a DOM tree for the router to render.
-They’re passed the current state, and any time the state changes they’re run
-again with the new state.
-
-Views are also passed the `send` function, which they can use to dispatch
-actions that can update the state. For example, the DOM tree can have an
-`onclick` handler that dispatches an `add` action.
-
-```js
-function view (state, prev, send) {
- return html`
-
-
Total todos: ${state.todos.length}
-
-
- `
-
- function addTodo (e) {
- send('add', { title: 'demo' })
- }
+// tell nanomorph to not compare the DOM tree if they're both divs
+el.isSameNode = function (target) {
+ return (target && target.nodeName && target.nodeName === 'DIV')
}
```
-In this example, when the `Add` button is clicked, the view will dispatch an
-`add` action that the model’s `add` reducer will receive. [As seen
-above](#models), the reducer will add an item to the state’s `todos` array. The
-state change will cause this view to be run again with the new state, and the
-resulting DOM tree will be used to [efficiently patch the
-DOM](#does-choo-use-a-virtual-dom).
+### Pruning dependencies
+We use the `require('assert')` module from Node core to provide helpful error
+messages in development. In production you probably want to strip this using
+[unassertify][unassertify].
-### Plugins
-Sometimes it's necessary to change the way `choo` itself works. For example to
-report whenever an action is triggered, handle errors globally or perist state
-somewhere. This is done through something called `plugins`. Plugins are objects
-that contain `hook` and `wrap` functions and are passed to `app.use()`:
+To convert inlined HTML to valid DOM nodes we use `require('bel')`. This has
+overhead during runtime, so for production environments we should unwrap this
+using [yo-yoify][yo-yoify].
-```js
-var log = require('choo-log')
-var choo = require('choo')
-var app = choo()
-
-app.use(log())
-
-var tree = app.start()
-document.body.appendChild(tree)
-```
-
-Generally people using `choo` shouldn't be too worried about the specifics of
-`plugins`, as the internal API is (unfortunately by necessity) quite complex.
-After all they're the most powerful way to modify a `choo` application.
-
-__:warning: Warning :warning:: plugins should only be used as a last resort.
-It creates peer dependencies which makes upgrading versions and switching
-frameworks a lot harder. Please exhaust all other options before using
-plugins.__
-
-If you want to learn more about creating your own `plugins`, and which `hooks`
-and `wrappers` are available, head on over to [app.use()](#appusehooks).
-
-## Badges
-Using `choo` in a project? Show off which version you've used using a badge:
-
-
-[](https://github.com/yoshuawuyts/choo)
-```md
-[](https://github.com/yoshuawuyts/choo)
-```
-
-## API
-This section provides documentation on how each function in `choo` works. It's
-intended to be a technical reference. If you're interested in learning choo for
-the first time, consider reading through the [handbook] or
-[concepts](#concepts) first :sparkles:
-
-### app = choo(opts)
-Initialize a new `choo` app. Takes an optional object of handlers that is
-passed to [app.use()](#appusehooks).
-
-Opts can also contain the following values:
-- __opts.history:__ default: `true`. Enable a `subscription` to the browser
- history API. e.g. updates the internal `location.href` state whenever the
- browsers "forward" and "backward" buttons are pressed.
-- __opts.href:__ default: `true`. Handle all relative `` clicks and update internal `state.location`
- accordingly.
-- __opts.hash:__ default: `false`. Enable a `subscription` to the hash change
- event, updating the internal `state.location` state whenever the URL hash
- changes (eg `localhost/#posts/123`). Enabling this option automatically
- disables `opts.history` and `opts.href`.
-
-### app.model(obj)
-Create a new model. Models modify data and perform IO. Takes the following
-arguments:
-- __namespace:__ namespace the model so that it cannot access any properties
- and handlers in other models
-- __state:__ initial values of `state` inside the model
-- __reducers:__ synchronous operations that modify state. Triggered by
- `actions`. Signature of `(state, data)`.
-- __effects:__ asynchronous operations that don't modify state directly.
- Triggered by `actions`, can call `actions`. Signature of `(state, data,
- send, done)`
-- __subscriptions:__ asynchronous read-only operations that don't modify state
- directly. Can call `actions`. Signature of `(send, done)`.
-
-#### send(actionName, data?[,callback])
-Send a new action to the models with optional data attached. Namespaced models
-can be accessed by prefixing the name with the namespace separated with a `:`,
-e.g. `namespace:name`.
-
-When sending data from inside a `model` it expects exactly three arguments: the name of the action you're calling, the data you want to send, and finally a callback to handle errors through the global `onError()` hook. So if you want to send two values, you'd have to either send an array or object containing them.
-
-#### done(err?, res?)
-When an `effect` or `subscription` is done executing, or encounters an error,
-it should call the final `done(err, res)` callback. If an `effect` was called
-by another `effect` it will call the callback of the caller. When an error
-propegates all the way to the top, the `onError` handler will be called,
-registered in `choo(handlers)`. If no callback is registered, errors will
-`throw`.
-
-### app.router(defaultRoute?, (route) => [routes])
-Creates a new router. Takes a function that exposes a single `route` function,
-and that expects a tree of `routes` to be returned. See [sheet-router] for full
-documentation. Registered views have a signature of `(state, prev, send)`,
-where `state` is the current `state`, `prev` is the last state,
-`state.location.params` is URI partials and `send()` can be called to trigger
-actions. If `defaultRoute` is passed in, that will be called if no paths match.
-If no `defaultRoute` is specified it will throw instead.
-
-### app.use(hooks)
-Register an object of hooks on the application. This is useful to extend the
-way `choo` works, adding custom behavior and listeners. Generally returning
-objects of `hooks` is done by returning them from functions (which we call
-`plugins` throughout the documentation).
-
-There are several `hooks` and `wrappers` that are picked up by `choo`:
-- __onError(err, state, createSend):__ called when an `effect` or
- `subscription` emit an error. If no handler is passed, the default handler
- will `throw` on each error.
-- __onAction(state, data, name, caller, createSend):__ called when an
- `action` is fired.
-- __onStateChange(state, data, prev, caller, createSend):__ called after a
- reducer changes the `state`.
-- __wrapSubscriptions(fn):__ wraps a `subscription` to add custom behavior
-- __wrapReducers(fn):__ wraps a `reducer` to add custom behavior
-- __wrapEffects(fn):__ wraps an `effect` to add custom behavior
-- __wrapInitialState(fn):__ mutate the complete initial `state` to add custom
- behavior - useful to mutate the state before starting up
-
-__:warning: Warning :warning:: plugins should only be used as a last resort.
-It creates peer dependencies which makes upgrading versions and switching
-frameworks a lot harder. Please exhaust all other options before using
-plugins.__
-
-`createSend()` is a special function that allows the creation of a new named
-`send()` function. The first argument should be a string which is the name, the
-second argument is a boolean `callOnError` which can be set to `true` to call
-the `onError` hook istead of a provided callback. It then returns a
-`send(actionName, data?)` function.
-
-Hooks should be used with care, as they're the most powerful interface into
-the state. For application level code it's generally recommended to delegate to
-actions inside models using the `send()` call, and only shape the actions
-inside the hooks.
-
-### html = app.toString(route, state?)
-Render the application to a string of HTML. Useful for rendering on the server.
-First argument is a path that's passed to the router. Second argument is an
-optional state object. When calling `.toString()` instead of `.start()`, all
-calls to `send()` are disabled, and `subscriptions`, `effects` and `reducers`
-aren't loaded.
-
-### tree = app.start()
-Start the application. Returns a tree of DOM nodes that can be mounted using
-`document.body.appendChild()`.
-
-### view = require('choo/html')\`html\`
-Tagged template string HTML builder. Built on top of [yo-yo], [bel], and
-[hyperx]. To register a view on the `router` it should be wrapped in a function
-with the signature of `(state, prev, send)` where `state` is the current
-`state`, `prev` is the last state, `state.location.params` is URI partials and
-`send()` can be called to trigger actions.
-
-To create listeners for events, create interpolated attributes on elements.
-```js
-var html = require('choo/html')
-html`
-
-`
-
-function log (e) {
- console.log(e)
-}
-```
-Example listeners include: `onclick`, `onsubmit`, `oninput`, `onkeydown`,
-`onkeyup`. A full list can be found [at the yo-yo
-repo](https://github.com/maxogden/yo-yo/blob/master/update-events.js). When
-creating listeners always remember to call `e.preventDefault()` and
-`e.stopPropagation()` on the event so it doesn't bubble up and do stuff like
-refreshing the full page or the like.
-
-To trigger lifecycle events on any part of a view, set the `onload=${(el) =>
-{}}` and `onunload=${(el) => {}}` attributes. These parameters are useful when
-creating self-contained widgets that take care of their own state and lifecycle
-(e.g. a maps widget) or to trigger animations. Most elements shouldn't have a
-need for these hooks though.
-
-### mount('selector', html)
-Use `choo/mount` to mount a tree of DOMNodes at a given selector. This is
-especially useful to mount a `` tag on the document body after rendering
-from the server. It makes sure all `
-
-
-
-