From 12ae95b297a117b2288647560ad1622b386028d4 Mon Sep 17 00:00:00 2001 From: Yoshua Wuyts Date: Sat, 21 May 2016 22:44:03 +0900 Subject: [PATCH] docs: add examples, index --- README.md | 113 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 92 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 6698321..41ef550 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,21 @@ A framework for creating sturdy web applications. Built on years of industry experience it distills the essence of functional architectures into a productive package. +- [features](#features) +- [demos](#demos) +- [usage](#usage) +- [concepts](#concepts) +- [effects](#effects) + - [HTTP](#http) +- [subscriptions](#subscriptions) + - [server sent events](#server-sent-events-sse) + - [keyboard](#keyboard) + - [websockets](#websockets) +- [API](#api) +- [FAQ](#faq) +- [installation](#installation) +- [license](#license) + ## Features - __minimal size:__ weighing under `8kb`, `choo` is a tiny little framework - __single state:__ immutable single state helps reason about changes @@ -101,7 +116,7 @@ document.body.appendChild(tree) ## Effects Side effects are done through `effects` declared in `app.model()`. Unlike `reducers` they cannot modify the state by returning objects, but get a -callback passed hich is used to emit `actions` to handle results. +callback passed which is used to emit `actions` to handle results. A typical `effect` flow looks like: @@ -140,19 +155,71 @@ Note that `http` only runs in the browser to prevent accidental requests when rendering in Node. For more details view the [`raynos/xhr` documentation](https://github.com/Raynos/xhr). -## Subscriptions (wip) +## 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. ### Server Sent Events (SSE) -[tbi] - help and suggestions welcome! +[Server Sent Events (SSE)][sse] allow servers to push data to the browser. +They're the unidirectional cousin of `websockets` and compliment `HTTP` +brilliantly. To enable `SSE`, create a new `EventSource`, point it at a local +uri (generally `/sse`) and setup a `subscription`: +```js +const stream = new document.EventSource('/sse') + +app.model({ + subscriptions: [ + function (send) { + stream.onerror = (e) => send('error', { payload: JSON.stringify(e) }) + stream.onmessage = (e) => send('print', { payload: e.data }) + } + ], + effects: { + 'sse:close': () => stream.close() + error: (state, event_ => console.error(`error: ${event.payload}`)), + print: (state, event) => console.log(`pressed key num: ${event.payload}`) + } +}) +``` ### Keyboard -[tbi] - help and suggestions welcome! +Most browsers have [basic support for keyboard events][keyboard-support]. To +capture keyboard events, setup a `subscription`: +```js +app.model({ + subscriptions: [ + function (send) { + keyboard.onkeypress = (e) => send('print', { payload: e.keyCode }) + } + ], + effects: { + print: (state, event) => console.log(`pressed key num: ${event.payload}`) + } +}) +``` -### Websockets -[tbi] - help and suggestions welcome! +### WebSockets +[WebSockets][ws] allow for bidirectional communication between servers and +browsers: +```js +const socket = new document.WebSocket('ws://localhost:8081') + +app.model({ + subscriptions: [ + function (send) { + socket.onerror = (e) => send('error', { payload: JSON.stringify(e) }) + socket.onmessage = (e) => send('print', { payload: e.data }) + } + ], + effects: { + 'ws:close': () => socket.close(), + 'ws:send': (state, event) => socket.send(JSON.stringify(event.payload)), + error: (state, event_ => console.error(`error: ${event.payload}`)), + print: (state, event) => console.log(`pressed key num: ${event.payload}`) + } +}) +``` ## API ### app = choo() @@ -187,14 +254,28 @@ where `params` is URI partials. Start the application. Returns a DOM element that can be mounted using `document.body.appendChild()`. -## Packages used +## FAQ +### How does choo compare to X? +- __react:__ [tbi] +- __mithril:__ [tbi] +- __preact:__ [tbi] +- __angular2:__ [tbi] + +## Which packages was choo built on? - __views:__ [`yo-yo`](https://github.com/maxogden/yo-yo) - __models:__ [`send-action`](https://github.com/sethvincent/send-action), [`xtend`](https://github.com/raynos/xtend) - __routes:__ [`sheet-router`](https://github.com/yoshuawuyts/sheet-router) - __http:__ [`xhr`](https://github.com/Raynos/xhr) -## Optimizing +## What packages do you recommend to pair with choo? +- [tachyons](https://github.com/tachyons-css/tachyons) - functional CSS for + humans +- [sheetify](https://github.com/stackcss/sheetify) - modular CSS bundler for + browserify +- [pull-stream](https://github.com/pull-stream/pull-stream) - minimal streams + +## How can I optimize choo? To bring down file size, consider running the following `browserify` transforms: - [unassertify](https://github.com/twada/unassertify) - remove `assert()` @@ -204,19 +285,6 @@ transforms: - [uglifyify](https://github.com/hughsk/uglifyify) - minify your code using UglifyJS2. Use as a `--global` transform -## Packages that work well together -- [tachyons](https://github.com/tachyons-css/tachyons) - functional CSS for - humans -- [sheetify](https://github.com/stackcss/sheetify) - modular CSS bundler for - browserify - -## FAQ -### How does choo compare to X? -- __react:__ [tbi] -- __mithril:__ [tbi] -- __preact:__ [tbi] -- __angular2:__ [tbi] - ## Installation ```sh $ npm install choo @@ -238,3 +306,6 @@ $ npm install choo [10]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square [11]: https://github.com/feross/standard [dom]: https://en.wikipedia.org/wiki/Document_Object_Model +[keyboard-support]: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent#Browser_compatibility +[sse]: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events +[ws]: https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API