rou3 Router

Common errors

• TypeError: addRoute is not a function

  cause Attempting to use `addRoute` without correctly importing it from an ESM module, likely in a CommonJS context or with incorrect import syntax.
  fix Ensure you are using `import { addRoute } from 'rou3';` in an ESM environment, or configure your bundler (like Webpack/Rollup/esbuild) to correctly handle ESM modules in a CommonJS project.

• Router does not match expected path/method combinations, returns `undefined`

  cause Common causes include paths not starting with `/`, methods not being uppercase, or incorrect URL pattern syntax, especially after v0.8.0 compatibility changes.
  fix Verify that all paths start with `/` and all methods are uppercase. Check your route patterns against the URLPattern compatibility documentation, particularly for complex regex or wildcard usage.

Warnings

• breaking Version 0.8.0 introduced significant changes to URL pattern compatibility. While aiming for URLPattern API syntax, existing complex patterns might behave differently or require adjustments.
  Fix: Review your route patterns against the new URLPattern-compatible syntax documentation. Test all existing routes thoroughly after upgrading.
• gotcha All paths added to rou3 must begin with a forward slash `/`. Paths like `users` (without a leading slash) will not be correctly registered or matched.
  Fix: Always prepend a '/' to your route paths, e.g., `/users` instead of `users`.
• gotcha HTTP methods passed to `addRoute` and `findRoute` must be in UPPERCASE. Using lowercase methods (e.g., 'get' instead of 'GET') will result in routes not being matched.
  Fix: Ensure all HTTP methods are uppercase, e.g., 'GET', 'POST', 'PUT', 'DELETE'.
• gotcha If a route pattern contains literal colons (`:`) or asterisks (`*`) that are not intended to be parameters or wildcards, they must be escaped with a backslash (`\`).
  Fix: For literal characters, use `\:` for a colon and `\*` for an asterisk. For example, `/static\:path/`.

Install

• npm install rou3 npm
• yarn add rou3 yarn
• pnpm add rou3 pnpm

Imports

• createRouter
  wrong:

  const { createRouter } = require('rou3');

  correct:

  import { createRouter } from 'rou3';

  rou3 is primarily designed for ESM environments, though CommonJS usage might be possible via bundlers.
• addRoute
  wrong:

  import addRoute from 'rou3';

  correct:

  import { addRoute } from 'rou3';

  All public API functions are named exports. There is no default export.
• findRoute

  import { findRoute } from 'rou3';

  Used to match an incoming path and method against registered routes.
• InferRouteParams

  import type { InferRouteParams } from 'rou3';

  TypeScript type for extracting route parameters, added in v0.7.6.

Quickstart

Demonstrates creating a router, adding various route patterns including parameters and wildcards, and then using `findRoute` to match incoming requests and extract associated data and parameters.

import { createRouter, addRoute, findRoute } from 'rou3';

const router = createRouter();

// Add various route types
addRoute(router, 'GET', '/users', { handler: 'listUsers' });
addRoute(router, 'POST', '/users/:id', { handler: 'createUser' });
addRoute(router, 'GET', '/posts/:category/:slug', { handler: 'viewPost' });
addRoute(router, 'GET', '/files/**:path', { handler: 'serveStatic' });

// Match routes and extract parameters
console.log('GET /users:', findRoute(router, 'GET', '/users'));
// Expected: { handler: 'listUsers' }

console.log('POST /users/123:', findRoute(router, 'POST', '/users/123'));
// Expected: { handler: 'createUser', params: { id: '123' } }

console.log('GET /posts/tech/my-article:', findRoute(router, 'GET', '/posts/tech/my-article'));
// Expected: { handler: 'viewPost', params: { category: 'tech', slug: 'my-article' } }

console.log('GET /files/images/logo.png:', findRoute(router, 'GET', '/files/images/logo.png'));
// Expected: { handler: 'serveStatic', params: { path: 'images/logo.png' } }

console.log('GET /not-found:', findRoute(router, 'GET', '/not-found'));
// Expected: undefined