# @keleran/routing

> Routing utilities for Node.js projects

Latest version **4.0.0** (published 2023-05-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install @keleran/routing
pnpm add @keleran/routing
yarn add @keleran/routing
bun add @keleran/routing
```

## Health

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

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2023-05-19 |
| First published | 2018-09-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=16 |
| Dependencies | 4 |
| Unpacked size | 10 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Dmitry Chekanov |
| Maintainers | keleran |

## Links

- npm: https://www.npmjs.com/package/@keleran/routing
- Repository: https://github.com/dchekanov/routing
- Homepage: https://github.com/dchekanov/routing#readme
- Issues: https://github.com/dchekanov/routing/issues
- npm.io page: https://npm.io/package/@keleran/routing

## Dependencies (4)

- [ms](https://npm.io/package/ms.md) ^2.1.3
- [err-code](https://npm.io/package/err-code.md) ^3.0.1
- [http-errors](https://npm.io/package/http-errors.md) ^2.0.0
- [rate-limiter-flexible](https://npm.io/package/rate-limiter-flexible.md) ^2.3.6

## Recent versions

- 4.0.0 (latest) — 2023-05-19
- 3.0.0 — 2023-01-19
- 3.0.0-beta — 2022-02-14
- 2.1.2 — 2021-08-26
- 2.1.1 — 2020-09-12
- 2.1.0 — 2020-08-27
- 2.0.4 — 2020-07-23
- 2.0.3 — 2020-06-25
- 2.0.2 — 2020-06-25
- 2.0.1 — 2020-01-20
- 2.0.0 — 2019-12-23
- 1.3.3 — 2019-10-07
- 1.3.2 — 2019-10-02
- 1.3.1 — 2019-04-17
- 1.2.1 — 2018-12-04
- … 3 more at https://npm.io/package/@keleran/routing/versions

## README

# @keleran/routing

Utilities to simplify request routing in Node.js projects.  
Use ESM, require Node.js 16+.

![GitHub Workflow Status](https://img.shields.io/github/workflow/status/dchekanov/routing/Test)

## Installation

```bash
$ npm i @keleran/routing
```

```javascript
import {discover, mount} from '@keleran/routing';
```

## `discover`

Returns a flat list of route handlers found in the specified directory. 
If you don't need to work with the list before mounting, use `mount` directly - it returns the same data.

```javascript
// [{route: String, method: String, source: Object, pipeline: Array}, ...]
const handlers = await discover({dir: 'routes'});
```

## `mount`

Reads a file tree and mounts request handlers to the specified Express app.

Request handler is a file named as "HTTP_METHOD.js" (get.js, post.js, etc.) that exports an object
with the following properties:

1. "rateLimit" (optional) - a string or an object that defines rate limiting options 
for the [rate-limiter-flexible](https://github.com/animir/node-rate-limiter-flexible) library.  
The string is parsed with the [ms](https://github.com/vercel/ms) library, 
"1s" means "allow 1 request per second from this IP".  
The object is passed to rate-limiter-flexible as is. HTTP 429 will be thrown upon exceeding the limit.
2. "authorize" (optional) - an authorization function that MUST return true for request to be processed.
Otherwise it throws HTTP 403 using the [http-errors](https://github.com/jshttp/http-errors) library. 
Supplied with the "req" and "res" arguments. Can be async.
3. "middleware" (optional) - a function or an array of functions that are regular middleware 
with the "req", "res", and "next" arguments supplied.
4. "handle" - the main function that handles the request. Supplied with the "req" and "res" arguments. Can be async.

The order of execution matches the order listed above.

### Example

The following tree:

```
routes
├── =
│   └── get.js
└── route
    ├── get.js
    └── =param-name
        └── get.js
``` 

With the call:

```javascript
await mount({dir: 'routes', app, route: '/test'});
```
 
Will be mounted like this (notice the order and param/wildcard substitution):
 
```javascript
app.get('/test/route', /* handler defined in routes/route/get.js */);
app.get('/test/route/:paramName', /* handler defined in routes/route/=param-name/get.js */);
app.get('/test/*', /* handler defined in routes/=/get.js */);
```

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