Route-Value collections

route, HistoryAPI, HashChange
bower install ruta



Build Status NPM version Bower version

RouteKey-Value Collection for Browser and Node.js

Mainly used for an application routing, but can be used for any other purpose

  • strict match part(s)
    • /user (same as !/user) does not match ``` /user/bob ``
  • begins with part(s)
    • ^/user matches /user/bob, but does not /users
  • optional parts
    • /?foo Matches only / and /foo paths
  • regexp - enclosed in parentheses '(regexp)'
    • (\.less$)
    • /user/:action(edit|delete)
    • /user/:action([a-z]{2,4})
  • method
    • $post /user
  • query string (matches key/value at any position(order) in query string)
    • ?debug
    • ?debug=js
    • ?debug=(js|less) (in parenthese regexp is used, note here is also full-match is used
    • ?:debugger(d|debug)=(js|less) match d=less like debugger: 'less'

Each route definition (path) is split into parts (folders).

Each part (folder) can be

  • strict (default behaviour) /user/:name - all are strict
  • optional: /user/?:name - user is strict, but next folder with alias name is optional.
  • alias, seen from example above: /user/:name
  • alias with regexp: /user/:name(\w{3,8})
  • alias with possible values /:action(create|edit|remove)


Route-Value Collection.

  * @param route <String> : route definition
  * @param obj <Any> : value to store in collection
ruta.Collection.prototype.add(route, obj <Any>);

  * @param path <String>: url string
  * @param method <String>: optional, request method GET, POST, DELETE, PUT
  * @return route <Object> {
  *      value <Any> - stored value,
  *      current <Object> {
  *          params <Object>, - holds alias values and querystring arguments
  *          url <String>
  *      }
  * }
ruta.Collection.prototype.get(path, ?method);
import ruta from 'ruta'

const collection = new ruta.Collection();

    .add('/user/:id', {foo: 'bar'});

const route = collection.get('/user/20');

route.value === { foo: 'bar' }; === 20;


If collection is bound to a router, then each item value in the collection should be a function, which will be called, when router emits the URL-change event.

RutaJS supports History API and hashchanged routing.

⚠️ ruta object is already the route collection itself. And there is History API Router bound to this collection, or hash as a fallback;


  • .add(definition:String, mix:Any) Adds anything to the collection

    • definition String routing definition
    • mix Any Object, that you can later retrieve via .get method. When mix is a Function, then it will be additionally bound to the Router
  • .get(url:String) Gets first object from the collection matches the url

  • .getAll(url:String) Gets all objects from the collection matches the url

  • .navigate(url:String, ?options:Object) Navigate the Router to the url

    • options

      • extend:Boolean Preserve current query string parameters, which are not in url string
      • silent:Boolean Default: false; Do not trigger change event
      • replace:Boolean Default: false; For the History API replaceState is used.


var collection = new ruta.Collection();

collection.add('/user/:id', myObject);
collection.get('/user/10') // -> { key: '/user/:id', value: myObject, current: { id: 10 } }

// Will match '/foo', '/foo/bar', ...
collection.add('^/foo', x);

// Strict Pattern, match '/foo'

// Conditional

// Query String
collection.add('/users', X);
//> { key: '/users', value: X, current: { params: { loc: 'DE' }, url: '/users?loc=DE' } }

Atma.js Project