route-core is a routing engine for framework authors and adapter maintainers. It matches HTTP methods and pathnames, returns decoded params plus the registered route template, and leaves handler ownership to your framework.

Use it when you want a router core that is:

• Fast on its own hot path
• Small and zero-runtime-dependency
• Explicit about framework boundaries: route-core matches routes, your framework owns handlers, middleware, and request lifecycle

Do not treat it as a complete HTTP dispatcher. It does not parse requests, own response flow, run middleware, or store handlers directly.

There are two ways to use it:

• Standard usage: pass method and path directly on each lookup
• High-throughput usage: prepare reusable handles so your adapter does less work per request

Most users should start with standard usage. Only switch to the high-throughput path when your adapter is already performance-sensitive and you understand where the extra cost is coming from.

• Install
• Before You Choose It
• Choose a Usage Style
• Current Performance Snapshot
• Quick Start
• Supported Route Patterns
• High-Throughput Quick Start
• API Reference
  • createRouter(options?)
  • RouterOptions
  • router.add(method, path, storeId)
  • router.find(method, path)
  • router.lookup(method, path, onMatch)
  • router.allowed(path)
  • router.prepareMethod(method)
  • router.preparePathname(path)
  • router.findPrepared(method, pathname)
  • router.lookupPrepared(method, pathname, onMatch)
  • router.allowedPrepared(pathname)
• 404 vs 405
• Route Syntax
  • URL and Parameter Normalization
  • Priority
  • ANY Method
• Framework Integration
• Using route-core in a vext-like Adapter
• TypeScript
• Error Reference
• Changelog
• License

npm install route-core

route-core is a good fit when:

• You are building a framework, adapter, gateway, or internal platform router
• You want storeId -> store ownership in your own layer
• You want routePath back for metrics tags such as req.route
• You already have a request object and only need route matching

It is usually not the right fit when:

• You want an off-the-shelf web framework router with handlers attached directly
• You expect built-in middleware orchestration or HTTP response helpers
• You need a drop-in replacement for a library whose public API includes handler registration and default-route callbacks

Start with standard usage when:

• Your integration still receives raw method strings and raw paths
• Clarity matters more than squeezing out the last bit of adapter overhead
• You want the simplest migration path

Switch to high-throughput usage when:

• You call the router from an internal adapter hot path
• You can reuse a prepared method handle across many requests
• You already have a normalized pathname, or can normalize it once and reuse it

Both styles return the same routing result. The high-throughput path only exists to remove repeated prep work from very hot adapter code.

Short version first:

• If you want the easiest integration, choose standard usage.
• If you picked route-core mainly for speed, choose high-throughput usage.
• The clearest lead over find-my-way on this machine comes from the high-throughput path.

Latest local benchmark run on this project workspace, using npm run bench:hot and npm run bench:compat on May 29, 2026:

lookup()-style dispatch, which is usually the most relevant adapter metric:

Direct result-returning lookups:

How to read this:

• Standard usage is the easier API surface, but it is not the mode where route-core always wins across every scenario.
• High-throughput usage is the performance-first mode. That is the mode to benchmark if speed is your main decision point.
• On the current build, the hot path is the mode that leads find-my-way most consistently in these local benchmarks.
• Mixed-segment and regex-constrained routes are now covered by dedicated benchmarks too, but today they are primarily about route expressiveness, not about beating find-my-way on raw throughput.

To verify on your own machine:

npm run bench:compat
npm run bench:hot

Treat these numbers as a current snapshot, not a universal promise. Your Node version, CPU, and route mix will change the exact ratios.

CommonJS:

const { createRouter } = require('route-core')

ES modules:

import { createRouter } from 'route-core'

Basic usage:

const { createRouter } = require('route-core')

const router = createRouter()

router.add('GET', '/users', 0)
router.add('GET', '/users/:id', 1)
router.add('POST', '/users', 2)

console.log(router.find('GET', '/users'))
// { storeId: 0, params: null, routePath: '/users' }

console.log(router.find('GET', '/users/42'))
// { storeId: 1, params: { id: '42' }, routePath: '/users/:id' }

console.log(router.allowed('/users'))
// ['GET', 'POST']

Use lookup() when your adapter prefers callback-style dispatch without allocating a MatchResult wrapper:

router.lookup('GET', '/users/42', (storeId, params, routePath) => {
  console.log(storeId)   // 1
  console.log(params)    // { id: '42' }
  console.log(routePath) // '/users/:id'
})

What this example shows in practice:

