satorijs

Satori

Satori is a minimalistic JavaScript reactive view library that uses ES6 Proxies for data binding (browser support).

Key features:

• Unobtrusive — you can keep your model intact. In contrast to non-Proxy solutions, even property additions do not need any special treatment
• Pure JavaScript DSL makes code reuse more straightforward
• Expressive — TodoMVC is only 75 SLOC (including most of the markup)
• It doesn’t dictate you anything — it’s not a framework
• Tiny — core library is ~700 SLOC, 5 KB gzipped
• Server-side rendering
• No dependencies
• Undo/redo
• Fast

These qualities also make it useful for quick prototyping — it won’t interfere with your model code, requires almost zero boilerplate and helps you create and reorganize ad hoc components very quickly.

Getting started

Install the library:

npm i satorijs

Hello, World:

import {Satori} from 'satorijs';
 
const view = new Satori();
const h = view.h;
const HelloView = name => h('div', null, ['Hello, ', name]);
view.qs('body').appendChild(HelloView('World'));

But this is just a static element. To make something reactive, first make sure that the root object of your model is wrapped in a proxy:

const user = view.proxy({name: 'Mike'});

Then just wrap the reactive part in a function:

const HelloView = user => h('div', null, ['Hello, ', h('span', null, () => user.name)]);
view.qs('body').appendChild(HelloView(user));
// The content of the <span> will be updated automatically
setTimeout(() => {user.name = 'Joe'}, 1000);

Reactivity is based primarily on registering property accesses via proxies, so the properties you want observed have to be accessed inside the wrapper function. This means you can’t just write () => name — that would be static. Also, you can’t make reactive text nodes — you must have an element. This is why we added a <span> here.

Documentation

Element factory

DOM elements are created using the element factory method:

h(tagName, modifiers, content): Element

Element content

There are multiple ways to specify the element content:

• Text:

h('div', null, 'Hello')

• One child element:

h('div', null, h('div'))

• Array of elements and/or strings:

h('div', null, [h('span'), ' ', h('span')])

The view.setElementContent() method is called under the hood and supports all of the above:

view.setElementContent(element, content)

Modifiers

Element modifiers are passed as the second argument to the element factory:

h('div', {…}, content)

Modifiers are view object methods and can also be applied to any existing DOM elements:

view.content(view.qs('.name'), () => user.name)
view.bind(view.qs('.title'), {model: post, key: 'title'})

You also can use assign() method to apply multiple modifiers at once to an existing element:

view.assign(view.qs('.clear-completed'), {
    show: () => model.completed.length,
    on: {click: () => {model.clearCompleted()}},
});

All available modifiers are listed below.

Content: content

Content passed to the element factory is handled as content modifier internally.

{content: string|Node|[string|Node] | () => string|Node|[string|Node]}

Examples:

h('div', {content: 'Text'})
h('div', {content: h('h1', null, 'Title')})
h('div', {content: [h('strong', null, 10), ' items']})
h('div', {content: () => page.text})

Visibility: show

Adds display: none style property when the value is false and removes it, when the value is true.

{show: bool | () => bool}

h('div', {show: false}, 'Text')
h('div', {show: () => items.length}, 'Text')

CSS classes: class

Presence of CSS classes is specified using booleans:

{class: string | [string] | {string: bool | () => bool, …}}

Single static class:

h('div', {class: 'active'})

Static:

h('div', {class: ['active']})
h('div', {class: {active: true}})
h('div', {class: {active: user.active}})

Reactive:

h('div', {class: {active: () => user.active}})

Attributes: attr

{attr: {string: string | () => string, …}}

h('input', {attr: {type: 'checkbox'}})

Element properties: prop

{prop: {string: any | () => any, …}}

{prop: {checked: true}}
{prop: {value: ''}}

Element data-attributes (dataset): data

{data: {string: string | () => string, …}}

Element style properties: css

{css: {string: string | () => string, …}}

h('div', {css: {'background-color': 'blue'}})

Event handlers: on

Simply calls addEventHandler() for each key.

{on: {eventType(event) {…}, …}}

h('div', {on: {click() {alert('Click!')}}})

Capturing event handlers: onCapture

For capturing handlers use onCapture modifier instead of on:

{onCapture: {eventType(event) {…}, …}}

Keyboard event handler: keydown, keyup

{keydown: {[view.Key.*]: (element, event) => …, …}}
{keyup: {[view.Key.*]: (element, event) => …, …}}

h('input', {keydown: {
    [view.Key.ENTER]: el => {alert(el.value)},
    [view.Key.ESCAPE]: () => {alert('Esc')},
}})

Two-way data binding: bind

The value of the to element property gets assigned to the model[key] on every event specified in on. The opposite happens on every change of model[key]. Parameter to defaults to 'checked' for checkboxes or 'value' for anything else, and on defaults to ['change'].

{bind: {model: proxy, key: string, to: string, on: string|[string]}}

h('input', {bind: {model: proxy, key: 'title', to: 'value', on: ['keydown', 'keyup']}})

Examples

• Component TodoMVC
• MVVM TodoMVC (75 SLOC)

Performance

Satori is very fast. It was built with performance in mind and tries to do only what is essential, so there’s actually not much room left for further optimization of typical operations. It updates the UI asynchronously to make bulk updates faster and reflects array modifications with minimal DOM changes. It shows very good results on the TodoMVC benchmark, but I won’t provide you with them due to its controversial nature. In particular, libraries based on virtual DOM, despite performing well in this benchmark, tend to have poor responsiveness when the number of rendered elements is large enough. For instance, simple editing of text in an input field can become irritating because of the delays introduced by rerendering and diffing performed by those libraries on each keystroke.

Helper functions

• qs(selector, scope = document) — alias for scope.querySelector(selector)
• qsa(selector, scope = document) — alias for scope.querySelectorAll(selector)
• each(selector, scope = document, func) — call func for each element in querySelectorAll() result
• sortCompare(a, b) — comparer for sorting numbers and strings, for example: ['b', 'a'].sort(sortCompare)
• arrayRemove(array, value) — remove first occurrence of value from array

Debugging

Enable logging of all flushes and affected observers in console:

view.logFlushes = true;

Enable logging of all proxy events:

view.logEvents = true;

Highlight all affected DOM elements:

view.highlightUpdates = true;

To inspect registered object observers, just explore the [Symbol(proxyInternals)].observers property of the proxy object in the developer tools of your browser. Most interesting observer fields are element and name. When you hover the element value, the actual element will usually be highlighted if it is visible.

License

Apache 2.0.