@conveyal/woonerf
v4.2.1
Published
React/Redux bootstrapping and common libs for Conveyal
Downloads
302
Keywords
Readme
woonerf
React/Redux bootstrapping and common libs for Conveyal.
Modern JavaScript applications take a lot of bootstrapping. This library helps with some common libs to include and use on the client to help.
Table of Contents
Pronunciation
"Woonerf" is a Dutch word for a small neighborhood street where vehicles must move very slowly. The kind of road you can imagine allowing kids to play in. Although it's fun to pronounce it as "woo nerf", the break is after the n (woon == living, erf == yard). A good transliteration for an American English speaker would be "Vone Airf".
Usage
Let's create a Redux application:
const mount = require('@conveyal/woonerf/mount')
const Application = require('./containers/application')
const reducers = require('./reducers')
mount({
app: Application,
id: 'root',
reducers
})
This will create a redux store with the fetch
, history
, logger
, multi
, and promise
middleware applied, wrap your application with a redux provider, initialize the browser history, and mount your component to #id
. The component passed as app
will be passed history
from react-router-redux and the initialized redux store
as props.
API
auth0
Login Component
Create a simple login component with custom Auth0-lock options.
import Auth0 from '@conveyal/woonerf/components/auth0-lock'
export default function Login () {
const lockOptions = {}
return (
<Auth0
lockOptions={lockOptions}
/>
)
}
Authentication helpers
refreshUser
Refresh a user. To be used within a redux connected component. Will send update actions to a redux store based on response from Auth0.
import {refreshUser} from '@conveyal/woonerf/auth0'
...
function mapDispatchToProps (dispatch) {
return {
refreshUserToken: () => refreshUser(dispatch)
}
}
...
fetch
fetch({url, options, next, retry, type, id})
Create a fetch action to be dispatched by the store. Key features:
- Automatically
JSON.stringify
bodies that are objects and automaticallyJSON.parse
responses that areapplication/json
. next
is a function that's result will be dispatched by the store. It can be anasync
function.retry
is a function that receives the response and needs to resolve to a Boolean. It can be anasync
function.Authorization
,Content-Type
andAccept
headers are added automatically (if you want to make a request without one of these headers, for instance suppressing the Authorization header when calling a remote service, simply set it to null in theheaders
field ofoptions
).type
is a string that can designate a category of fetches that will only run one at a time.id
can be used to later abort the specific fetch by dispatching anabortFetch
action.
fetch errors
The arity of next
determines how errors are handled.
- When no
next
is present, afetchError
action is dispatched. - When a
next
function with arity < 2 is present, then on errorfetchError
is dispatched andnext
is not called. - When
next
has an arity >= 2 then errors are passed tonext
andfetchError
is not dispatched.
const fetch = require('@conveyal/woonerf/fetch')
store.dispatch(fetch({
url: 'http://conveyal.com',
options: {
method: 'post',
body: {hello: 'world'}
},
retry: async (response) => {
if (response.status !== 200) {
await timeout(2000)
return true
} else {
return false
}
},
next: async (error, response) => {
return actionBasedOn(response)
}
}))
abort fetch
Abort a fetch by dispatching abortFetch({type, id})
.
const fetch, {abortFetch, getID} = require('@conveyal/woonerf/fetch')
const id = getID()
store.dispatch(fetch({
url: 'http://conveyal.com',
id,
next: () => {
throw new Error('Will not be called')
}
}))
store.dispatch(abortFetch({id}))
fetchMultiple
fetchMultiple({fetches, next})
Allows you to dispatch a single action that will call next with all of the responses.
const {fetchMultiple} = require('@conveyal/woonerf/fetch')
store.dispatch(fetchMultiple({
fetches: [{
url: 'http://conveyal.com',
options: {
body: {hello: 'world'}
}
}],
next: async (error, responses) => {
return actionBasedOn(response)
}
}))
html
html({staticHost, title})
Used for creating the default HTML needed to use a woonerf application. Accepts the following parameters:
staticHost
: (optional) The host server of the static files. This gets prepended to an expected assets folder for the static files. The files loaded will be:${staticHost}assets/favicon.ico
,${staticHost}assets/index.css
and${staticHost}assets/index.js
. If omitted, the host path will be an empty string.title
: The string to insert into thetitle
tag.
message
message(key, defaultMessage, parameters)
Pass a key, an optional default message, and an optional parameters object that will replace corresponding %(key)
. It auto-parses process.env.MESSAGES
brought in by mastarm
and allows you to set your own messages directly with setMessages
. Message lookup is done with lodash/get
for nested objects.
import message, {setMessages} from '@conveyal/woonerf/message'
setMessages({one:'hello world', two:'hola %(s)', three: {four: 'wat'}})
message('key.doesnt.exist', 'default message') // 'default message'
message('one', 'default message') // 'hello world'
message('three.four', 'default message') // 'wat'
message('fake.key', 'hello %(world)s', {world: 'bob'}) // 'hello bob'
message('two', 'hello %(s)', {s: 'bob'}) // 'hola bob'
message('fake.key', 'hello %(a) %(b)', {a: 'bob', b: 'tim'}) // 'hello bob tim'
Install
With yarn installed, run
$ yarn add @conveyal/woonerf
See Also
License
MIT