# nicely-typed-routes

> Typed routes parser with magic syntax

Latest version **0.1.8** (published 2022-08-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install nicely-typed-routes
pnpm add nicely-typed-routes
yarn add nicely-typed-routes
bun add nicely-typed-routes
```

## Health

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

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

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.8 |
| Published | 2022-08-29 |
| First published | 2021-12-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=10 |
| Dependencies | 0 |
| Unpacked size | 61.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4 |
| Author | Andrei Miroshnik |
| Maintainers | anmi |

## Links

- npm: https://www.npmjs.com/package/nicely-typed-routes
- Repository: https://github.com/anmi/nicely-typed-routes
- Homepage: https://github.com/anmi/nicely-typed-routes#readme
- Issues: https://github.com/anmi/nicely-typed-routes/issues
- npm.io page: https://npm.io/package/nicely-typed-routes

## Recent versions

- 0.1.8 (latest) — 2022-08-29
- 0.1.7 — 2021-12-18
- 0.1.5 — 2021-12-16
- 0.1.3 — 2021-12-16
- 0.1.2 — 2021-12-16
- 0.1.0 — 2021-12-16

## README

# nicely-typed-routes

Typed routes parser with magic syntax

## What's the problem?

Declaring routes and arguments types can be full of boilerplate and there is a chance intruducting typos.

For example, using `react-router`, you have to manually extract URL params and make sure they match your types. Moreover there is not autocomplete on getting parameters, generating URLs, no typechecking.

`react-router` example

```typescript
const params = new URLSearchParams(props.location.search);
const tags = params.get('tags'):
```

And still it is necessary to make sure there are no typos in `tags` parameter while generating link for example.

## Why not to use any other library?

Sure, there are tons of amazing libraries:

- https://www.npmjs.com/package/typed-route-builder
- https://www.npmjs.com/package/next-typed-routes
- https://github.com/fongandrew/typed-routes

and so on.

But they are pretty verbose and even better typing could be done using TypeScript 4 feature [Template Literal Types](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-1.html#template-literal-types).

## API

```typescript
import { route, createRoutesDeclaration } from 'nicely-typed-routes';

const categoriesRoute = route('/users/{userId:number}/categories/:category');
const productsRoute = route('/products/{productId:number}');

const routes = createRoutesDeclaration(categoriesRoute).add(productsRoute);

const parsed = routes.parse(window.location.pathname);

// First, check if url matched one of the routes
if (parsed !== null) {
  // at this moment parsed is sum type of all possible routes

  if (parsed.key === categoriesRoute.key) {
    console.log(parsed.params); // typed as { userId: number, category: string }
  }
  if (parsed.key === productsRoute.key) {
    console.log(parsed.params); // typed as { productId: number }
  }
}

// Routes also usable to generate link

categoriesRoute.link({ userId: 42, category: 'cats' }); // '/users/42/categories/cats`
categoriesRoute.link({ userId: '42', category: 'cats' }); // Typecheck failed
```

## Is it production ready?

No, but I'm looking forward to see how this library could be improved.

## Future plans

### Tier 1

- Finalize syntax specification
- Rewrite better matching algorithm
- Improve test coverage
- Improve documentation
- Search params typing

### Tier 2

- Custom types
- URLs composition, nested routes

## Downsides

- TypeScript 4 is mandatory
- Probably longer compiling time (I should run benchmarks to make sure)
- TypeScript Errors could be not as readable as you want
- Harder to inspect derived types.

## Thanks

This solution is highly inspired by [TypeScript Challenges](https://github.com/type-challenges/type-challenges).
Special thanks to [Grigorii Khromov](https://github.com/gkhromov) for helping me figure out how all of this works :).

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