1 | # wayfarer [![stability][0]][1]
|
2 | [![npm version][2]][3] [![build status][4]][5] [![test coverage][6]][7]
|
3 | [![downloads][8]][9] [![js-standard-style][10]][11]
|
4 |
|
5 | Composable [trie based](https://github.com/jonathanong/routington/) router.
|
6 | It's faster than traditional, linear, regular expression-matching routers,
|
7 | although insignficantly, and scales with the number of routes.
|
8 |
|
9 | If you're looking for a client-side router check out
|
10 | [sheet-router](https://github.com/yoshuawuyts/sheet-router). If you're looking
|
11 | for a server router check out
|
12 | [server-router](https://github.com/yoshuawuyts/server-router).
|
13 |
|
14 | ### features
|
15 | - works with any framework
|
16 | - built for speed
|
17 | - minimal dependencies
|
18 | - extensible
|
19 |
|
20 | ## Installation
|
21 | ```sh
|
22 | $ npm install wayfarer
|
23 | ```
|
24 |
|
25 | ## Usage
|
26 | ```js
|
27 | const wayfarer = require('wayfarer')
|
28 |
|
29 | const router = wayfarer('/404')
|
30 |
|
31 | router.on('/', () => console.log('/'))
|
32 | router.on('/404', () => console.log('404 not found'))
|
33 | router.on('/:user', (params) => console.log('user is %s', params.user))
|
34 |
|
35 | router('tobi')
|
36 | // => 'user is tobi'
|
37 |
|
38 | router('/uh/oh')
|
39 | // => '404 not found'
|
40 | ```
|
41 |
|
42 | ## Subrouting
|
43 | Routers can be infinitely nested, allowing routing to be scoped per view.
|
44 | Matched params are passed into subrouters. Nested routes will call their
|
45 | parent's default handler if no path matches.
|
46 | ```js
|
47 | const r1 = wayfarer()
|
48 | const r2 = wayfarer()
|
49 |
|
50 | r2.on('/child', () => console.log('subrouter trix!'))
|
51 | r1.on('/:parent', r2)
|
52 |
|
53 | r1('/dada/child')
|
54 | // => 'subrouter trix!'
|
55 | ```
|
56 |
|
57 | ## API
|
58 | ### router = wayfarer(default)
|
59 | Initialize a router with a default route. Doesn't ignore querystrings and
|
60 | hashes.
|
61 |
|
62 | ### router.on(route, cb(params, [arg1, ...]))
|
63 | Register a new route. The order in which routes are registered does not matter.
|
64 | Routes can register multiple callbacks. The callback can return values when
|
65 | called.
|
66 |
|
67 | ### val = router(route, [arg1, ...])
|
68 | Match a route and execute the corresponding callback. Alias: `router.emit()`.
|
69 | Returns a values from the matched route (e.g. useful for streams). Any
|
70 | additional values will be passed to the matched route.
|
71 |
|
72 | ## Internals
|
73 | Wayfarer is built on an internal trie structure. If you want to build a router
|
74 | using this trie structure it can be accessed through
|
75 | `require('wayfarer/trie')`. It exposes the following methods:
|
76 | - `trie = Trie()` - create a new trie
|
77 | - `node = trie.create(route)` - create a node at a path, and return a node
|
78 | - `node = trie.match(route)` - match a route on the the trie and return a node
|
79 | - `trie.mount(path, trie)` - mount a trie onto a node at route
|
80 |
|
81 | ## Known issues
|
82 | ### multiple nested partials don't match
|
83 | E.g. `/:foo/:bar/:baz` won't work. This is due `Trie.mount()` overriding child
|
84 | partial paths when mounted. I'll get around to fixing this at some point in the
|
85 | future, but if anyone wants to contribute a patch it'd most appreciated.
|
86 |
|
87 | ## FAQ
|
88 | ### Why did you build this?
|
89 | Routers like [react-router](https://github.com/rackt/react-router) are
|
90 | complicated solutions for a simple problem. In reality all that's needed is a
|
91 | [methodless](http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html) router
|
92 | that can define + match paths and can mount other routers to delegate requests.
|
93 |
|
94 | ### Why isn't my route matching?
|
95 | Wayfarer only compares strings. Before you pass in an url you probably want to
|
96 | strip it of querystrings and hashes using the
|
97 | [pathname-match](https://github.com/yoshuawuyts/pathname-match) module.
|
98 |
|
99 | ## See Also
|
100 | - [sheet-router](https://github.com/yoshuawuyts/sheet-router) - fast, modular
|
101 | client-side router
|
102 | - [server-router](https://github.com/yoshuawuyts/server-router) - server router
|
103 | - [hash-match](https://github.com/sethvincent/hash-match) - easy
|
104 | `window.location.hash` matching
|
105 | - [pathname-match](https://github.com/yoshuawuyts/pathname-match) - strip
|
106 | querystrings and hashes from a url
|
107 | - [wayfarer-to-server](https://github.com/yoshuawuyts/wayfarer-to-server) -
|
108 | Wrap wayfarer to provide HTTP method matching and `req, res` delegation
|
109 |
|
110 | ## License
|
111 | [MIT](https://tldrlegal.com/license/mit-license)
|
112 |
|
113 | [0]: https://img.shields.io/badge/stability-2%20stable-brightgreen.svg?style=flat-square
|
114 | [1]: https://nodejs.org/api/documentation.html#documentation_stability_index
|
115 | [2]: https://img.shields.io/npm/v/wayfarer.svg?style=flat-square
|
116 | [3]: https://npmjs.org/package/wayfarer
|
117 | [4]: https://img.shields.io/travis/yoshuawuyts/wayfarer/master.svg?style=flat-square
|
118 | [5]: https://travis-ci.org/yoshuawuyts/wayfarer
|
119 | [6]: https://img.shields.io/codecov/c/github/yoshuawuyts/wayfarer/master.svg?style=flat-square
|
120 | [7]: https://codecov.io/github/yoshuawuyts/wayfarer
|
121 | [8]: http://img.shields.io/npm/dm/wayfarer.svg?style=flat-square
|
122 | [9]: https://npmjs.org/package/wayfarer
|
123 | [10]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square
|
124 | [11]: https://github.com/feross/standard
|
125 | [12]: http://github.com/raynos/mercury
|
126 | [13]: http://github.com/raynos/virtual-dom
|