api.md

Modules

fx

subs

fx

• fx
  • .exports.BatchFx(...fx)
  • .exports.Console(...args)
  • .exports.Debounce(props)
  • .exports.HistoryPush(props)
  • .exports.HistoryReplace(props)
  • .exports.Http(props)
  • .exports.Merge(action)
  • .exports.Random(props)
  • .exports.WriteToStorage(props)
  • .exports.ReadFromStorage(props)
  • .exports.RemoveFromStorage(props)
  • .exports.Throttle(props)

fx.exports.BatchFx(...fx)

Kind: static method of fx

Param	Type	Description
...fx	*	FX to run together in a batch

Example

import { BatchFx } from "hyperapp-fx"

const BatchedAction = state => [
  state,
  BatchFx(
    Effect1,
    Effect2,
    // ...
  )
]

fx.exports.Console(...args)

Describes an effect that will call console.log with arguments. Useful for development and debugging. Not recommended for production.

Kind: static method of fx

Param	Type	Description
...args	*	arguments to log to the console

Example

import { Console } from "hyperapp-fx"

const ConsoleAction = state => [
  state,
  Console(
    "string arg",
    { object: "arg" },
    ["list", "of", "args"],
    someOtherArg
  )
]

fx.exports.Debounce(props)

Describes an effect that will call an action after waiting for a delay to pass. The delay will be reset each time the action is called.

Kind: static method of fx

Param	Type	Description
props	object
props.wait	number	delay to wait before calling the action
props.action	*	action to debounce

Example

import { Debounce } from "hyperapp-fx"

const DebouncedAction = state => [
  state,
  Debounce({
    wait: 500,
    action() {
      // This action will run after waiting for 500ms since the last call
    }
  })
]

fx.exports.HistoryPush(props)

Describes an effect that will update the browsers navigation history with the supplied location and state.

Kind: static method of fx

Param	Type	Description
props	object
props.state	*	data to add to browser history
props.url	string	url to add to browser history
props.title	string	title to set document to

Example

import { Console } from "hyperapp-fx"

export const UpdateHistory = state => [
  state,
  HistoryPush({
    state,
    title: document.title,
    url: '#foo'
  })
]

fx.exports.HistoryReplace(props)

Describes an effect that will replace the browsers navigation history with the supplied location and state.

Kind: static method of fx

Param	Type	Description
props	object
props.state	*	data to add to browser history
props.url	string	url to add to browser history
props.title	string	title to set document to

Example

import { Console } from "hyperapp-fx"

export const InitialiseHistory = state => [
  state,
  HistoryReplace({
    state,
    title: document.title,
    url: '#foo'
  })
]

fx.exports.Http(props)

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 one of the available fetch polyfills.

Kind: static method of fx

Param	Type	Description
props	object
props.url	string	URL for sending HTTP request
props.options	string	same options as fetch
props.response	string	Specify which method to use on the response body, defaults to "json", other supported methods include "text"
props.action	*	Action to call with the results of a successful HTTP response
props.error	*	Action to call if there is a problem making the request or a not-ok HTTP response, defaults to the same action defined for success

Example

import { Http } from "hyperapp-fx"

const Login = state => [
  state,
  Http({
    url: "/login",
    options: {
      method: "POST",
      body: form
    },
    action(state, loginResponse) {
      // loginResponse will have the JSON-decoded response from POSTing to /login
    },
    error(state, error) {
      // please handle your errors...
    }
  })
]

fx.exports.Merge(action)

Kind: static method of fx

Param	Type	Description
action	function	an action function that takes state and returns a partial new state which will be shallow-merged with the previous state

Example

import { Merge } from "hyperapp-fx"

const MergingAction = state => [
  state,
  Merge(ActionReturningPartialState)
]

fx.exports.Random(props)

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.

Kind: static method of fx

Param	Type	Description
props	object
props.action	*	action to call with the random number result
props.min	number	minimum random number to generate
props.max	number	maximum random number to generate

Example

import { Random } from "hyperapp-fx"

const RollDie = state => [
  state,
  Random({
    min: 1,
    // We use the max of 7 to include all values of 6.x
    max: 7,
    action: (_, randomNumber) => {
      const roll = Math.floor(randomNumber)
      // roll will be an int from 1-6

      // return new state using roll
    }
  })
]

fx.exports.WriteToStorage(props)

Describes an effect that will write a key value pair to Storage. By default the item is written to localStorage, to write to sessionStorage set the storage prop to session. Values are saved in JSON, unless a custom converter is provided.

Kind: static method of fx

Param	Type	Description
props	object
props.key	string	Specify key to use
props.value	*	Value to write to storage
props.storage	string	Storage area to write to, can be either "session" or "local"
props.converter	function	Use a custom converter function to encode the value of the item

Example

import { WriteToStorage } from "hyperapp-fx"

const SavePreferences = (state, preferences) => [
  state,
  WriteToStorage({
    name: "preferences",
    value: preferences,
    storage: "local"
  })
]

fx.exports.ReadFromStorage(props)

Describes an effect that will read the value of a key from Storage. By default the item is read from localStorage, to read from sessionStorage set the storage prop to session. Values are converted from JSON, unless a custom converter is provided.

Kind: static method of fx

Param	Type	Description
props	object
props.key	string	Specify key to use with which to write to storage
props.action	*	Action to call with the value of the item in storage
props.storage	string	Storage area to read from, can be either "session" or "local"
props.prop	string	Property of the action where the value is received, defaults to "value"
props.converter	function	Use a custom converter function to decode the value of the item

Example

import { ReadFromStorage } from "hyperapp-fx"

