Radix3 Router

Common errors

• TypeError: createRouter is not a function

  cause Attempting to use CommonJS `require` syntax when the project or specific file is configured for ESM, or vice-versa.
  fix Ensure your import statement matches your module system. For ESM, use `import { createRouter } from 'radix3';`. For CommonJS, use `const { createRouter } = require('radix3');`.

• Route lookup for '/foo/' unexpectedly matches '/foo' when strictTrailingSlash is true.

  cause The `strictTrailingSlash` option was not correctly applied during router initialization or a new router instance was created without it.
  fix Ensure the router is initialized with `{ strictTrailingSlash: true }` when `createRouter()` is called, and that you are using this specific router instance for lookups.

• Unexpected route matching or no match for path containing characters like ':', '*', or '**'

  cause Special characters like `:` and `*` are interpreted as route parameters or wildcards by `radix3`.
  fix If these characters are part of a literal path segment and not intended as route patterns, they must be escaped using a backslash, e.g., `/api\:version` or `/files\*`.

Warnings

• breaking The `url pattern compatibility` was introduced in `v0.8.0`, potentially changing how routes are matched or defined. Review your route patterns when upgrading from `v0.7.x`.
  Fix: Consult the `radix3` documentation on 'Route Patterns' to understand the updated compatibility rules and adjust your route definitions as necessary.
• gotcha The `data` object inserted with `router.insert(path, data)` should not contain a key named `params`, as this is a reserved keyword used by the router for matched route parameters.
  Fix: Rename any `params` key within your route's `data` object to avoid conflicts, e.g., `payload.params` or `customParams`.
• gotcha By default, `radix3` ignores trailing slashes for matching and adding routes. If strict trailing slash matching is required, you must explicitly enable it.
  Fix: Initialize the router with `createRouter({ strictTrailingSlash: true })` to enable strict trailing slash behavior.
• gotcha Special characters like `:` (for named parameters) and `*` (for wildcards) in a path need to be escaped with a backslash if they are intended to be part of the literal path segment, not a special route pattern.
  Fix: Use `\:` to match a literal colon and `\*` to match a literal asterisk in your route definition paths.

Install

• npm install radix3 npm
• yarn add radix3 yarn
• pnpm add radix3 pnpm

Imports

• createRouter
  wrong:

  const createRouter = require('radix3');

  correct:

  import { createRouter } from 'radix3';

  While CommonJS `require` works, ESM `import` is the preferred modern syntax and offers better static analysis.
• toRouteMatcher
  wrong:

  import toRouteMatcher from 'radix3/matcher';

  correct:

  import { createRouter, toRouteMatcher } from 'radix3';

  All public utilities are exported from the main 'radix3' package entry point. Sub-path imports are not recommended.
• exportMatcher, createMatcherFromExport
  wrong:

  const { exportMatcher } = require('radix3').matcher;

  correct:

  import { exportMatcher, createMatcherFromExport } from 'radix3';

  Ensure you import both `exportMatcher` and `createMatcherFromExport` from the top-level package.

Quickstart

Demonstrates creating a Radix3 router, inserting various route patterns (static, named, wildcard), performing lookups, and utilizing the `toRouteMatcher` and `exportMatcher` utilities for advanced matching and persistence.

import { createRouter, toRouteMatcher, exportMatcher, createMatcherFromExport } from 'radix3';

// 1. Create a router instance and add routes
const router = createRouter({
  strictTrailingSlash: false,
  routes: {
    '/': { name: 'home' },
    '/users': { name: 'users-list' },
    '/users/:id': { name: 'user-detail' },
    '/assets/**': { name: 'static-assets' },
    '/docs/:version/**': { name: 'docs-wildcard' }
  }
});

// 2. Lookup routes
console.log('Matching /users:', router.lookup('/users'));
// Expected: { name: 'users-list' }

console.log('Matching /users/123:', router.lookup('/users/123'));
// Expected: { name: 'user-detail', params: { id: '123' } }

console.log('Matching /assets/img/logo.png:', router.lookup('/assets/img/logo.png'));
// Expected: { name: 'static-assets' }

// 3. Create a multi-matcher to find all matching routes
const matcher = toRouteMatcher(router);
const allMatches = matcher.matchAll('/docs/v1/introduction');
console.log('All matches for /docs/v1/introduction:', allMatches.map(m => m.name));
// Expected: ['docs-wildcard']

// 4. Export and rehydrate matcher for persistence/pre-compilation
const exportedMatcher = exportMatcher(matcher);
// In a real scenario, `exportedMatcher` would be serialized (e.g., to JSON) and loaded later.
const rehydratedMatcher = createMatcherFromExport(exportedMatcher);
console.log('Rehydrated matcher matching /users:', rehydratedMatcher.matchAll('/users').map(m => m.name));
// Expected: ['users-list']