• route-core only stores numeric storeId
• your framework maps storeId back to handlers or middleware chains
• routePath comes back on hit, so you do not need a second route-template lookup

The router currently supports these route shapes:

• exact static routes such as /users
• named params such as /users/:id
• mixed params inside one segment such as /assets/:name.:ext
• multiple params inside one segment such as /near/:lat-:lng
• segment-level regex params such as /reports/:id(^\\d+)
• trailing optional params such as /optional/:id?
• fixed-count trailing multi-segment params such as /files/*2:path
• trailing wildcards such as /assets/*file
• bare wildcard *
• ANY as a method fallback bucket

Current limits:

• regex constraints only apply inside a single segment param
• optional params must be the final segment
• optional params must occupy the whole final segment
• fixed-count multi-segment params must be the final segment
• wildcard segments must be the final segment
• adjacent params inside one segment require a literal separator, so :left:right is invalid
• routes must start with /, unless the whole route is the bare wildcard *
• empty segments such as /users//profile are invalid
• normalized route shapes must be unique, so /users/:id conflicts with /users/:name
• wildcard segments in the middle of the path and full-path regex routes are not supported

Complete example:

const { createRouter } = require('route-core')

const router = createRouter()

router.add('GET', '/users', 0)
router.add('GET', '/users/:id', 1)
router.add('GET', '/assets/:name.:ext', 2)
router.add('GET', '/near/:lat-:lng', 3)
router.add('GET', '/reports/:id(^\\d+).json', 4)
router.add('GET', '/optional/:id?', 5)
router.add('GET', '/optional', 6)
router.add('GET', '/files/*2:path', 7)
router.add('GET', '/assets/*file', 8)
router.add('ANY', '/health', 9)
router.add('GET', '*', 10)

console.log(router.find('GET', '/users'))
// { storeId: 0, params: null, routePath: '/users' }

console.log(router.find('GET', '/users/42'))
// { storeId: 1, params: { id: '42' }, routePath: '/users/:id' }

console.log(router.find('GET', '/assets/app.js'))
// { storeId: 2, params: { name: 'app', ext: 'js' }, routePath: '/assets/:name.:ext' }

console.log(router.find('GET', '/near/12.3-45.6'))
// { storeId: 3, params: { lat: '12.3', lng: '45.6' }, routePath: '/near/:lat-:lng' }

console.log(router.find('GET', '/reports/123.json'))
// { storeId: 4, params: { id: '123' }, routePath: '/reports/:id(^\\d+).json' }

console.log(router.find('GET', '/optional'))
// { storeId: 6, params: null, routePath: '/optional' }

console.log(router.find('GET', '/optional/42'))
// { storeId: 5, params: { id: '42' }, routePath: '/optional/:id?' }

console.log(router.find('GET', '/files/a/b'))
// { storeId: 7, params: { path: 'a/b' }, routePath: '/files/*2:path' }

console.log(router.find('GET', '/files/a'))
// null

console.log(router.find('GET', '/assets/js/app.js'))
// { storeId: 8, params: { file: 'js/app.js' }, routePath: '/assets/*file' }

console.log(router.find('POST', '/health'))
// { storeId: 9, params: null, routePath: '/health' }

console.log(router.find('GET', '/anything-else'))
// { storeId: 10, params: { wildcard: 'anything-else' }, routePath: '*' }

Examples of unsupported route shapes:

router.add('GET', 'users', 0)               // invalid: must start with /
router.add('GET', '/users/*file/edit', 1)   // invalid: wildcard must be final
router.add('GET', '/users/:id?/tail', 2)    // invalid: optional param must be final
router.add('GET', '/users/*0:path', 3)      // invalid: fixed multi-segment count must be positive
router.add('GET', '/users/:id?.json', 4)    // invalid: optional param must occupy the full final segment
router.add('GET', '/users/:left:right', 5)  // invalid: adjacent params need a literal separator
router.add('GET', '/users/:id([)', 6)       // invalid: malformed regex constraint

Priority rules:

• static routes win over mixed or regex-constrained segment routes
• mixed or regex-constrained segment routes win over plain param routes
• plain param routes win over wildcard routes
• concrete methods win over ANY
• an explicit static route wins over the omitted branch of a trailing optional route

For example:

const router = createRouter()

router.add('GET', '/users/profile', 0)
router.add('GET', '/users/:id', 1)
router.add('GET', '/users/*rest', 2)

console.log(router.find('GET', '/users/profile'))
// { storeId: 0, params: null, routePath: '/users/profile' }

console.log(router.find('GET', '/users/42'))
// { storeId: 1, params: { id: '42' }, routePath: '/users/:id' }

console.log(router.find('GET', '/users/a/b'))
// { storeId: 2, params: { rest: 'a/b' }, routePath: '/users/*rest' }

If your adapter already has a normalized pathname, prefer the prepared hot path:

import { createRouter } from 'route-core'

const router = createRouter()
router.add('GET', '/users/:id', 1)

const GET = router.prepareMethod('GET')

console.log(GET.find('/users/42'))
// { storeId: 1, params: { id: '42' }, routePath: '/users/:id' }

GET.lookup('/users/42', (storeId, params, routePath) => {
  console.log(storeId)   // 1
  console.log(params)    // { id: '42' }
  console.log(routePath) // '/users/:id'
})

If your adapter still receives raw paths, you can normalize once and reuse the prepared value:

const preparedPath = router.preparePathname('/Users/42?from=app')
if (preparedPath) {
  console.log(router.findPrepared(GET, preparedPath))
}

In v0.0.7 and later, strings returned by preparePathname() are recognized by the same router instance as already prepared. That lets prepared method dispatch avoid repeating raw pathname normalization, while direct raw string calls still keep the compatibility behavior.

Prepared method handles stay live across later add() calls. When the route table changes, route-core rebinds the prepared handle to the latest compiled runtime on the next lookup.

For adapter authors, the common pattern is:

1. Prepare the method once during bootstrap
2. Normalize the request pathname once per request
3. Use lookupPrepared() or method.lookup() for the thinnest dispatch path
4. Resolve storeId in your own store table

The API names behind these two styles are:

• Standard usage: add, find, lookup, allowed
• High-throughput usage: prepareMethod, preparePathname, findPrepared, lookupPrepared, allowedPrepared

Creates and returns a new Router instance.

function createRouter(options?: RouterOptions): Router

Registers a route.

router.add(method: string, path: string, storeId: number): void

Errors:

Returns MatchResult on hit, or null on miss or invalid parameter input.

router.find(method: string, path: string): MatchResult | null

interface MatchResult {
  storeId: number
  params: Record<string, string> | null
  routePath: string
}

find() returns null when:

• No route matches.
• The matched parameter value exceeds maxParamLength.
• URL decoding fails for a matched parameter or wildcard value.

Looks up a route and calls the callback directly on hit. This is intended for adapter integrations that prefer callback-style dispatch.

router.lookup(
  method: string,
  path: string,
  onMatch: (storeId: number, params: Record<string, string> | null, routePath: string) => void,
): boolean

lookup() follows the same matching semantics as find(), but avoids returning a MatchResult object.

Returns the registered methods for a path so you can distinguish 404 Not Found from 405 Method Not Allowed.

router.allowed(path: string): string[] | null

Call allowed() only after find() returns null.

Prepares a reusable hot-path method handle.

router.prepareMethod(method: string): PreparedMethod

interface PreparedMethod {
  name: string
  find(pathname: PreparedPathname): MatchResult | null
  lookup(pathname: PreparedPathname, onMatch: LookupHandler): boolean
}

Use this when your adapter will perform many lookups with the same HTTP method.

Prepared method handles remain valid after later add() calls. They automatically pick up newly compiled routes on the next lookup. When you call router.findPrepared() or router.lookupPrepared(), the method handle must come from the same router instance that created it.

Normalizes a path once so it can be reused by the hot API.

router.preparePathname(path: string): PreparedPathname | null

type PreparedPathname =
  | string
  | {
      rawPathname: string
      matchPathname: string
    }

Common-case already-normalized lowercase ASCII paths usually return a plain string. Case-insensitive paths that need separate raw and match representations return the object form. The prepared APIs also accept raw string pathnames and normalize them with the same rules as find(), lookup(), and allowed(), but preparePathname() remains the preferred hot-path form when you want to reuse the normalized value.

Calls the prepared hot path directly.

router.findPrepared(method: PreparedMethod, pathname: PreparedPathname): MatchResult | null

This is equivalent to method.find(pathname). The method handle must come from the same router instance. Passing a prepared method from another router throws TypeError.

Calls the prepared hot lookup path directly.

router.lookupPrepared(
  method: PreparedMethod,
  pathname: PreparedPathname,
  onMatch: LookupHandler,
): boolean

This is equivalent to method.lookup(pathname, onMatch).

Runs allowed() against a prepared pathname.

router.allowedPrepared(pathname: PreparedPathname): string[] | null

When pathname is a raw string, route-core normalizes it with the same rules as allowed() before matching.

const { createRouter } = require('route-core')

const router = createRouter()
router.add('GET', '/users', 0)
router.add('POST', '/users', 1)

function dispatch(method, pathname, res) {
  const match = router.find(method, pathname)
  if (match) {
    return match
  }

  const methods = router.allowed(pathname)
  if (methods === null) {
    res.writeHead(404)
  } else {
    res.writeHead(405, { Allow: methods.join(', ') })
  }
}

route-core splits on the raw / delimiter before decoding parameter values, so %2F stays inside the matched segment.

Normalized route shapes are unique. For example, /users/:id conflicts with /users/:name, /assets/:name.:ext conflicts with /assets/:file.:kind, and /assets/*file conflicts with /assets/*path.

Trailing optional params are internally treated as an omitted branch plus a present branch. An explicit static route for the omitted path may coexist and wins when both match.

When multiple patterns can match the same request path, route-core uses this order:

static > pattern segment > :param > *wildcard

ANY acts as a fallback bucket. The router checks the concrete method first, then ANY.

router.add('GET', '/health', 0)
router.add('ANY', '/health', 1)

router.find('GET', '/health')
// { storeId: 0, params: null, routePath: '/health' }

router.find('DELETE', '/health')
// { storeId: 1, params: null, routePath: '/health' }

route-core is transport-agnostic. A common integration pattern is storeId -> store mapping:

import { createRouter } from 'route-core'

interface RouteStore {
  handler: (req: any, res: any) => void
  middleware: Function[]
}

const router = createRouter({ ignoreTrailingSlash: true })
const storeMap = new Map<number, RouteStore>()
let nextId = 0

function register(method: string, path: string, store: RouteStore) {
  const id = nextId++
  router.add(method, path, id)
  storeMap.set(id, store)
}

function resolve(method: string, pathname: string, res: any) {
  const match = router.find(method, pathname)
  if (match) {
    return {
      store: storeMap.get(match.storeId)!,
      params: match.params ?? {},
      route: match.routePath,
    }
  }

  const methods = router.allowed(pathname)
  if (methods) {
    res.writeHead(405, { Allow: methods.join(', ') })
  } else {
    res.writeHead(404)
  }
  return null
}

That is the intended ownership model:

• route-core owns route matching
• your framework owns handler instances, middleware chains, metadata, and fallback behavior
• allowed() is how you distinguish 404 from 405

If your framework hot path already parsed the URL, switch the example above to prepareMethod() plus preparePathname().

route-core can replace the routing core used inside a vext-style native adapter, but it is not a one-line import swap for find-my-way.

Why it is not a direct replacement:

• find-my-way registers handler + store directly on the router
• find-my-way exposes lookup(req, res) plus defaultRoute
• route-core registers storeId only and returns matches through find() or lookup()

What maps cleanly:

• route registration shape: method + path
• named params, mixed single-segment params, segment regex params, trailing optional params, trailing wildcard semantics, and fixed-count trailing multi-segment params
• ANY fallback bucket
• route-template return value for req.route

What the adapter must own:

• storeId -> store table
• 404 / 405 fallback branching
• request-object and response-object handling
• optional prepared method caching for hot methods

Minimal adapter shape:

import { createRouter } from 'route-core'

const router = createRouter()
const stores: RouteStore[] = []
const GET = router.prepareMethod('GET')

function register(method: string, path: string, store: RouteStore) {
  const storeId = stores.length
  stores.push(store)
  router.add(method, path, storeId)
}

function dispatch(methodHandle: ReturnType<typeof router.prepareMethod>, rawPath: string) {
  const preparedPath = router.preparePathname(rawPath)
  if (!preparedPath) return false

  return methodHandle.lookup(preparedPath, (storeId, params, routePath) => {
    const store = stores[storeId]!
    store.handle(params ?? {}, routePath)
  })
}

Current recommendation for vext:

• Yes, route-core is viable as the matching engine
• No, it should not be described as a drop-in replacement for the current adapter contract
• The migration unit is the adapter boundary, not a blind package swap

All public types are exported from the package root:

import { createRouter } from 'route-core'
import type {
  LookupHandler,
  MatchResult,
  PreparedMethod,
  PreparedPathname,
  Router,
  RouterOptions,
} from 'route-core'

const router: Router = createRouter({ caseSensitive: true })

const {
  RouteConflictError,
  InvalidPathError,
  InvalidMethodError,
  InvalidStoreIdError,
} = require('route-core')

• v0.0.7
• v0.0.6
• v0.0.5
• v0.0.4
• v0.0.3
• v0.0.2
• Unreleased

Apache-2.0