const LoadPreferences = state => [
 state,
 ReadFromStorage({
   key: "preferences",
   action: function (state, { value }) {
     // this action will receive the value of the item in storage
   }
 })
]

fx.exports.RemoveFromStorage(props)

Describes an effect that will remove a key value pair Storage. By default the item is deleted from localStorage, to delete from sessionStorage set the storage prop to session.

Kind: static method of fx

Param	Type	Description
props	object
props.key	string	Specify key to delete from storage
props.storage	string	Storage area to delete from, can be either "session" or "local"

Example

import { RemoveFromStorage } from "hyperapp-fx"

const ClearPreferences = state => [
 state,
 RemoveFromStorage({
   key: "preferences",
   storage: "local"
 })
]

fx.exports.Throttle(props)

Describes an effect that will call an action at a maximum rate. Where rate is one call per rate milliseconds.

Kind: static method of fx

Param	Type	Description
props	object
props.rate	number	minimum time between action calls
props.action	*	action to throttle

Example

import { Throttle } from "hyperapp-fx"

const ThrottledAction = state => [
  state,
  Throttle({
    rate: 500,
    action() {
      // This action will only run once per 500ms
    }
  })
]

subs

• subs
  • .exports.Animation(action)
  • .exports.HistoryPop(action)
  • .exports.Keyboard(props)
  • .exports.Time(props)
  • .exports.WebSocketClient(props)

subs.exports.Animation(action)

Describes an effect that will call an action from inside a requestAnimationFrame loop, which is also where the render triggered by the action will run. A relative timestamp will be provided as the action data.

Kind: static method of subs

Param	Type	Description
action	*	action to call inside a requestAnimationFrame loop

Example

import { h, app } from "hyperapp"
import { Animation, BatchFx, Merge } from "hyperapp-fx"

const UpdateTime = time => ({ time: lastTime, delta: lastDelta }) => ({
  time,
  delta: time && lastTime ? time - lastTime : lastDelta
})

const AnimationFrame = (state, time) => [
  state,
  BatchFx(
    Merge(UpdateTime(time)),
    Merge(UpdateStateForDelta),
    Merge(UpdateMoreStateForDelta),
    // ...
  )
]

app({
  init: {
    time: 0,
    delta: 0,
    running: true
  }
  // ...
  subscriptions: ({ running }) => (running ? [Animation(AnimationFrame)] : [])
})

subs.exports.HistoryPop(action)

Describes an effect that will call an action whenever a user navigates through their browser history. The action will receive the state at that point in the browsers history

Kind: static method of subs

Param	Type	Description
action	*	Action to call

Example

import { HistoryPop } from "hyperapp-fx"

app({
 init: { page: 1 },
 view: state => <App page={state.page} />,
 container: document.body,
 subscriptions: state => [HistoryPop({ action: (state, event) => event.state || state })]
})

subs.exports.Keyboard(props)

Describes an effect that can capture keydown, keyup, and keypress events for your entire document. The KeyboardEvent will be provided as the action data.

Kind: static method of subs

Param	Type	Description
props	object
props.downs	boolean	listen for keydown events
props.ups	boolean	listen for keyup events
props.presses	boolean	listen for keypress events
props.action	*	action to call when keyboard events are fired

Example

import { Keyboard } from "hyperapp-fx"

const KeySub = Keyboard({
  downs: true,
  ups: true,
  action: (_, keyEvent) => {
    // keyEvent has the props of the KeyboardEvent
    // action will be called for keydown and keyup
  }
})

subs.exports.Time(props)

Describes an effect that can provide timestamps to actions using performance.now or dates using the new Date() API. The action can be fired now, after a delay, or at a regular interval. The timestamp/date will be provided as the action data.

Kind: static method of subs

Param	Type	Description
props	object
props.now	boolean	get the current time immediately
props.after	number	get the time after a delay
props.every	number	get the time repeatedly after waiting a set interval
props.asDate	boolean	use a Date object instead of a timestamp
props.action	*	action to call with the time

Example

import { h, app } from "hyperapp"
import { Time } from "hyperapp-fx"

const UpdateDate = (_, date) =>
  date.toLocaleString("uk", {
    hour: "numeric",
    minute: "numeric",
    second: "numeric"
  })

const InitialTime = Time({
  now: true,
  asDate: true,
  action: UpdateDate
})

const TimeSub = Time({
  every: 100,
  asDate: true,
  action: UpdateDate
})

app({
  init: ["", InitialTime],
  view: time => <h1>{time}</h1>,
  container: document.body,
  subscriptions: () => [TimeSub]
})

subs.exports.WebSocketClient(props)

Describes an effect that will open a WebSocket connection for a given URL and optional protocols. A message may be sent to the server on connection and messages to the client may be listened for. Connections will remain open until the last subscription for that URL are cancelled.

Kind: static method of subs

Param	Type	Description
props	object
props.url	string	The URL to which to connect; this should be the URL to which the WebSocket server will respond
props.protocols	string | Array.<string>	Either a single protocol string or an array of protocol strings. These strings are used to indicate sub-protocols, so that a single server can implement multiple WebSocket sub-protocols (for example, you might want one server to be able to handle different types of interactions depending on the specified protocol). If you don't specify a protocol string, an empty string is assumed.
props.send	*	data to send once connected
props.listen	*	action to call with new incoming messages
props.error	*	action to call if an error occurs

Example

import { WebSocketClient } from "hyperapp-fx"

const WebSocketSub = WebSocketClient({
  url: "wss://example.com",
  send: JSON.stringify({
    sendThisData: "on connecting"
  }),
  listen: ReceivedMessageAction
})