@c9up/ream 0.1.31 → 0.1.33

package/src/http/Response.ts

@@ -11,6 +11,7 @@ import { readFileSync } from 'node:fs'
 import { basename } from 'node:path'
 import etag from 'etag'
 import { contentType } from 'mime-types'
+import { durationToSeconds } from '../helpers/duration.js'
 import type { CookieSigner } from '../security/CookieSigner.js'
 import { Macroable } from '../utils/Macroable.js'
 import { E_HTTP_REQUEST_ABORTED } from './Exception.js'
@@ -36,6 +37,28 @@ function assertNoCRLF(name: string, value: string): void {
   }
 }
 
+/**
+ * Build a `Content-Disposition` value for a download (RFC 6266).
+ *
+ * The filename sits in a quoted-string, so a `"` inside it would close the
+ * field early and the rest would be read as further parameters. Backslash and
+ * quote are escaped, which is what a quoted-string allows.
+ *
+ * A non-ASCII name cannot go in that field at all — the header is Latin-1 — so
+ * it also gets `filename*=UTF-8''…`, and the plain `filename=` keeps an ASCII
+ * approximation for clients that ignore the extended form. Without it an
+ * accented name reached the browser as mojibake, or was dropped.
+ */
+function contentDisposition(disposition: string, filename: string): string {
+  const quoted = filename.replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: matching control
+  // characters is the point — they cannot travel in a header field.
+  const ascii = quoted.replace(/[^\x20-\x7e]/g, '_')
+  const base = `${disposition}; filename="${ascii}"`
+  if (ascii === quoted) return base
+  return `${base}; filename*=UTF-8''${encodeURIComponent(filename)}`
+}
+
 /**
  * JSON.stringify with AdonisJS-parity safety: `BigInt` values are emitted as
  * strings (native `JSON.stringify` throws on them) and circular references are
@@ -54,19 +77,68 @@ function safeStringify(value: unknown): string {
   })
 }
 
+/**
+ * Pack a cookie value the way AdonisJS does: a JSON envelope, base64url.
+ *
+ * The envelope is what carries the TYPE — without it every cookie comes back a
+ * string, and `plainCookie('count', 3)` would read as `"3"` next request.
+ */
+function packCookieValue(value: unknown): string {
+  return Buffer.from(JSON.stringify({ message: value }), 'utf8').toString('base64url')
+}
+
+/**
+ * Unpack a value written by {@link packCookieValue}.
+ *
+ * Anything that is not one of our envelopes comes back untouched — a cookie set
+ * by something else, or written with `encode: false`, is still readable.
+ */
+export function unpackCookieValue(raw: string): unknown {
+  try {
+    const decoded = Buffer.from(raw, 'base64url').toString('utf8')
+    const parsed: unknown = JSON.parse(decoded)
+    if (typeof parsed === 'object' && parsed !== null && 'message' in parsed) {
+      return (parsed as { message: unknown }).message
+    }
+    return raw
+  } catch {
+    return raw
+  }
+}
+
 export interface CookieOptions {
-  maxAge?: number
+  /**
+   * Cookie lifetime. A NUMBER is seconds; a STRING is parsed the way Adonis
+   * parses it (`'2 hours'`, `'30 mins'`, `'7 days'`, `'2h'`…), including its
+   * rule that a unitless string is milliseconds — see `helpers/duration.ts`.
+   */
+  maxAge?: number | string
   path?: string
   httpOnly?: boolean
   secure?: boolean
-  sameSite?: 'lax' | 'strict' | 'none'
+  /**
+   * `false` omits the attribute entirely (AdonisJS accepts the boolean form);
+   * `true` is not a valid attribute value and is rejected.
+   */
+  sameSite?: boolean | 'lax' | 'strict' | 'none'
+  /** Domain the cookie is valid for — what makes it readable across subdomains. */
+  domain?: string
+  /** Absolute expiry, or a function returning one (AdonisJS `expires`). */
+  expires?: Date | (() => Date)
+  /** CHIPS partitioned cookie: keyed to the top-level site as well as the domain. */
+  partitioned?: boolean
+  /** Eviction priority hint (Chromium). */
+  priority?: 'low' | 'medium' | 'high'
 }
 
 export class Response extends Macroable {
   #status = 200
+  /** A body still being drained by {@link stream}; awaited by {@link settle}. */
+  #pendingStream: Promise<void> | undefined
   #headers: Record<string, string> = {}
   #cookies: string[] = []
   #body = ''
+  readonly #finishCallbacks: Array<(err: Error | null) => void> = []
   #finished = false
   #redirectBuilderFactory?: () => RedirectBuilder
   #streamBackend?: StreamBackend
@@ -572,6 +644,19 @@ export class Response extends Macroable {
     throw new E_HTTP_REQUEST_ABORTED(body, status)
   }
 
+  /**
+   * Abort unless `condition` is truthy (AdonisJS `abortUnless`) — the guard
+   * clause form: `response.abortUnless(user, 'Not found', 404)` narrows `user`
+   * for everything after it.
+   */
+  abortUnless<T>(
+    condition: T,
+    body: unknown,
+    status = 400,
+  ): asserts condition is Exclude<T, undefined | null | false> {
+    if (!condition) this.abort(body, status)
+  }
+
   /** Abort only when `condition` is truthy (AdonisJS `abortIf`). */
   abortIf(
     condition: unknown,
@@ -581,6 +666,17 @@ export class Response extends Macroable {
     if (condition) this.abort(body, status)
   }
 
+  /**
+   * @internal Wait for a body still being produced (see {@link stream}). The
+   * kernel calls this before serializing; everything else resolves at once.
+   */
+  async settle(): Promise<void> {
+    const pending = this.#pendingStream
+    if (pending === undefined) return
+    this.#pendingStream = undefined
+    await pending
+  }
+
   /**
    * Send a file to the client (AdonisJS `download`) — reads the file, infers the
    * content-type from its extension, and sends it as a binary body. On a read
@@ -620,10 +716,86 @@ export class Response extends Macroable {
     generateEtag = false,
   ): void {
     const filename = name ?? basename(filePath)
-    this.header('Content-Disposition', `${disposition}; filename="${filename}"`)
+    this.header('Content-Disposition', contentDisposition(disposition, filename))
     this.download(filePath, generateEtag)
   }
 
+  /**
+   * Run `callback` once the response has been sent (AdonisJS `onFinish`).
+   *
+   * Where a temp file gets deleted, a timer stopped, a metric recorded — work
+   * that must not delay the reply but must still happen. Callbacks run after
+   * the body is handed to the server; one that throws is reported and does not
+   * stop the others, since by then the client already has its answer.
+   *
+   * NAMED DEVIATION: AdonisJS hands the Node `ServerResponse` to the callback.
+   * Ream's response crosses a NAPI boundary and there is no such object, so the
+   * callback receives only the error slot.
+   */
+  onFinish(callback: (err: Error | null) => void): void {
+    this.#finishCallbacks.push(callback)
+  }
+
+  /** @internal Drain the finish callbacks. Called by HttpKernel once sent. */
+  runFinishCallbacks(err: Error | null = null): void {
+    const callbacks = this.#finishCallbacks.splice(0)
+    for (const callback of callbacks) {
+      try {
+        callback(err)
+      } catch {
+        // The client already has its answer; one failing hook must not take
+        // the others with it.
+      }
+    }
+  }
+
+  /**
+   * Send a readable stream as the response body (AdonisJS `stream`).
+   *
+   * NAMED DEVIATION: the stream is CONSUMED into the body rather than piped.
+   * Ream hands a complete response across the NAPI boundary, so there is no
+   * socket to pipe into — the same reason `download()` reads a file rather
+   * than streaming it. For a large payload, prefer `sse()`, which does stream.
+   *
+   * `errorCallback` maps a read failure to `[message, status]`, as upstream;
+   * without one, a failure answers 500 with a generic message rather than
+   * leaking the filesystem error to the client.
+   *
+   * Upstream's `stream()` returns void and a controller never awaits it, so a
+   * migrated controller does not either. The drain is therefore REGISTERED as
+   * well as returned: the kernel awaits it before serializing, and a caller
+   * that ignores the promise still sends the whole body instead of an empty
+   * one. Awaiting it keeps working.
+   */
+  stream(
+    body: NodeJS.ReadableStream,
+    errorCallback?: (error: NodeJS.ErrnoException) => [string, number?],
+  ): Promise<void> {
+    const draining = this.#drain(body, errorCallback)
+    this.#pendingStream = draining
+    return draining
+  }
+
+  async #drain(
+    body: NodeJS.ReadableStream,
+    errorCallback?: (error: NodeJS.ErrnoException) => [string, number?],
+  ): Promise<void> {
+    const chunks: Buffer[] = []
+    try {
+      for await (const chunk of body) {
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk)
+      }
+    } catch (err) {
+      const [message, status] = errorCallback
+        ? errorCallback(err as NodeJS.ErrnoException)
+        : ['Cannot process the request', 500]
+      this.status(status ?? 500)
+      this.send(message)
+      return
+    }
+    this.sendBuffer(Buffer.concat(chunks))
+  }
+
   setRedirectFactory(factory: () => RedirectBuilder): void {
     this.#redirectBuilderFactory = factory
   }
