hyperapp-effects
v0.5.2Hyperapp Effects
A Hyperapp Higher-Order App giving your app
superpowers to write your effects as data, inspired by Elm Commands.
Installation
Node.js
Install with npm / Yarn.
npm i hyperapp-effects
Then with a module bundler like parcel, rollup or webpack, use as you would anything else.
import { withEffects } from "hyperapp-effects"
Or using require.
const { withEffects } = require("hyperapp-effects")
Browser
Download the minified library from the CDN.
<script src="https://unpkg.com/hyperapp-effects"></script>
You can find the library in window.effects
.
API
Effects data
EffectTuple = [type: string, props: object]
Effect = EffectTuple | EffectTuple[] | Effect[]
Effects are always represented as arrays. For a single effect this array represents a tuple containing the effect type string and an object containing the properties of this effect. For multiple effects each array element is either an effect tuple or an array of these tuples, which may be nested. This means that effects are composeable.
withEffects
EffectsConfig = {
[effectName]: (
props: object,
getAction: (name: string) => Action
) => undefined
}
withEffects = App => App | EffectsConfig => App => App
This Higher-Order App function enables actions
to return arrays which later will be run as effects.
Example:
import { withEffects } from "hyperapp-effects"
const state = {
// ...
}
const actions = {
foo: () => [
// ... effects go here
],
bar: () => // or a single effect can go here
}
withEffects(app)(state, actions).foo()
For custom effects pass an object to withEffects
before composing with your app
:
import { withEffects } from "hyperapp-effects"
const state = {
// ...
}
const actions = {
// You will probably want to write a helper function for returning these
// similar to the built-in effects
foo: () => [
// type of effect for effects data
// must match key used in custom effect object below
"custom",
{
// ... props go here
}
]
}
withEffects({
// key in this object must match type used in effect data above
custom(props, getAction) {
// use props to get the props used when creating the effect
// use getAction for firing actions when appropriate
}
})(app)(state, actions).foo()
Reusing an existing effect type will override the built-in one.
action
action = (name: string, data?: any) => EffectTuple
Describes an effect that will fire another action, optionally with data
.
Example:
import { withEffects, action } from "hyperapp-effects"
const state = {
// ...
}
const actions = {
foo: () => [
action("bar", { message: "hello" }),
action("baz", { message: "hola" }),
// ... other effects
],
bar: data => {
// data will have { message: "hello" }
},
baz: data => {
// data will have { message: "hola" }
}
}
withEffects(app)(state, actions).foo()
Note that you may also use a single action effect without an array wrapper and that nested actions
may be called by separating the slices with dots:
import { withEffects, action } from "hyperapp-effects"
const state = {
// ...
}
const actions = {
foo: () => action("bar.baz", { message: "hello" }),
bar: {
baz: data => {
// data will have { message: "hello" }
}
}
}
withEffects(app)(state, actions).foo()
This same convention follows for all the other effects as well.
Also note that action
(and other effects) may be used for handler props in your view
:
import { withEffects, action } from "hyperapp-effects"
const state = {
// ...
}
const actions = {
foo: data => {
// data will have { message: "hello" }
// when the button is clicked
}
}
const view = () => h("button", {
onclick: action("foo", { message: "hello" })
})
withEffects(app)(state, actions, view, document.body)
frame
frame = (action: string) => EffectTuple
Describes an effect that will call an action from inside requestAnimationFrame
, which is also where the render triggered by the action will run. A relative timestamp will be provided as the action data
. If you wish to have an action that continuously updates the state
and rerenders inside of requestAnimationFrame
(such as for a game), remember to include another frame
effect in your return.
Example:
import { withEffects, action, frame } from "hyperapp-effects"
const state = {
time: 0,
delta: 0
}
const actions = {
init: () => frame("update"),
update: time => [
action("incTime", time),
// ...
// Other actions to update the state based on delta time
// ...
// End with a recursive frame effect to perform the next update
frame("update")
],
incTime: time => ({ time: lastTime, delta: lastDelta }) => ({
time,
delta: time && lastTime ? time - lastTime : lastDelta
})
}
withEffects(app)(state, actions).init()
delay
delay = (duration: number, action: string, data?: any) => EffectTuple
Describes an effect that will call an action after a delay using setTimeout
, optionally with data
.
Example:
import { withEffects, delay } from "hyperapp-effects"
const state = {
// ...
}
const actions = {
startTimer: () => delay(
60000,
"alarm",
{ name: "minute timer" }
),
alarm: data => {
// This action will run after a minute delay
// data will have { name: "minute timer" }
}
}
withEffects(app)(state, actions).startTimer()
time
time = (action: string) => EffectTuple
Describes an effect that will provide the current timestamp to an action using performance.now
. The timestamp will be provided as the action data
.
Example:
import { withEffects, time } from "hyperapp-effects"
const state = {
// ...
}
const actions = {
foo: () => time("bar"),
bar: timestamp => {
// use timestamp
}
}
withEffects(app)(state, action).foo()
log
log = (...args: any[]) => EffectTuple
Describes an effect that will call console.log
with arguments. Useful for development and debugging. Not recommended for production.
Example:
import { withEffects, log } from "hyperapp-effects"
const state = {
// ...
}
const actions = {
foo: () => log(
"string arg",
{ object: "arg" },
["list", "of", "args"],
someOtherArg
)
}
withEffects(app)(state, actions).foo()
http
http = (url: string, action: string, options?: object) => EffectTuple
Describes an effect that will send an HTTP request using fetch
and then call an action with the response. If you are using a browser from the Proterozoic Eon like Internet Explorer you will want a fetch
polyfill. An optional options
parameter supports the same options as fetch
plus the following additional properties:
Property | Usage | Default |
---|---|---|
response |
Specify which method to use on the response body. | "json" |
error |
Action to call if there is a problem making the request or a not-ok HTTP response. | Same action as defined for success |
Example HTTP GET request with a JSON response:
import { withEffects, http } from "hyperapp-effects"
const state = {
// ...
}
const actions = {
foo: () => http("/data", "dataFetched"),
dataFetched: data => {
// data will have the JSON-decoded response from /data
}
}
withEffects(app)(state, actions).foo()
Example HTTP GET request with a text response:
import { withEffects, http } from "hyperapp-effects"
const state = {
// ...
}
const actions = {
foo: () => http(
"/data/name",
"textFetched",
{ response: "text" }
),
textFetched: data => {
// data will have the response text from /data
}
}
withEffects(app)(state, actions).foo()
Example HTTP POST request using JSON body and response that handles errors:
import { withEffects, http } from "hyperapp-effects"
const state = {
// ...
}
const actions = {
login: form => http(
"/login",
"loginComplete",
{
method: "POST",
body: form,
error: "loginError"
}
),
loginComplete: loginResponse => {
// loginResponse will have the JSON-decoded response from POSTing to /login
},
loginError: error => {
// please handle your errors...
}
}
withEffects(app)(state, actions).login()
event
event = (action: string) => EffectTuple
Describes an effect that will capture DOM Event data when attached to a handler in your view
. The originally fired event will be provided as the action data
.
import { withEffects, event } from "hyperapp-effects"
const state = {
// ...
}
const actions = {
click: clickEvent => {
// clickEvent has the props of the click event
}
}
const view = () => h("button", {
onclick: event("click")
})
withEffects(app)(state, actions, view, document.body)
keydown
keydown = (action: string) => EffectTuple
Describes an effect that will capture keydown events for your entire document. The KeyboardEvent
will be provided as the action data
.
Example:
import { withEffects, keydown } from "hyperapp-effects"
const state = {
// ...
}
const actions = {
init: () => keydown("keyPressed"),
keyPressed: keyEvent => {
// keyEvent has the props of the KeyboardEvent
}
}
withEffects(app)(state, actions).init()
keyup
keyup = (action: string) => EffectTuple
Describes an effect that will capture keyup events for your entire document. The KeyboardEvent
will be provided as the action data
.
Example:
import { withEffects, keyup } from "hyperapp-effects"
const state = {
// ...
}
const actions = {
init: () => keyup("keyReleased"),
keyReleased: keyEvent => {
// keyEvent has the props of the KeyboardEvent
}
}
withEffects(app)(state, actions).init()
random
random = (action: string, min?: number, max?: number) => EffectTuple
Describes an effect that will call an action with a randomly generated number within a range. If provided the range will be [min, max)
or else the default range is [0, 1)
. The random number will be provided as the action data
.
Use Math.floor
if you want a random integer instead of a floating-point number. Remember the range will be max
exclusive, so use your largest desired int + 1.
Example:
import { withEffects, random } from "hyperapp-effects"
const state = {
// ...
}
const actions = {
// We use the max of 7 to include all values of 6.x
foo: () => random("rollDie", 1, 7),
rollDie: randomNumber => {
const roll = Math.floor(randomNumber)
// roll will be an int from 1-6
}
}
withEffects(app)(state, actions).foo()
effectsIf
EffectConditional = [boolean, EffectTuple]
effectsIf = EffectConditional[] => EffectTuple[]
Convert an array of [boolean, EffectTuple]
s into a new array of effects where the boolean evaluated to true. This provides compact syntatic sugar for conditionally firing effects.
Example:
import { withEffects, effectsIf, action } from "hyperapp-effects"
const state = {
// ...
}
const actions = {
foo: () => ({ running }) => effectsIf([
[true, action("always")],
[false, action("never")],
[running, action("ifRunning")],
[!running, action("ifNotRunning")]
])
}
withEffects(app)(state, actions).foo()
License
Hyperapp Effects is MIT licensed. See LICENSE.
Metadata
- MIT
- Whatever
- Wolfgang Wedemeyer
- released 2/18/2018