172 lines
4.4 KiB
Markdown
172 lines
4.4 KiB
Markdown
# 🌳 radix3
|
|
|
|
[![npm version][npm-version-src]][npm-version-href]
|
|
[![npm downloads][npm-downloads-src]][npm-downloads-href]
|
|
[![bundle][bundle-src]][bundle-href]
|
|
[![Codecov][codecov-src]][codecov-href]
|
|
[![License][license-src]][license-href]
|
|
[![JSDocs][jsdocs-src]][jsdocs-href]
|
|
|
|
Lightweight and fast router for JavaScript based on [Radix Tree](https://en.wikipedia.org/wiki/Radix_tree).
|
|
|
|
## Usage
|
|
|
|
**Install package:**
|
|
|
|
```sh
|
|
# npm
|
|
npm i radix3
|
|
|
|
# yarn
|
|
yarn add radix3
|
|
|
|
# pnpm
|
|
pnpm i radix3
|
|
```
|
|
|
|
**Import:**
|
|
|
|
```js
|
|
// ESM
|
|
import { createRouter } from "radix3";
|
|
|
|
// CJS
|
|
const { createRouter } = require("radix3");
|
|
```
|
|
|
|
**Create a router instance and insert routes:**
|
|
|
|
```js
|
|
const router = createRouter(/* options */);
|
|
|
|
router.insert("/path", { payload: "this path" });
|
|
router.insert("/path/:name", { payload: "named route" });
|
|
router.insert("/path/foo/**", { payload: "wildcard route" });
|
|
router.insert("/path/foo/**:name", { payload: "named wildcard route" });
|
|
```
|
|
|
|
**Match route to access matched data:**
|
|
|
|
```js
|
|
router.lookup("/path");
|
|
// { payload: 'this path' }
|
|
|
|
router.lookup("/path/fooval");
|
|
// { payload: 'named route', params: { name: 'fooval' } }
|
|
|
|
router.lookup("/path/foo/bar/baz");
|
|
// { payload: 'wildcard route' }
|
|
|
|
router.lookup("/");
|
|
// null (no route matched for/)
|
|
```
|
|
|
|
## Methods
|
|
|
|
### `router.insert(path, data)`
|
|
|
|
`path` can be static or using `:placeholder` or `**` for wildcard paths.
|
|
|
|
The `data` object will be returned on matching params. It should be an object like `{ handler }` and not containing reserved keyword `params`.
|
|
|
|
### `router.lookup(path)`
|
|
|
|
Returns matched data for `path` with optional `params` key if mached route using placeholders.
|
|
|
|
### `router.remove(path)`
|
|
|
|
Remove route matching `path`.
|
|
|
|
## Options
|
|
|
|
You can initialize router instance with options:
|
|
|
|
```ts
|
|
const router = createRouter({
|
|
strictTrailingSlash: true,
|
|
routes: {
|
|
"/foo": {},
|
|
},
|
|
});
|
|
```
|
|
|
|
- `routes`: An object specifying initial routes to add
|
|
- `strictTrailingSlash`: By default router ignored trailing slash for matching and adding routes. When set to `true`, matching with trailing slash is different.
|
|
|
|
### Route Matcher
|
|
|
|
Creates a multi matcher from router tree that can match **all routes** matching path:
|
|
|
|
```ts
|
|
import { createRouter, toRouteMatcher } from "radix3";
|
|
|
|
const router = createRouter({
|
|
routes: {
|
|
"/foo": { m: "foo" }, // Matches /foo only
|
|
"/foo/**": { m: "foo/**" }, // Matches /foo/<any>
|
|
"/foo/bar": { m: "foo/bar" }, // Matches /foo/bar only
|
|
"/foo/bar/baz": { m: "foo/bar/baz" }, // Matches /foo/bar/baz only
|
|
"/foo/*/baz": { m: "foo/*/baz" }, // Matches /foo/<any>/baz
|
|
},
|
|
});
|
|
|
|
const matcher = toRouteMatcher(router);
|
|
|
|
const matches = matcher.matchAll("/foo/bar/baz");
|
|
|
|
// [
|
|
// {
|
|
// "m": "foo/**",
|
|
// },
|
|
// {
|
|
// "m": "foo/*/baz",
|
|
// },
|
|
// {
|
|
// "m": "foo/bar/baz",
|
|
// },
|
|
// ]
|
|
```
|
|
|
|
### Route Matcher Export
|
|
|
|
It is also possible to export and then rehydrate a matcher from pre-compiled rules.
|
|
|
|
```ts
|
|
import { exportMatcher, createMatcherFromExport } from "radix3";
|
|
|
|
// Assuming you already have a matcher
|
|
// you can export this to a JSON-type object
|
|
const json = exportMatcher(matcher);
|
|
|
|
// and then rehydrate this later
|
|
const newMatcher = createMatcherFromExport(json);
|
|
|
|
const matches = newMatcher.matchAll("/foo/bar/baz");
|
|
```
|
|
|
|
## Performance
|
|
|
|
See [benchmark](./benchmark).
|
|
|
|
## License
|
|
|
|
Based on original work of [`charlieduong94/radix-router`](https://github.com/charlieduong94/radix-router)
|
|
by [Charlie Duong](https://github.com/charlieduong94) (MIT)
|
|
|
|
[MIT](./LICENSE) - Made with ❤️
|
|
|
|
<!-- Badges -->
|
|
|
|
[npm-version-src]: https://img.shields.io/npm/v/radix3?style=flat&colorA=18181B&colorB=F0DB4F
|
|
[npm-version-href]: https://npmjs.com/package/radix3
|
|
[npm-downloads-src]: https://img.shields.io/npm/dm/radix3?style=flat&colorA=18181B&colorB=F0DB4F
|
|
[npm-downloads-href]: https://npmjs.com/package/radix3
|
|
[codecov-src]: https://img.shields.io/codecov/c/gh/unjs/radix3/main?style=flat&colorA=18181B&colorB=F0DB4F
|
|
[codecov-href]: https://codecov.io/gh/unjs/radix3
|
|
[bundle-src]: https://img.shields.io/bundlephobia/minzip/radix3?style=flat&colorA=18181B&colorB=F0DB4F
|
|
[bundle-href]: https://bundlephobia.com/result?p=radix3
|
|
[license-src]: https://img.shields.io/github/license/unjs/radix3.svg?style=flat&colorA=18181B&colorB=F0DB4F
|
|
[license-href]: https://github.com/unjs/radix3/blob/main/LICENSE
|
|
[jsdocs-src]: https://img.shields.io/badge/jsDocs.io-reference-18181B?style=flat&colorA=18181B&colorB=F0DB4F
|
|
[jsdocs-href]: https://www.jsdocs.io/package/radix3
|