@@ -695,8 +867,13 @@ export class Response extends Macroable {
    * for values you already protect (encrypted session ids, CSRF tokens) or that
    * a client-side script must read.
    */
-  plainCookie(name: string, value: string, options?: CookieOptions): this {
-    return this.#writeCookie(name, value, options)
+  plainCookie(name: string, value: unknown, options?: CookieOptions & { encode?: boolean }): this {
+    // AdonisJS packs the value into a base64url JSON envelope, which is what
+    // lets `plainCookie('prefs', { theme: 'dark' })` round-trip as an object.
+    // `encode: false` writes the string as-is — for a value a browser script
+    // has to read, or one that is already protected (a signed CSRF token).
+    const encoded = options?.encode === false ? String(value) : packCookieValue(value)
+    return this.#writeCookie(name, encoded, options)
   }
 
   /**
@@ -718,6 +895,11 @@ export class Response extends Macroable {
     // (Chrome 80+, Firefox, Safari) silently reject the cookie otherwise, so
     // a missing Secure here turns OAuth callbacks / iframe sessions into a
     // "works in dev (localhost relaxes Secure), breaks in prod" foot-gun.
+    if (options?.sameSite === true) {
+      throw new Error(
+        `Cookie '${name}': sameSite: true is not an attribute value — use 'lax', 'strict', 'none', or false to omit it.`,
+      )
+    }
     if (options?.sameSite === 'none' && !options.secure) {
       throw new Error(
         `Cookie '${name}': SameSite=None requires Secure: true (browsers reject SameSite=None cookies without Secure).`,
@@ -726,16 +908,41 @@ export class Response extends Macroable {
     const parts = [`${encodeURIComponent(name)}=${encodeURIComponent(value)}`]
     // `maxAge: 0` is the RFC 6265 "delete-now" signal used by logout flows. A
     // truthiness check would skip it; explicit `!== undefined` covers 0 too.
-    if (options?.maxAge !== undefined) parts.push(`Max-Age=${options.maxAge}`)
+    if (options?.maxAge !== undefined) {
+      parts.push(`Max-Age=${durationToSeconds(options.maxAge, 'a cookie maxAge')}`)
+    }
     if (options?.path) {
       // `Path` is concatenated raw (encodeURIComponent would mangle `/`), so it
       // needs the same CRLF/NUL guard as header() (response-splitting).
       assertNoCRLF(`Set-Cookie path for '${name}'`, options.path)
       parts.push(`Path=${options.path}`)
     }
+    if (options?.domain) {
+      // Concatenated raw like `Path`, so it carries the same splitting guard.
+      assertNoCRLF(`Set-Cookie domain for '${name}'`, options.domain)
+      parts.push(`Domain=${options.domain}`)
+    }
+    if (options?.expires !== undefined) {
+      const at = typeof options.expires === 'function' ? options.expires() : options.expires
+      if (Number.isNaN(at.getTime())) {
+        throw new Error(`Cookie '${name}': expires is an invalid Date.`)
+      }
+      parts.push(`Expires=${at.toUTCString()}`)
+    }
     if (options?.httpOnly !== false) parts.push('HttpOnly')
     if (options?.secure) parts.push('Secure')
     if (options?.sameSite) parts.push(`SameSite=${options.sameSite}`)
+    // Partitioned only means anything on a Secure cookie, and browsers drop it
+    // otherwise — say so rather than emit an attribute that will be ignored.
+    if (options?.partitioned) {
+      if (!options.secure) {
+        throw new Error(
+          `Cookie '${name}': partitioned requires Secure: true (browsers ignore partitioned cookies without it).`,
+        )
+      }
+      parts.push('Partitioned')
+    }
+    if (options?.priority) parts.push(`Priority=${options.priority}`)
     this.#cookies.push(parts.join('; '))
     return this
   }

package/src/index.ts

@@ -11,6 +11,8 @@ import 'reflect-metadata'
 export { Application } from './Application.js'
 export { ConfigStore, configProvider, defineModuleConfig, env } from './ConfigLoader.js'
 export { Container } from './container/Container.js'
+export { ContainerResolver } from './container/ContainerResolver.js'
+export { ContextualBindingsBuilder } from './container/ContextualBindingsBuilder.js'
 export type { Binding, ServiceFactory, ServiceScope, ServiceToken } from './container/types.js'
 export { Env, EnvValidationException } from './env/Env.js'
 export { loadEnvFiles } from './env/loadEnvFiles.js'
@@ -53,6 +55,13 @@ export { type GetterFn, Macroable, type MacroFn } from './utils/Macroable.js'
 // ─── Session ────────────────────────────────────────────────
 
 export { CookieDriver as SessionCookieDriver } from './session/drivers/CookieDriver.js'
+export type {
+  DatabaseDriverOptions as SessionDatabaseDriverOptions,
+  SessionDbConnection,
+} from './session/drivers/DatabaseDriver.js'
+export { DatabaseDriver as SessionDatabaseDriver } from './session/drivers/DatabaseDriver.js'
+export type { FileDriverOptions as SessionFileDriverOptions } from './session/drivers/FileDriver.js'
+export { FileDriver as SessionFileDriver } from './session/drivers/FileDriver.js'
 export { MemoryDriver as SessionMemoryDriver } from './session/drivers/MemoryDriver.js'
 export type {
   RedisSessionOptions,
@@ -60,8 +69,13 @@ export type {
   SessionRedisClientSource,
 } from './session/drivers/RedisDriver.js'
 export { RedisDriver as SessionRedisDriver } from './session/drivers/RedisDriver.js'
-export type { SessionConfig, SessionDriver } from './session/Session.js'
-export { Session } from './session/Session.js'
+export type {
+  SessionConfig,
+  SessionDriver,
+  SessionDriverWithTagging,
+  TaggedSession,
+} from './session/Session.js'
+export { Session, supportsTagging as sessionStoreSupportsTagging } from './session/Session.js'
 export { default as SessionMiddleware } from './session/SessionMiddleware.js'
 
 // ─── Body Parser ────────────────────────────────────────────
@@ -278,8 +292,8 @@ export type { EventsConfig } from './events/config.js'
 export { defineConfig as defineEventsConfig } from './events/config.js'
 export {
   BaseEvent,
-  type ContainerResolver,
   Emitter,
+  type EmitterResolver,
   type ListenerClass,
 } from './events/Emitter.js'
 export type {

package/src/router/Router.ts

@@ -4,13 +4,13 @@
  * @implements FR24, FR25, FR26, FR27, FR28
  */
 
+import { singular, snakeCase } from '../helpers/string.js'
 import type { HttpContext } from '../http/HttpContext.js'
 import { safeDecodeURIComponent } from '../http/urlDecode.js'
 import type { MiddlewareFunction } from '../middleware/Pipeline.js'
 import type { SignedUrl } from '../security/SignedUrl.js'
-import type { MiddlewareEntry } from '../server/Server.js'
+import type { LazyImport, MiddlewareClassConstructor, MiddlewareEntry } from '../server/Server.js'
 import { resolveMiddlewareEntry, resolveParametrizedMiddlewareEntry } from '../server/Server.js'
-import { singular, snakeCase } from '../utils/inflect.js'
 import { Macroable } from '../utils/Macroable.js'
 
 /** Options for {@link Router.makeSignedUrl}. */
@@ -31,9 +31,15 @@ export type RouteHandlerFunction = (ctx: HttpContext) => Promise<void> | void
  * Controller tuple: [ControllerClass, 'methodName'].
  * Constructor params are resolved by the IoC container, not by TypeScript —
  * same pattern as AdonisJS (@poppinss/utils Constructor type).
+ *
+ * `never[]` rather than `any[]`: parameters are contravariant, so a rest of
+ * `never` accepts EVERY concrete parameter list. The claim that this needed
+ * `any` was simply untrue.
  */
-// biome-ignore lint/suspicious/noExplicitAny: required — TypeScript contravariance makes it impossible to type "any constructor" without `any`
-export type ControllerAction = [target: new (...args: any[]) => any, method: string]
+export type ControllerAction = [target: AnyConstructor, method: string]
+
+/** Any class, whatever its constructor takes. */
+export type AnyConstructor = new (...args: never[]) => unknown
 
 /** Any controller class (derived from {@link ControllerAction} — no fresh `any`). */
 export type ControllerConstructor = ControllerAction[0]
@@ -58,8 +64,7 @@ export interface RouteDefinition {
   method: string
   path: string
   handler: RouteHandlerFunction | null
-  // biome-ignore lint/suspicious/noExplicitAny: see ControllerAction
-  controller?: { target: new (...args: any[]) => any; method: string }
+  controller?: { target: AnyConstructor; method: string }
   middleware: string[]
   inlineMiddleware: MiddlewareFunction[]
   guards: string[]
@@ -144,9 +149,18 @@ function makeDefinition(method: string, path: string, handler: RouteHandler): Ro
   return def
 }
 
+/**
+ * Matched route parameters.
+ *
+ * A named `:param` is a string; the catch-all `*` is the ARRAY of segments it
+ * swallowed, as AdonisJS hands it (`@poppinss/matchit`, and the route types it
+ * generates say `'*': ParamValue[]`).
+ */
+export type MatchedParams = Record<string, string | string[]>
+
 export interface MatchResult {
   route: RouteDefinition
-  params: Record<string, string>
+  params: MatchedParams
 }
 
 // ─── Matchers ───────────────────────────────────────────────
@@ -648,15 +662,25 @@ export class OnRouteBuilder {
     this.#path = path
   }
 
-  /** Render a view (requires Photon/view provider). */
+  /**
+   * Render a template with no handler of your own (AdonisJS brisk `render`).
+   *
+   * Reads the request's `ctx.view` — the per-request renderer the template
+   * provider installs. It used to look only in `ctx.store` under `view`, which
+   * nothing has ever populated, so this route always threw; the message even
+   * named the wrong package. `ctx.store` is still honoured for a host that
+   * seeds its own engine there.
+   */
   render(view: string, data?: Record<string, unknown>): RouteBuilder {
     return this.#router.get(this.#path, async (ctx) => {
-      const raw = ctx.store.get('view')
-      if (!isViewEngine(raw)) {
-        throw new Error('View engine not configured. Register a view provider (Photon) first.')
+      const candidate = Reflect.get(Object(ctx), 'view') ?? ctx.store.get('view')
+      if (!isViewEngine(candidate)) {
+        throw new Error(
+          `[E_NO_VIEW_ENGINE] router.on('${this.#path}').render('${view}') needs a template engine. ` +
+            'Register one (its provider installs `ctx.view`), or seed `ctx.store` with a `view` that has a render() method.',
+        )
       }
-      const viewEngine = raw
-      const html = await viewEngine.render(view, data)
+      const html = await candidate.render(view, data)
       ctx.response.type('text/html; charset=utf-8').send(html)
     })
   }
@@ -709,9 +733,16 @@ export class Router extends Macroable {
 
   /**
    * Register router-level middleware (runs on requests with a matched route).
-   *   router.use([() => import('#middleware/auth_middleware')])
+   *
+   *     router.use([() => import('#middleware/auth_middleware')])
+   *
+   * Imports of middleware CLASSES only, as in AdonisJS — its `use()` runs
+   * `moduleImporter(one, 'handle')` over every entry, so a closure has no
+   * place here. An inline function goes on the route or group instead
+   * (`router.get(...).use(fn)`), which is also what removes the ambiguity
+   * between a zero-arity closure and an import factory.
    */
-  use(middleware: MiddlewareEntry[]): this {
+  use(middleware: LazyImport<MiddlewareClassConstructor>[]): this {
     for (const mw of middleware) {
       this.#routerMiddleware.push(resolveMiddlewareEntry(mw))
     }
@@ -980,8 +1011,22 @@ export class Router extends Macroable {
         }
         route.lazyController = { loader, method: route.stringRef.method }
       }
-      // Named route index
+      // Named route index. A duplicate name is refused, as AdonisJS does:
+      // `urlFor(name)` can only mean one route, and silently keeping the last
+      // one makes every link built from that name point somewhere unintended.
       if (route.name) {
+        const existing = this.#nameIndex.get(route.name)
+        // Same name on the same PATH is one logical route split across verbs —
+        // `route(['PUT','PATCH'], …)` and `resource()`'s `update` both do it,
+        // and AdonisJS models those as a single route object. Only a name
+        // reused for a DIFFERENT path is the ambiguity worth refusing.
+        if (existing && existing.path !== route.path) {
+          throw new Error(
+            `[E_DUPLICATE_ROUTE_NAME] A route with name "${route.name}" already exists ` +
+              `(${existing.method} ${existing.path}); ${route.method} ${route.path} reuses it. ` +
+              `It may happen when two routes share a controller — give each an explicit name.`,
+          )
+        }
         this.#nameIndex.set(route.name, route)
       }
 
@@ -990,6 +1035,14 @@ export class Router extends Macroable {
       if (!isParam && !route.domain) {
         // Static route — O(1) exact match
         const key = route.method === '*' ? `*:${route.path}` : `${route.method}:${route.path}`
+        // Refused rather than overwritten, as AdonisJS does. A silent overwrite
+        // is how an authenticated endpoint gets shadowed by a later, unguarded
+        // one that happens to share its path — with nothing in the logs.
+        if (this.#staticIndex.has(key)) {
+          throw new Error(
+            `[E_DUPLICATE_ROUTE] Duplicate route found. "${route.method}: ${route.path}" route already exists.`,
+          )
+        }
         this.#staticIndex.set(key, route)
       } else {
         // Parametric route — indexed by method
@@ -1038,8 +1091,19 @@ export class Router extends Macroable {
         const params = matchPath(route.path, candidatePath)
         if (params === null) continue
 
-        if (!this.#validateMatchers(params, route.matchers)) continue
-        if (!this.#validateMatchers(params, this.#globalMatchers)) continue
+        // A route's own matcher REPLACES the global one for that param, as
+        // AdonisJS merges them (`{ ...global, ...local }`). Applying both as
+        // separate gates meant the global always had the final say, so a route
+        // could never loosen it — a global `id: /^[0-9]+$/` plus a route-level
+        // slug matcher 404'd instead of matching.
+        if (
+          !this.#validateMatchers(params, {
+            ...this.#globalMatchers,
+            ...route.matchers,
+          })
+        ) {
+          continue
+        }
 
         return { route, params }
       }
@@ -1231,19 +1295,21 @@ export class Router extends Macroable {
     return makeDefinition(method, path, handler)
   }
 
-  #validateMatchers(
-    params: Record<string, string>,
-    matcherMap: Record<string, ParamMatcher>,
-  ): boolean {
+  #validateMatchers(params: MatchedParams, matcherMap: Record<string, ParamMatcher>): boolean {
     for (const [param, value] of Object.entries(params)) {
       const matcher = matcherMap[param]
       if (!matcher) continue
+      // The wildcard holds several segments; every one has to satisfy the
+      // matcher, or a `/assets/*` guard would pass on its first segment alone.
+      const values = Array.isArray(value) ? value : [value]
       const regex = matcher instanceof RegExp ? matcher : matcher.pattern
       // A user-supplied /g or /y regex is stateful (`lastIndex` advances on
       // match) — without a reset, the same URL alternates match/no-match
       // across requests. Reset before every test.
-      if (regex.global || regex.sticky) regex.lastIndex = 0
-      if (!regex.test(value)) return false
+      for (const single of values) {
+        if (regex.global || regex.sticky) regex.lastIndex = 0
+        if (!regex.test(single)) return false
+      }
     }
     return true
   }
@@ -1252,7 +1318,7 @@ export class Router extends Macroable {
 // ─── Path matching ──────────────────────────────────────────
 
 /** Match path pattern against actual path, extracting params. Returns null on no match. */
-function matchPath(pattern: string, actual: string): Record<string, string> | null {
+function matchPath(pattern: string, actual: string): MatchedParams | null {
   const patternParts = pattern.split('/')
   const actualParts = actual.split('/')
 
@@ -1263,7 +1329,7 @@ function matchPath(pattern: string, actual: string): Record<string, string> | nu
   if (wildcardIdx !== -1) {
     if (wildcardIdx !== patternParts.length - 1) return null
     if (actualParts.length < wildcardIdx + 1) return null
-    const params: Record<string, string> = {}
+    const params: MatchedParams = {}
     for (let i = 0; i < wildcardIdx; i++) {
       const part = patternParts[i]
       if (part.startsWith(':')) {
@@ -1272,12 +1338,11 @@ function matchPath(pattern: string, actual: string): Record<string, string> | nu
         return null
       }
     }
-    // Decode per segment, then rejoin — an encoded `/` inside a segment stays
-    // a value character, the path structure was already split on raw `/`.
-    params['*'] = actualParts
-      .slice(wildcardIdx)
-      .map((s) => safeDecodeURIComponent(s))
-      .join('/')
+    // An ARRAY of segments, as AdonisJS hands it (`@poppinss/matchit` does
+    // `out['*'] = segs.slice(i).map(decode)`, and the generated route types say
+    // `'*': ParamValue[]`). Joining them lost the boundary between a segment
+    // containing an encoded `/` and a real path separator.
+    params['*'] = actualParts.slice(wildcardIdx).map((s) => safeDecodeURIComponent(s))
     return params
   }
 
@@ -1287,7 +1352,7 @@ function matchPath(pattern: string, actual: string): Record<string, string> | nu
 
   if (actualParts.length < requiredCount || actualParts.length > maxCount) return null
 
-  const params: Record<string, string> = {}
+  const params: MatchedParams = {}
 
   for (let i = 0; i < patternParts.length; i++) {
     const part = patternParts[i]