@nextrush/router 3.0.7 → 4.0.0-beta.1

package/src/__tests__/middleware-pipeline.test.ts

@@ -0,0 +1,306 @@
+/**
+ * @nextrush/router - Middleware pipeline edge cases
+ *
+ * Exercises per-route middleware (compiled by `compileExecutor`) across both
+ * calling styles — traditional `(ctx, next)` and modern `ctx.next()` — and every
+ * pipeline edge case: onion ordering, short-circuit, async ordering, error
+ * propagation, state sharing, chain sizes, mixed styles, sync throws, and the
+ * double-next() guard.
+ */
+
+import type { Context, Middleware, RouteHandler } from '@nextrush/types';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createRouter, Router } from '../router';
+
+/**
+ * Context mock whose setNext/next behave like a real adapter context:
+ * setNext stores the wired next; ctx.next() invokes it.
+ */
+function createCtx(overrides: Partial<Context> = {}): Context {
+  let stored: () => Promise<void> = () => Promise.resolve();
+  return {
+    method: 'GET',
+    path: '/',
+    params: {},
+    query: {},
+    body: undefined,
+    headers: {},
+    status: 200,
+    state: {},
+    responded: false,
+    json: vi.fn(),
+    send: vi.fn(),
+    html: vi.fn(),
+    redirect: vi.fn(),
+    set: vi.fn(),
+    get: vi.fn(),
+    setNext: (fn: () => Promise<void>) => {
+      stored = fn;
+    },
+    next: () => stored(),
+    raw: { req: {}, res: {} },
+    ...overrides,
+  } as unknown as Context;
+}
+
+const run = (router: Router, ctx: Context): Promise<void> => router.routes()(ctx, async () => {});
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+describe.each([
+  ['traditional (ctx, next)', false],
+  ['modern ctx.next()', true],
+])('per-route middleware pipeline — %s', (_label, modern) => {
+  let router: Router;
+  beforeEach(() => {
+    router = createRouter();
+  });
+
+  /** Build a middleware in the style under test that runs `before`, awaits, then `after`. */
+  const layer = (before: (ctx: Context) => void, after?: (ctx: Context) => void): Middleware =>
+    modern
+      ? (async (ctx: Context) => {
+          before(ctx);
+          await ctx.next();
+          after?.(ctx);
+        }) as Middleware
+      : (async (ctx: Context, next: () => Promise<void>) => {
+          before(ctx);
+          await next();
+          after?.(ctx);
+        }) as Middleware;
+
+  it('runs the onion model: before → handler → after (reverse)', async () => {
+    const order: string[] = [];
+    router.get(
+      '/',
+      layer(() => order.push('1-before'), () => order.push('1-after')),
+      layer(() => order.push('2-before'), () => order.push('2-after')),
+      layer(() => order.push('3-before'), () => order.push('3-after')),
+      (async () => {
+        order.push('handler');
+      }) as RouteHandler
+    );
+
+    await run(router, createCtx());
+
+    expect(order).toEqual([
+      '1-before',
+      '2-before',
+      '3-before',
+      'handler',
+      '3-after',
+      '2-after',
+      '1-after',
+    ]);
+  });
+
+  it('short-circuits: a layer that never calls next skips the rest', async () => {
+    const order: string[] = [];
+    const handler = vi.fn();
+    const stop: Middleware = modern
+      ? (async () => {
+          order.push('stop');
+        }) as Middleware
+      : (async () => {
+          order.push('stop');
+        }) as Middleware;
+
+    router.get(
+      '/',
+      layer(() => order.push('a')),
+      stop,
+      layer(() => order.push('b')),
+      handler as RouteHandler
+    );
+
+    await run(router, createCtx());
+
+    expect(order).toEqual(['a', 'stop']);
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it('preserves order across async delays', async () => {
+    const order: number[] = [];
+    const delayed = (n: number, ms: number): Middleware =>
+      modern
+        ? (async (ctx: Context) => {
+            await sleep(ms);
+            order.push(n);
+            await ctx.next();
+          }) as Middleware
+        : (async (ctx: Context, next: () => Promise<void>) => {
+            await sleep(ms);
+            order.push(n);
+            await next();
+          }) as Middleware;
+
+    router.get('/', delayed(1, 5), delayed(2, 1), delayed(3, 3), (async () => {
+      order.push(4);
+    }) as RouteHandler);
+
+    await run(router, createCtx());
+    expect(order).toEqual([1, 2, 3, 4]);
+  });
+
+  it('propagates an error thrown in a middleware and skips the handler', async () => {
+    const handler = vi.fn();
+    const boom: Middleware = (async () => {
+      throw new Error('mw boom');
+    }) as Middleware;
+
+    router.get('/', layer(() => {}), boom, handler as RouteHandler);
+
+    await expect(run(router, createCtx())).rejects.toThrow('mw boom');
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it('propagates an error thrown by the handler', async () => {
+    router.get('/', layer(() => {}), (async () => {
+      throw new Error('handler boom');
+    }) as RouteHandler);
+
+    await expect(run(router, createCtx())).rejects.toThrow('handler boom');
+  });
+
+  it('propagates a synchronous throw in a middleware', async () => {
+    const sync: Middleware = ((_ctx: Context) => {
+      throw new Error('sync boom');
+    }) as Middleware;
+
+    router.get('/', sync, (async () => {}) as RouteHandler);
+
+    await expect(run(router, createCtx())).rejects.toThrow('sync boom');
+  });
+
+  it('shares ctx.state across all layers', async () => {
+    router.get(
+      '/',
+      layer((ctx) => {
+        ctx.state.a = 1;
+      }),
+      layer((ctx) => {
+        ctx.state.b = 2;
+      }),
+      (async (ctx: Context) => {
+        ctx.state.c = 3;
+      }) as RouteHandler
+    );
+
+    const ctx = createCtx();
+    await run(router, ctx);
+    expect(ctx.state).toEqual({ a: 1, b: 2, c: 3 });
+  });
+
+  it('runs a 10-layer chain in order (general dispatch path)', async () => {
+    const order: number[] = [];
+    const layers = Array.from({ length: 10 }, (_, i) => layer(() => order.push(i + 1)));
+    router.get('/', ...layers, (async () => {
+      order.push(0);
+    }) as RouteHandler);
+
+    await run(router, createCtx());
+    expect(order).toEqual([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 0]);
+  });
+
+  it.each([1, 2, 3, 5])('runs correctly with %i middleware layer(s)', async (count) => {
+    const order: number[] = [];
+    const layers = Array.from({ length: count }, (_, i) => layer(() => order.push(i + 1)));
+    router.get('/', ...layers, (async () => {
+      order.push(0);
+    }) as RouteHandler);
+
+    await run(router, createCtx());
+    expect(order).toEqual([...Array.from({ length: count }, (_, i) => i + 1), 0]);
+  });
+});
+
+describe('per-route middleware pipeline — cross-cutting', () => {
+  let router: Router;
+  beforeEach(() => {
+    router = createRouter();
+  });
+
+  it('interleaves traditional and modern styles in one chain', async () => {
+    const order: string[] = [];
+    router.get(
+      '/',
+      (async (ctx: Context) => {
+        order.push('m1');
+        await ctx.next();
+        order.push('m1-after');
+      }) as Middleware,
+      (async (_ctx: Context, next: () => Promise<void>) => {
+        order.push('t2');
+        await next();
+        order.push('t2-after');
+      }) as Middleware,
+      (async (ctx: Context) => {
+        order.push('m3');
+        await ctx.next();
+      }) as Middleware,
+      (async () => {
+        order.push('handler');
+      }) as RouteHandler
+    );
+
+    await run(router, createCtx());
+    expect(order).toEqual(['m1', 't2', 'm3', 'handler', 't2-after', 'm1-after']);
+  });
+
+  it('rejects when the next argument is called more than once', async () => {
+    const bad: Middleware = (async (_ctx: Context, next: () => Promise<void>) => {
+      await next();
+      await next();
+    }) as Middleware;
+
+    router.get('/', bad, (async () => {}) as RouteHandler);
+
+    await expect(run(router, createCtx())).rejects.toThrow('next() called multiple times');
+  });
+
+  it('rejects double-next even after intervening layers', async () => {
+    const bad: Middleware = (async (_ctx: Context, next: () => Promise<void>) => {
+      await next();
+      await next();
+    }) as Middleware;
+
+    router.get(
+      '/',
+      bad,
+      (async (_ctx: Context, next: () => Promise<void>) => {
+        await next();
+      }) as Middleware,
+      (async () => {}) as RouteHandler
+    );
+
+    await expect(run(router, createCtx())).rejects.toThrow('next() called multiple times');
+  });
+
+  it('treats ctx.next() inside the final handler as a safe no-op', async () => {
+    let reached = false;
+    router.get(
+      '/',
+      (async (ctx: Context) => {
+        await ctx.next();
+      }) as Middleware,
+      (async (ctx: Context) => {
+        reached = true;
+        await ctx.next(); // handler calling next() must not throw or re-run anything
+      }) as RouteHandler
+    );
+
+    await expect(run(router, createCtx())).resolves.toBeUndefined();
+    expect(reached).toBe(true);
+  });
+
+  it('handler-only route: 2nd-arg next is a safe no-op', async () => {
+    let called = false;
+    router.get('/', (async (_ctx: Context, next: () => Promise<void>) => {
+      called = true;
+      await next(); // no middleware — next is NOOP
+    }) as RouteHandler);
+
+    await expect(run(router, createCtx())).resolves.toBeUndefined();
+    expect(called).toBe(true);
+  });
+});

package/src/__tests__/param-decoding.test.ts

@@ -0,0 +1,78 @@
+/**
+ * @nextrush/router - Param decoding & the `decode` option
+ *
+ * By default the router percent-decodes param and wildcard values (like Express,
+ * Koa, Hono, find-my-way). `decode: false` opts out and preserves raw values.
+ * Malformed encoding never throws — the raw value is returned.
+ */
+
+import type { RouteHandler } from '@nextrush/types';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createRouter, Router } from '../router';
+
+const h = (): RouteHandler => vi.fn();
+
+describe('param decoding — default (decode: true)', () => {
+  let router: Router;
+  beforeEach(() => {
+    router = createRouter();
+  });
+
+  it('decodes a percent-encoded space', () => {
+    router.get('/u/:name', h());
+    expect(router.match('GET', '/u/hello%20world')?.params.name).toBe('hello world');
+  });
+
+  it('decodes percent-encoded unicode', () => {
+    router.get('/u/:name', h());
+    expect(router.match('GET', '/u/jos%C3%A9')?.params.name).toBe('josé');
+  });
+
+  it('leaves an unencoded value unchanged (fast path)', () => {
+    router.get('/u/:name', h());
+    expect(router.match('GET', '/u/plain-value.txt')?.params.name).toBe('plain-value.txt');
+  });
+
+  it('decodes reserved characters like %2F inside a single param', () => {
+    router.get('/u/:name', h());
+    expect(router.match('GET', '/u/a%2Fb')?.params.name).toBe('a/b');
+  });
+
+  it('decodes the wildcard remainder', () => {
+    router.get('/s/*', h());
+    expect(router.match('GET', '/s/a%20b/c')?.params['*']).toBe('a b/c');
+  });
+
+  it('returns the raw value on malformed encoding without throwing', () => {
+    router.get('/u/:name', h());
+    expect(() => router.match('GET', '/u/%E0%A4%A')).not.toThrow();
+    expect(router.match('GET', '/u/%E0%A4%A')?.params.name).toBe('%E0%A4%A');
+  });
+
+  it('decodes params in case-insensitive mode while preserving decoded case', () => {
+    router.get('/u/:name', h());
+    expect(router.match('GET', '/u/Hello%20World')?.params.name).toBe('Hello World');
+  });
+
+  it('decodes each param independently in a multi-param route', () => {
+    router.get('/:a/:b', h());
+    expect(router.match('GET', '/a%20b/c%2Fd')?.params).toEqual({ a: 'a b', b: 'c/d' });
+  });
+});
+
+describe('param decoding — opt-out (decode: false)', () => {
+  let router: Router;
+  beforeEach(() => {
+    router = createRouter({ decode: false });
+  });
+
+  it('preserves the raw percent-encoded param value', () => {
+    router.get('/u/:name', h());
+    expect(router.match('GET', '/u/hello%20world')?.params.name).toBe('hello%20world');
+  });
+
+  it('preserves the raw wildcard remainder', () => {
+    router.get('/s/*', h());
+    expect(router.match('GET', '/s/a%20b')?.params['*']).toBe('a%20b');
+  });
+});

package/src/__tests__/public-surface.test.ts

@@ -0,0 +1,72 @@
+/**
+ * @nextrush/router - Public API surface test
+ *
+ * Locks the exported symbol set from `src/index.ts`. If this test fails, the
+ * public API has changed. Intentional changes require an explicit update to
+ * the expected list below, plus a changeset for a published package.
+ */
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import * as routerApi from '../index';
+import { NodeType } from '../index';
+import type {
+  HandlerEntry,
+  HttpMethod,
+  Middleware,
+  ParsedSegment,
+  Route,
+  RouteGroup,
+  RouteHandler,
+  RouteMatch,
+  RouterInterface,
+  RouterOptions,
+  TrieNode,
+} from '../index';
+
+describe('Public API surface (runtime exports)', () => {
+  it('exports exactly the intended runtime symbols', () => {
+    const actualExports = Object.keys(routerApi).sort();
+
+    // SEALED: intentional public runtime API surface.
+    // `createNode`/`NodeType`/`parseSegments` are internal segment-trie
+    // helpers exposed for advanced usage (see the barrel's own comment) —
+    // locked as-is here; renaming any of them is a separate breaking change.
+    // `canonicalizePath`/`hasDotSegment` are RFC-029's canonical-path surface:
+    // the single normalization owner every path-based consumer (mount-prefix
+    // matching, CSRF exclude paths, a hand-written policy guard) should call
+    // instead of re-deriving its own fold/collapse/strip.
+    const expectedRuntime = [
+      'createRouter',
+      'endpoint',
+      'Router',
+      'createNode',
+      'NodeType',
+      'parseSegments',
+      'canonicalizePath',
+      'hasDotSegment',
+    ].sort();
+
+    expect(actualExports).toEqual(expectedRuntime);
+    expect(typeof NodeType).toBe('object');
+  });
+});
+
+describe('Public API surface (type-only exports)', () => {
+  it('the type-only surface stays importable from the barrel', () => {
+    // Compile-time only: removing/renaming any of these in src/index.ts fails
+    // this file to type-check.
+    type Surface = [
+      RouteGroup,
+      HandlerEntry,
+      ParsedSegment,
+      TrieNode,
+      HttpMethod,
+      Middleware,
+      Route,
+      RouteHandler,
+      RouteMatch,
+      RouterInterface,
+      RouterOptions,
+    ];
+    expectTypeOf<Surface>().not.toBeNever();
+  });
+});

package/src/__tests__/registration-max-depth.test.ts

@@ -0,0 +1,56 @@
+/**
+ * @nextrush/router - registration-time max-depth tracking
+ *
+ * `addRoute` inserts each route's `:param`/static segments as a chain of trie
+ * nodes. The reused walk-frame pool (`reduce-router-match-allocations`) needs
+ * this chain's worst-case length known at registration time, not guessed —
+ * an attacker's request path can never make the walk descend deeper than the
+ * trie's own real depth (a mismatched segment backtracks, it never pushes),
+ * so sizing the pool from registered-route depth preserves the walk's
+ * existing recursion-depth DoS guard rather than reintroducing it.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { addRoute, type RegistrationState } from '../registration';
+import { createNode } from '../segment-trie';
+
+function createState(): RegistrationState & { maxDepth: number } {
+  return {
+    root: createNode(''),
+    caseSensitive: false,
+    staticRoutes: new Map(),
+    routeDefinitions: [],
+    maxDepth: 0,
+  };
+}
+
+const noop = async (): Promise<void> => {};
+
+describe('registration tracks the deepest registered route', () => {
+  it('a single-segment route has depth 1', () => {
+    const state = createState();
+    addRoute('GET', '/a', [noop], [], state);
+    expect(state.maxDepth).toBe(1);
+  });
+
+  it('tracks the deepest of several routes, not the last registered', () => {
+    const state = createState();
+    addRoute('GET', '/a', [noop], [], state);
+    addRoute('GET', '/a/b/c/:id', [noop], [], state);
+    addRoute('GET', '/x', [noop], [], state);
+    expect(state.maxDepth).toBe(4);
+  });
+
+  it('a wildcard segment counts toward depth but never pushes beyond it', () => {
+    const state = createState();
+    addRoute('GET', '/files/*', [noop], [], state);
+    expect(state.maxDepth).toBe(2);
+  });
+
+  it('registering a shallower route after a deeper one does not shrink maxDepth', () => {
+    const state = createState();
+    addRoute('GET', '/a/b/c', [noop], [], state);
+    addRoute('GET', '/x', [noop], [], state);
+    expect(state.maxDepth).toBe(3);
+  });
+});

package/src/__tests__/route-metadata.test.ts

@@ -0,0 +1,172 @@
+/**
+ * @nextrush/router - Route Metadata System Tests
+ *
+ * Covers endpoint() markers, the ROUTE_METADATA contribution protocol,
+ * getRoutes() introspection, contribution merge semantics, and the guarantee
+ * that pure-metadata markers never enter the executed handler chain.
+ */
+
+import type { Context, Middleware } from '@nextrush/types';
+import { ROUTE_METADATA, type MetadataContribution } from '@nextrush/types';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createRouter, endpoint, Router } from '../router';
+
+function createMockContext(overrides: Partial<Context> = {}): Context {
+  return {
+    method: 'GET',
+    path: '/',
+    params: {},
+    query: {},
+    body: undefined,
+    headers: {},
+    status: 200,
+    state: {},
+    json: vi.fn(),
+    send: vi.fn(),
+    html: vi.fn(),
+    redirect: vi.fn(),
+    set: vi.fn(),
+    get: vi.fn(),
+    next: vi.fn(),
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    raw: { req: {} as any, res: {} as any },
+    ...overrides,
+  } as Context;
+}
+
+/** Simulate a metadata-contributing middleware (like validate()): a real function carrying the symbol. */
+function contributingMiddleware(contribution: MetadataContribution): Middleware {
+  const mw: Middleware = async (ctx, next) => {
+    await next();
+  };
+  Object.defineProperty(mw, ROUTE_METADATA, { value: contribution, enumerable: false });
+  return mw;
+}
+
+describe('endpoint()', () => {
+  it('returns a marker carrying its metadata under ROUTE_METADATA', () => {
+    const marker = endpoint({ summary: 'Create user' });
+    expect(marker[ROUTE_METADATA]).toEqual({ summary: 'Create user' });
+  });
+
+  it('is not a function (never executed as middleware)', () => {
+    expect(typeof endpoint({ summary: 'x' })).not.toBe('function');
+  });
+});
+
+describe('getRoutes()', () => {
+  let router: Router;
+  beforeEach(() => {
+    router = createRouter();
+  });
+
+  it('lists every registered route (static and param) with method, path, key', () => {
+    router.get('/health', vi.fn());
+    router.get('/users/:id', vi.fn());
+    router.post('/users', vi.fn());
+
+    const routes = router.getRoutes();
+    const keys = routes.map((r) => r.key).sort();
+    expect(keys).toEqual(['GET /health', 'GET /users/:id', 'POST /users']);
+
+    const byId = routes.find((r) => r.key === 'GET /users/:id');
+    expect(byId?.method).toBe('GET');
+    expect(byId?.path).toBe('/users/:id');
+  });
+
+  it('yields a definition with no metadata for a bare route', () => {
+    router.get('/hello', vi.fn());
+    const [route] = router.getRoutes();
+    expect(route?.key).toBe('GET /hello');
+    expect(route?.metadata).toBeUndefined();
+  });
+
+  it('captures endpoint() metadata on the route', () => {
+    router.post('/users', endpoint({ summary: 'Create a user', tags: ['users'] }), vi.fn());
+    const [route] = router.getRoutes();
+    expect(route?.metadata?.summary).toBe('Create a user');
+    expect(route?.metadata?.tags).toEqual(['users']);
+  });
+
+  it('captures a contributing middleware (validate-style) request schema', () => {
+    const schema = { '~standard': { version: 1, vendor: 'test', validate: () => ({ value: {} }) } };
+    router.post('/users', contributingMiddleware({ request: { body: schema } }), vi.fn());
+    const [route] = router.getRoutes();
+    expect(route?.metadata?.request?.body).toBe(schema);
+  });
+
+  it('returns a readonly snapshot', () => {
+    router.get('/x', vi.fn());
+    const routes = router.getRoutes();
+    expect(Array.isArray(routes)).toBe(true);
+    expect(routes).toHaveLength(1);
+  });
+});
+
+describe('contribution merge semantics', () => {
+  let router: Router;
+  beforeEach(() => {
+    router = createRouter();
+  });
+
+  it('merges across contributors: request from one, responses/summary from another', () => {
+    const bodySchema = { '~standard': { version: 1, vendor: 'test', validate: () => ({ value: {} }) } };
+    const resSchema = { '~standard': { version: 1, vendor: 'test', validate: () => ({ value: {} }) } };
+    router.post('/users',
+      contributingMiddleware({ request: { body: bodySchema } }),
+      endpoint({ summary: 'Create', responses: { 201: resSchema } }),
+      vi.fn()
+    );
+    const [route] = router.getRoutes();
+    expect(route?.metadata?.request?.body).toBe(bodySchema);
+    expect(route?.metadata?.summary).toBe('Create');
+    expect(route?.metadata?.responses?.[201]).toBe(resSchema);
+  });
+
+  it('last-write-wins for scalars/arrays; per-key merge for responses map', () => {
+    const a = { '~standard': { version: 1, vendor: 't', validate: () => ({ value: {} }) } };
+    const b = { '~standard': { version: 1, vendor: 't', validate: () => ({ value: {} }) } };
+    router.get('/x',
+      endpoint({ summary: 'first', tags: ['a'], responses: { 200: a } }),
+      endpoint({ summary: 'second', tags: ['b'], responses: { 404: b } }),
+      vi.fn()
+    );
+    const [route] = router.getRoutes();
+    expect(route?.metadata?.summary).toBe('second'); // last wins
+    expect(route?.metadata?.tags).toEqual(['b']); // last wins
+    expect(route?.metadata?.responses).toEqual({ 200: a, 404: b }); // per-key merge
+  });
+});
+
+describe('markers never enter the executed chain', () => {
+  it('dispatches correctly with an endpoint() marker present', async () => {
+    const router = createRouter();
+    const handler = vi.fn();
+    router.get('/x', endpoint({ summary: 'x' }), handler);
+
+    const ctx = createMockContext({ method: 'GET', path: '/x' });
+    await router.routes()(ctx, async () => {});
+
+    // Handler ran; the marker was filtered out (a non-function marker in the
+    // chain would throw when invoked).
+    expect(handler).toHaveBeenCalledOnce();
+  });
+
+  it('still runs a contributing middleware function in the chain', async () => {
+    const router = createRouter();
+    const order: string[] = [];
+    const mw = contributingMiddleware({ summary: 'x' });
+    const wrapped: Middleware = async (ctx, next) => {
+      order.push('mw');
+      await mw(ctx, next);
+    };
+    const handler = vi.fn(() => void order.push('handler'));
+    router.get('/x', wrapped, handler);
+
+    const ctx = createMockContext({ method: 'GET', path: '/x' });
+    await router.routes()(ctx, async () => {});
+
+    expect(order).toEqual(['mw', 'handler']);
+    expect(handler).toHaveBeenCalledOnce();
+  });
+});