sammyt / rhumb

URL routing in js

Rhumb

routing, this and that.

Bells and Whistles

• automatic path precedence
• ambiguity detection
• variables parts
• partially variable parts
• optional parts
• parameter parsing

Basic Usage

Rhumb allows you to map paths to functions

rhumb.add("/happy/shoes", function(){
  return shoes
})

If those paths contain variable parts, rhumb will grab them for you

rhumb.add("/happy/shoes/{color}", function(params){
  return shoes.inColor(params.color)
})

Whatever you return in the callback will to handed back to the caller of match

redShoes = rhumb.match("/happy/shoes/red")

Route Syntax

fixed paths

Fixed paths are the most simple

rhumb.add("/latest/potatoes")

will match /latest/potatoes only

variable parts

Use variable parts in your path to allow a range of options

rhumb.add("/potatoes/{variety}")

This route will match when anything is provided as a variety e.g.

• /potatoes/osprey
• /potatoes/saxon
• /potatoes/marabel
• /potatoes/321
• /potatoes/chips

A variety must be provided, so /potatoes alone will not match

Paths with variable parts generate a params object which is passed to the callback

rhumb.add("/potatoes/{variety}", function(params){
  console.log(params.variety)
})
rhumb.match("/potatoes/marabel")
// > "marabel"

partially variable parts

Partially variable parts allow you to capture more than one variable from a single segment of a URL.

If you wanted to capture a date in a url like /news-from/tue-march-1900 you could do so using partial parts.

rhumb.add("/news-from/{day}-{month}-{year}", function(params){
  console.log(
    params.day
  , params.month
  , params.year
  )
})

optional parts

Optional parts, well, are optional

rhumb.add("/stories(/{name})")

The above route matches for /stories and for /stories/anything

Optionals can be nested e.g.

rhumb.add("/stories(/{author}(/{genre}))")

Will match

• /stories
• /stories/bob
• /stories/sarah/scary

Have fun!

License

License: http://sammyt.mit-license.org

rhumb's Issues

Set up CI

Pretty self explanatory, but this project needs to hook up to some CI service in order to run automated tests (see #8) and potentially also publish new versions automagically on version bumps. (That latter bit being scary and possibly dangerous, so may want to reconsider.)

By far the two popular choices for OSS these days, and in particular JS projects, are Travis CI and Wercker. Of those, the latter has the interesting bonus feature of allowing you to define environments using Docker containers, which can even be used to provide a consistent local development environments (see #7.)

Roll up duplicate query parameters into lists

When something like /foo?bar=1&bar=2 is encountered, it should be rolled up into an array of values, in the order they are encountered. Probably worth looking into the rules of URI template to see what makes sense to do with empty parameters and so on. This is follow on work from #3.

Add query parameter object to callback

Currently, if you match /foo/{bar} with /foo/wibble?bar=1 the value of bar sent to the callback in the params object will be wibble, and the query parameter is lost. It makes sense for path parameters to take precedence, however we shouldn't lose information so consider adding a second callback parameter specifically for query parameters; alternatively roll up the parameters into a list as #12 says. Unclear what the way forward here is.

Automated testing

Rhumb needs to work in some set of browsers, but testing these can be a pain. To make sure things are working correctly, we need to set up automated testing across whatever set of browsers are relevant. (That's a different discussion, which doesn't much affect the core of this issue.) At minimum, this set up must work with whatever CI we set up; but ideally we'd also have the same (or at least similar) capabilities in local development.

BrowserStack and SauceLabs are popular alternatives for hosted browser testing, and both provide free plans for OSS projects. Additionally, there are plenty of tools available to make use of either of these services. @pemrouz has developed Popper, which looks mighty interesting for realtime browser testing, definitely worth looking into.

Additionally, rhumb should work in a non-browser setting, with the minimum support level being Node and should it run in things like Nashorn that's just a bonus. Thus, any tests run in a browser should work outside of a browser as well.

Consider a virtualized dev env for consistency

Virtualized dev environments are a huge boon to productivity, making almost any works-on-my-machine problem just go away by offering up a consistent development experience. Bonus points if this environment matches the delivery pipeline, such that there's very little work to go from local dev to CI to actual delivery.

The main requirements of such a setup is that it should work very well on Linux and Windows, as well as reasonably well on OSX.

To that end, there are a few options. There are others, no doubt, but here are some I can think of off hand, and as well have some experience with:

• Vagrant: mature software that works well across pretty much any platform under the sun. It's got good documentation, and a lot of community support in terms of articles and tutorials.
• Wercker: Interestingly enough, they have support for local development environments; making this a very strong contender as it's also usable as a full delivery pipeline whereas Vagrant and others focus solely on the local development.
• [Docker Compose](previously [Fig]): Let's you define and run multi-container applications. Probably a bit overkill since its main focus seem to be on composing images for actual deployment. Things like watching for changes and what not would have to be built in to the application itself, as opposed to being something the tool would do for you and consequently re-run steps. Cool tool, nonetheless.

URI template parsing

It seems the rhumb syntax is more or less compatible with URI templates, however the latter offers additional semantics such as value modifiers. These can be handy to describe how things should be parsed, but also the other way around – how things should be expanded into a new URI given input parameters. It's probably not the remit of rhumb to deal with this, since its purpose is that of pattern matching and routing, URI parsing is more of a dependency. It might be worth looking into whether the parsing/expansion can be done by something like URIt instead. (Shameless plug, I know.)

Can't find root resources

If you register the url / it will be placed in the lookup tree, however it's not possible to find. I think this is because of some early exits in find which will effectively short circuit if the segment array is empty; which it will be, since falsy values are filtered out.

It should be valid to register a handle at / -- it might be a special case, but it should be possible. The workaround for now is to add something else, I use /_ to the root resource.