flea

flea

Flea is a <4kb JavaScript UI library based in Snabbdom and ES6 tagged template literals with Hyperx.

The API and state management is inspired by the Elm Architecture and choo.

Install

npm i flea

Usage

A basic counter app. See fiddle.

app({
    model: 0,
    update: {
        add: model => model + 1,
        sub: model => model - 1
    },
    view: (model, msg) => html`
        <div>
            <button onclick=${msg.add}>+</button>
            <h1>${model}</h1>
            <button onclick=${msg.sub} disabled=${model <= 0}>–</button>
        </div>`
})

See live examples.

API

html

Use html to compose HTML elements.

const hello = html`<h1>Hello World!</h1>`

html is a tagged template string. If you are familiar with React, this is like JSX, but without breaking JavaScript.

Flea's html function translates Hyperx into a Snabbdom/h function call.

app

The app function takes an object with any of the following properties.

model

An value or object that represents the state of your app. You don't modify the model directly, instead, dispatch actions that describe how the model will change. See view.

update

The update object exposes reducer functions. A reducer describes how the model will change for a given action and can return a new model or part of a model. If a reducer returns part of a model, it will be merged back into the current model.

Reducers have a signature (model, data), where model is the current model, and data is any data passed into the function.

You call reducers inside a view, effect or subscription.

view

The view is a function that returns HTML via the html function.

The view has a signature (model, msg), where model is the current model, and msg is an object you use to call reducers / cause effects.

msg.name(data)

or if you prefer

msg("name", data)

effects

Effects are often asynchronous and cause side effects, like writing to a database, or sending requests to servers. When they are done, they often dispatch an action.

Effects have a signature (model, msg, error), where model is the current model, msg is an object you use to call reducers / cause effects (see view), and error is a function you may call with an error if something goes wrong.

subs

Subscriptions are functions that run only once when the DOM is ready. Use a subscription to register global events, like mouse or keyboard listeners.

While reducers and effects are actions you cause, you can't call subscriptions directly.

A subscription has a signature (model, msg, error).

hooks

Hooks are functions called when certain events happen across the app. You can use hooks to implement middleware, loggers, etc.

onUpdate

Called when the model changes. Signature (lastModel, newModel, data).

onAction

Called when an action (reducer or effect) is dispatched. Signature (name, data).

onError

Called when you use the error function inside a subscription or effect. If you don't use this hook, the default behavior is to throw. Signature (err).

root

The root is the HTML element that will serve as a container for your app. If none is given, a div element is appended to the document.body.

FAQ

What about choo or yo-yo?

I like both, but I enjoyed yo-yo the best. I even wrote a tiny module to help me structure apps with it. I found using only yo-yo too limiting, and choo too frameworky.

In particular, I didn't like some of choo choices like namespaces, including a router, models as containers for state and morphdom.

See also virtual dom benchmarks.