# ruta

> Route-Value Collections

Latest version **0.2.73** (published 2026-05-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install ruta
pnpm add ruta
yarn add ruta
bun add ruta
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.2.73 |
| Published | 2026-05-07 |
| First published | 2014-02-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 82.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1 |
| Author | Alexander Kit |
| Maintainers | tenbits |

## Links

- npm: https://www.npmjs.com/package/ruta
- Repository: https://github.com/atmajs/Ruta
- Homepage: https://github.com/atmajs/Ruta#readme
- Issues: https://github.com/atmajs/Ruta/issues
- npm.io page: https://npm.io/package/ruta

## Recent versions

- 0.2.73 (latest) — 2026-05-07
- 0.2.71 — 2021-05-02
- 0.2.70 — 2021-04-13
- 0.2.69 — 2021-01-01
- 0.2.67 — 2020-12-16
- 0.2.66 — 2020-12-16
- 0.2.65 — 2020-12-16
- 0.2.64 — 2020-10-23
- 0.2.63 — 2020-10-08
- 0.2.62 — 2020-04-30
- 0.2.59 — 2020-02-20
- 0.2.58 — 2020-02-16
- 0.2.57 — 2019-05-24
- 0.2.55 — 2018-09-10
- 0.2.53 — 2018-09-10
- … 35 more at https://npm.io/package/ruta/versions

## README

RutaJS
----

[![Build Status](https://travis-ci.org/atmajs/Ruta.png?branch=master)](https://travis-ci.org/atmajs/Ruta)
[![NPM version](https://badge.fury.io/js/ruta.svg)](http://badge.fury.io/js/ruta)
[![Bower version](https://badge.fury.io/bo/ruta.svg)](http://badge.fury.io/bo/ruta)


*Route*_Key_-Value Collection for Browser and Node.js


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

##### Route

- 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'`

##### Parts

>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) ```


### Collection

Route-Value Collection.

```javascript
/**
  * @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);

```

```ts
import ruta from 'ruta'

const collection = new ruta.Collection();

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

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

route.value === { foo: 'bar' };
route.current.params.id === 20;
```

### Router

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.


> :warning: _ruta_ object is already the route collection itself. And there is History API Router bound to this collection, or `hash` as a fallback;


### Api

- `.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.

#### Examples

```javascript

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'
collection.add('/foo')
collection.add('/foo?query=string')


// Conditional
collection.add('/user/?:id')


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

```


----
_Atma.js Project_

---
_Source: https://npm.io/package/ruta · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._