History repeats itself.
Farce provides a Redux store enhancer that wraps a series of middlewares to allow controlling browser navigation by dispatching actions and to allow managing location state with the rest of your store state.
Farce can also create a history object that is compatible with history v2 for use with React Router v2.
import {
Actions as FarceActions,
BrowserProtocol,
createHistoryEnhancer,
locationReducer,
queryMiddleware,
} from 'farce';
import { combineReducers, createStore } from 'redux';
const store = createStore(
combineReducers({
location: locationReducer,
}),
createHistoryEnhancer({
protocol: new BrowserProtocol(),
middlewares: [queryMiddleware],
}),
);
store.dispatch(FarceActions.init());
// To transition to a new location:
store.dispatch(FarceActions.push('/new/path'));
// To get the current location:
const location = store.getState().location;
// -> { action: 'PUSH', pathname: '/new/path', ... }
$ npm i -S redux
$ npm i -S farce
Create a history enhancer with createHistoryEnhancer
. Configure it with an options object with a protocol
property to control how to interact with browser APIs and an optional middlewares
property to customize handling of location objects. Use this history enhancer to enhance your store.
Install locationReducer
to track the current location state in your store.
const store = createStore(
combineReducers({
location: locationReducer,
}),
createHistoryEnhancer({
protocol: new BrowserProtocol(),
middlewares: [queryMiddleware],
}),
);
Dispatch FarceActions.init()
to initialize up your store with the current browser state and to set up event listeners.
Dispatch FarceActions.push(location)
, FarceActions.replace(location)
, or FarceActions.go(delta)
to navigate.
// Add a /foo history entry.
store.dispatch(FarceActions.push('/foo'));
// Replace the current history entry with /bar.
store.dispatch(FarceActions.replace('/bar'));
// Go back one entry.
store.dispatch(FarceActions.go(-1));
If you want to tear down all event listeners, dispatch FarceActions.dispose()
.
store.dispatch(FarceActions.dispose());
BrowserProtocol
uses the browser URL path and the HTML5 History API.
const protocol = new BrowserProtocol();
The examples here assume the use of a new BrowserProtocol()
.
ServerProtocol
uses a fixed, in-memory location for use in server-side rendering. It takes the path for the location to use. ServerProtocol
instances do not support location.state
and cannot navigate.
// Given a standard Node request object:
const protocol = new ServerProtocol(req.url);
The queryMiddleware
middleware adds support for the query
property, which enables the use of query objects to set the search string.
The createQueryMiddleware
middleware factory creates a custom query middleware. It takes a configuration object with parse
and stringify
functions as properties to configure parsing and stringifying queries.
import qs from 'qs';
const customQueryMiddleware = createQueryMiddleware({
parse: qs.parse, stringify: qs.stringify,
});
The examples here assume the use of queryMiddleware
.
The createBasenameMiddleware
middleware factory creates a middleware that implicitly prepends all paths with a base path. It takes a configuration object with a basename
string.
// With this middleware, dispatching FarceActions.push('/bar') will navigate to
// /foo/bar:
const basenameMiddleware = createBasenameMiddleware({ basename: '/foo' });
The locationReducer
reducer updates the store state with a location object. Location objects have the following properties:
action
:'PUSH'
or'REPLACE'
if the location was reached viaFarceActions.push
orFarceActions.replace
respectively;'POP'
on the initial location, or if the location was reached via the browser back or forward buttons or viaFarceActions.go
pathname
: the path name; as onwindow.location
search
: the search string; as onwindow.location
hash
: the location hash; as onwindow.location
key
: if present, a unique key identifying the current history entryindex
: the current index of the history entry, starting at 0 for the initial entry; this increments onFarceActions.push
but not onFarceActions.replace
delta
: the difference between the currentindex
and theindex
of the previous locationstate
: additional location state that is not part of the URL
If a queryMiddleware
is applied, the location object will also contain a query
property that is the parsed query object from the search string. If a basenameMiddleware
is applied, pathname
will be relative to the specified basename
.
FarceActions.push
and FarceActions.replace
take a location descriptor. A location descriptor can be an object with the shape of the location object. If it is an object, the action
, key
, index
, and delta
keys are ignored. A location descriptor can also be a string with the full path.
// Location descriptor string:
store.dispatch(FarceActions.push('/foo?bar=baz#qux'));
// Equivalent location descriptor object:
store.dispatch(FarceActions.push({
pathname: '/foo',
search: '?bar=baz',
hash: '#qux',
}));
// Given a location object, you can override a subset of its properties:
store.dispatch(FarceActions.replace({
...location,
query: { the: 'new-query' },
hash: '#new-hash',
}));
The history enhancer adds a farce
object as a property to the store that exposes createHref
and createLocation
methods. createHref
takes a location descriptor and returns a link href
. createLocation
takes a location descriptor and returns the corresponding location object.
const href = store.farce.createHref({
pathname: '/foo',
query: { the: 'query' },
});
// -> '/foo?the=query'
const location = store.farce.createLocation('/foo?the=query');
// -> { pathname: '/foo', query: { the: 'query' }, ... }
The farce
object on the store also has an addTransitionHook
method. This method takes a transition hook function and returns a function to remove the transition hook.
const removeTransitionHook = store.farce.addTransitionHook(location => (
location.pathname === '/bar' ? 'Are you sure you want to go to /bar?' : true
));
// To remove the transition hook:
removeTransitionHook();
The transition hook function receives the location to which the user is attempting to navigate. This function may return:
true
to allow the transitionfalse
to block the transition- A string to prompt the user with that string as the message
- A nully value to call the next transition hook and use its return value, if present, or else to allow the transition
- A promise that resolves to any of the above values, to allow or block the transition once the promise resolves
When creating the history enhancer, you can set the useBeforeUnload
option to run transition hooks when the user attempts to leave the page entirely.
const historyEnhancer = createHistoryEnhancer({
...options,
useBeforeUnload: true,
});
If useBeforeUnload
is set, transition hooks will be called with a null
location when the user attempts to leave the page. In this scenario, the transition hook must return a non-promise value.
function transitionHook(location) {
if (location === null) {
return false;
}
return asyncConfirm(location);
}
The StateStorage
class provides transient storage associated with location objects. This can be used for tracking values like scroll position that should not be propagated when using a location object to build a new location descriptor. The StateStorage
constructor takes the farce
property from the store and a namespace
string to uniquely identify the state storage instance.
const stateStorage = new StateStorage(store.farce, 'my-transient-state');
The state storage object exposes read
and save
methods. The save
method takes a location object, an optional key to further qualify the saved property, and a JSON-serializable value; it saves the value to session storage. The read
method takes the location object and the key; it returns the saved value if retrievable or undefined
otherwise.
stateStorage.save(location, null, 1);
stateStorage.save(location, 'foo', [2, 3]);
const value1 = stateStorage.read(location);
// -> 1
const value2 = stateStorage.read(location, 'foo');
// -> [2, 3]
const value3 = stateStorage.read(location, 'bar');
// -> undefined
StateStorage
intentionally ignores errors. As such, it should be treated as unreliable. Do not use StateStorage
for managing state that is critical to the operation of your application.
Call createStoreHistory
on a store enhanced with createHistoryEnhancer
to create a history object that is API-compatible with history
v2. This object has an additional dispose
method for tearing down event listeners.
If you don't have a store, createHistory
will create a history object. It takes the same configuration options as createHistoryEnhancer
.
The top-level farce
package exports everything available in this library. It is unlikely that any single application will use all the features available. As such, for real applications, you should import the modules you need from farce/lib
directly, to pull in only the code that you use.
import BrowserProtocol from 'farce/lib/BrowserProtocol';
import createHistoryEnhancer from 'farce/lib/createHistoryEnhancer';
import queryMiddleware from 'farce/lib/queryMiddleware';
// Instead of:
// import { BrowserProtocol, createHistoryEnhancer, queryMiddleware }
// from 'farce';