reduxen v0.1.1
reduxen
Core module for reduxen.
Table of contents
API
Methods
createHistoryRouter
createHistoryRouter(options) -> { middleware, reducer }
Creates an object that contains the reducer and middleware for redux.
The options object can contain:
- prefix: for customize action namespace (e.g.
router/), defaults toROUTER__ - selectRouter: method that can be used for selecting the router from the state,
if it's not in the root. defaults to
state => state.router - initialUrl: the middleware uses the initialUrl for dispatching the first ENTER action instead of window.location (can be used for server side rendering)
- redirectCallback: will be invoked on push & replace, can be used for redirections on server side rendering
match
match(pattern, path) -> { params } | null
match(pattern)(path) -> { params } | null
Returns an object (including named parameters if the argument pattern matches the path, otherwise returns null.
Supported pattern parts:
fixed - must match the argument path part
:id - the part will be included under the name in the returned object
? - anything matches
(a|b|c) - must match with one of the defined items
:name(a|b) - must match with one of the defined items, the match will be included as name
* - matches anything at that part and after it (can only be used as the last part in the pattern)Examples:
match("/todos/:todoId", "/todos/182") -> { todoId: "182" }
match("/todos/:todoId", "/todos") -> null
match("/todos/?/:tab(content|author)", "/todos/182/author") -> { tab: "author" }Also, path-to-regexp can be an alternative to match() with further capabilities.
parseUrl
parseUrl(urlString) -> { path, query, hash }
Parses the argument URL string to an object that contains the defined parts.
Examples:
parseUrl("/nested/path/?query=string#hash") -> {
path: "/nested/path",
query: { query: "string" },
hash: "hash"
}
parseUrl("/?query=string") -> {
path: "/",
query: { query: "string" }
}
parseUrl("#hash") -> { hash: "hash" }stringifyUrl
stringifyUrl({ path, query, hash ) -> urlString
Stingifies the argument object to a string.
Examples:
stringifyUrl({
path: "/nested/path",
query: { query: "string" },
hash: "hash"
}) -> "/nested/path/?query=string#hash"
stringifyUrl({
path: "/",
query: { query: "string" }
}) -> "/?query=string"
stringifyUrl({ hash: "hash" }) -> "#hash"parseQuery
parseQuery(queryString) -> {}
Parses the argument query string to an object, where the values are strings. Can't handle nested query strings yet.
Example:
parseQuery("q=groceries&sortyBy=createdAt&count=10") ->
{ q: "groceries", sortBy: "createdAt", count: "10" }stringifyQuery
stringifyQuery({}) -> queryString
Stringifies the argument object, to a query string. Can't handle nested query strings yet.
Example:
parseQuery({ q: "groceries", sortBy: "createdAt", count: "10" }) ->
"q=groceries&sortyBy=createdAt&count=10"Reducer
Contains the actual parts of the URL. Will be updated on ENTERED actions.
{
path: string,
query: object,
hash: string
}Middleware
Dispatches
ENTERED
The middleware dispatches ENTERED action when the
transition finished. Contains the parts of the next
URL in the payload (path, query, hash), as well as
the parts of the previous URL (from).
Can be used for loading resources entering a URL.
Do not capture ENTERED actions in middlewares, as it leads to undefined behavior.
{
type: "ROUTER__ENTERED",
payload: {
path: string,
query: object,
hash: string,
from: {
path: string,
query: object,
hash: string,
}
}
}LEFT
The middleware dispatches LEFT action when the
transition finished, but before ENTERED.
Contains the parts of the current URL in the payload (path, query, hash),
as well as the parts of the next URL (to).
Can be used for releasing resources leaving a URL.
Do not capture LEFT actions in middlewares, as it leads to undefined behavior.
{
type: "ROUTER__LEFT",
payload: {
path: string,
query: object,
hash: string,
to: {
path: string,
query: object,
hash: string,
}
}
}Handles
PUSH
Dispatching PUSH action pushes a new history entry to the stack via history.pushState
The middleware completes the URL with parts that is higher in hierarchy. (e.g. if the payload contains only the query, the path will be reused from the actual URL, but not the hash)
Do not use history.pushState parallel with reduxen as they do not fire any events,
and it is impossible to be notified about route changes without monkey patching them.
Using them directly will leave reduxen out of sync, and leads to undefined behavior.
{
type: "ROUTER__PUSH",
payload: {
path: "/todos",
query: { sortBy: "createdAt" }
}
}REPLACE
Dispatching PUSH action replaces the current history entry on the stack via history.replaceState
The middleware completes the URL with parts that is higher in hierarchy. (e.g. if the payload contains only the query, the path will be reused from the actual URL, but not the hash)
Do not use history.replaceState parallel with reduxen as they do not fire any events,
and it is impossible to be notified about route changes without monkey patching them.
Using them directly will leave reduxen out of sync, and leads to undefined behavior.
{
type: "ROUTER__PUSH",
payload: {
query: { sortBy: "name" }
}
}BACK
Dispatching BACK action calls history.back
{ type: "ROUTER__BACK" }FORWARD
Dispatching Calls FORWARD action calls history.forward
{ type: "ROUTER__FORWARD" }GO
Dispatching GO action calls history.go with the number of entries from the payload
{ type: "ROUTER__GO", payload: { entries: -3 } }Example
import { createStore, applyMiddleware } from "redux";
import { createHistoryRouter } from "reduxen";
import createSagaMiddleware from "redux-saga";
import { todosReducer } from "./reducers";
import rootSaga from "./rootSaga";
const configureStore = () => {
const historyRouter = createHistoryRouter({ initialUrl });
const rootReducer = combineReducers({
todos: todosReducer
router: historyRouter.reducer
});
const sagaMiddleware = createSagaMiddleware();
const store = createStore(
rootReducer,
applyMiddleware(historyRouter.middleware, sagaMiddleware)
);
sagaMiddleware.run(rootSaga);
return store;
};
export default configureStore;import { match } from "reduxen";
import { put, call, takeLatest } from "redux-saga/effects";
import { load } from "../api/todoApi";
const handleEntered = function*(action) {
const params = match("/todos/:todoId", action.payload.path);
if (params) {
const todo = yield call(load, params.todoId);
}
};
const handleLeft = function*(action) {
if (match("/todos/:todoId", action.payload.path)) {
yield put({ type: "TODO__RESET" });
}
};
const todoRoute = function*() {
yield takeLatest("ROUTER__ENTERED", handleEntered);
yield takeLatest("ROUTER__LEFT", handleLeft);
};
export default todoRoute;