# 🌳 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