# route-node

> A package to create a tree of named routes

Latest version **4.1.1** (published 2020-03-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install route-node
pnpm add route-node
yarn add route-node
bun add route-node
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.1.1 |
| Published | 2020-03-01 |
| First published | 2015-06-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 171 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 20 |
| Author | Thomas Roch |
| Maintainers | troch |
| Keywords | route tree, named route, route matching |

## Links

- npm: https://www.npmjs.com/package/route-node
- Repository: https://github.com/troch/route-node
- Issues: https://github.com/troch/route-node/issues
- npm.io page: https://npm.io/package/route-node

## Dependencies (3)

- [tslib](https://npm.io/package/tslib.md) ^1.10.0
- [path-parser](https://npm.io/package/path-parser.md) 6.1.0
- [search-params](https://npm.io/package/search-params.md) 3.0.0

## Recent versions

- 4.1.1 (latest) — 2020-03-01
- 4.1.0 — 2020-03-01
- 4.0.0 — 2020-03-01
- 3.4.2 — 2018-10-16
- 3.4.1 — 2018-10-04
- 3.4.0 — 2018-08-06
- 3.3.0 — 2018-07-11
- 3.2.1 — 2018-06-05
- 3.2.0 — 2018-05-14
- 3.1.2 — 2018-05-14
- 3.1.1 — 2018-05-01
- 3.1.0 — 2018-04-19
- 3.0.3 — 2018-04-13
- 3.0.2 — 2018-04-03
- 3.0.1 — 2018-04-03
- … 70 more at https://npm.io/package/route-node/versions

## README

[![npm version](https://badge.fury.io/js/route-node.svg)](http://badge.fury.io/js/route-node)
[![Build Status](https://travis-ci.org/troch/route-node.svg?branch=master)](https://travis-ci.org/troch/route-node)
[![Coverage Status](https://coveralls.io/repos/troch/route-node/badge.svg?branch=master)](https://coveralls.io/r/troch/route-node?branch=master)

# route-node

A package to create a tree (trie) of named routes, allowing you to build and match routes.

```sh
$ npm install route-node --save
```

## Creating your tree

To read about how to define paths, look at [path-parser README](https://www.npmjs.com/package/path-parser)

```javascript
import rootNode from 'route-node'

// Create nodes
const usersNode = new RouteNode('users', '/users', [
  new RouteNode('list', '/list'),
  new RouteNode('view', '/view/:id')
])

// You can also use plain objects
const ordersNode = new RouteNode('orders', '/orders', [
  { name: 'pending', path: '/pending' },
  { name: 'completed', path: '/completed' },
  { name: 'view', path: '/view/:id' }
])

// Creating a top root node
const rootNode = new RouteNode('', '', [ordersNode, usersNode])

// Add nodes programmatically
rootNode.add(new RouteNode('home', '/home'))
```

**`/` paths (empty paths)**

When using a deeply nested `/` path, it will automatically be matched when its parent is matched.

```js
const tree = new RouteNode('', '', [
  new RouteNode('admin', '/admin', [
    new RouteNode('home', '/'),
    new RouteNode('users', '/users')
  ])
])

tree.matchPath('/admin') // => { name: 'admin.home', params: {} }
tree.buildPath('admin.home', {}, { trailingSlashMode: 'never' }) // => '/admin'
```

**Options**

```js
const node = new RouteNode('admin', '/admin', [], options)
```

Where options can contain:

- `onAdd`: a callback called when adding routes (with contructor or `.add`), you can pass a callback which will be executed for each route added successfully to the tree.
- `parent`: the node parent
- `finalSort`: to sort children (matching order) after having added all children routes (rather than on each add)
- `sort`: whether to sort on each add or not (default to true, overriden by `finalSort`)

## Building and matching routes

**node.buildPath(routeName: string, params?: object, options?: BuildOptions): string**

```javascript
rootNode.buildPath('users.view', { id: 1 }) // => "/users/view/1"
```

**Performance**

Node children need to be sorted for matching purposes. By default this operation happens after having added all routes.

**matchPath(path: string, options?: MatchOptions): RouteNodeState | null**

```js
rootNode.matchPath('/users/view/1')
// => {name: "users.view", params: {id: "1"}}
```

## Options

Options available:

- `'urlParamsEncoding`, to specify how URL parameters are encoded and decoded:
  - `'default'`: `encodeURIComponent` and `decodeURIComponent` are used but some characters to encode and decode URL parameters, but some characters are preserved when encoding (sub-delimiters:`+`,`:`,`'`,`!`,`,`,`;`,`*`).
  - `'uriComponent'`: use `encodeURIComponent` and `decodeURIComponent`
    for encoding and decoding URL parameters.
  - `'uri'`: use `encodeURI` and `decodeURI for encoding amd decoding
    URL parameters.
  - `'none'`: no encoding or decoding is performed
  - `'legacy'`: the approach for version 5.x and below (not recommended)
- `trailingSlashMode`:
  - `'default'`: building follows path definitions
  - `'never'`: when building, trailing slash is removed
  - `'always'`: when building, trailing slash is added
- `queryParamsMode`:
  - `'default'`: a path will match with any query parameters added, but when building, extra parameters won't appear in the returned path.
  - `'strict'`: a path with query parameters which were not listed in node definition will cause a match to be unsuccessful. When building, extra parameters won't appear in the returned path.
  - `'loose'`: a path will match with any query parameters added, and when building, extra parameters will appear in the returned path.
- `queryParams`: [options for query parameters](https://github.com/troch/search-params#options)
- `caseSensitive`: whether path matching is case sensitive or not (default to `false`)

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