@c9up/ream 0.1.32 → 0.1.33

package/src/Application.ts

@@ -20,12 +20,21 @@ import { Container } from './container/Container.js'
 import type { AppContext, ProviderContract } from './Provider.js'
 import { callProviderPhase } from './Provider.js'
 
+/**
+ * How far the app intends to go in its lifecycle.
+ *
+ * `run` is a real boot. `warmup` means the app is being INSPECTED — a codegen
+ * or listing command — so it will never become ready.
+ */
+export type ApplicationMode = 'run' | 'warmup'
+
 export class Application implements AppContext {
   readonly container: Container
   readonly config: ConfigStore
   #appRoot?: URL
   private providers: ProviderContract[] = []
   private _booted = false
+  #mode: ApplicationMode = 'run'
   private _bootingHooks: Array<() => Promise<void> | void> = []
   private _bootedHooks: Array<() => Promise<void> | void> = []
   private _shutdownHooks: Array<() => Promise<void> | void> = []
@@ -35,6 +44,36 @@ export class Application implements AppContext {
     this.config = new ConfigStore()
   }
 
+  /**
+   * The current mode (AdonisJS `getMode`).
+   *
+   * A provider reads it to skip its SIDE EFFECTS — starting queue workers,
+   * opening a connection — when the app is only being inspected. It must never
+   * change which bindings are registered: the app being inspected has to match
+   * the app that runs, or the generated types describe something else.
+   *
+   *   async start() {
+   *     if (this.app.getMode() !== 'run') return
+   *     await startQueueWorkers()
+   *   }
+   */
+  getMode(): ApplicationMode {
+    return this.#mode
+  }
+
+  /**
+   * Switch the mode (AdonisJS `setMode`). Only before boot — afterwards the
+   * side effects a provider skipped have already been skipped, and pretending
+   * otherwise would leave the app half-started.
+   */
+  setMode(mode: ApplicationMode): this {
+    if (this._booted) {
+      throw new Error(`Cannot switch to '${mode}' mode: the application is already booted.`)
+    }
+    this.#mode = mode
+    return this
+  }
+
   // ─── Paths ────────────────────────────────────────────────
   // AdonisJS-style path helpers — resolve against the project root passed to
   // the Ignitor (`new Ignitor(new URL('../', import.meta.url))`). App code uses

package/src/ErrorBoundary.ts

@@ -142,7 +142,15 @@ export class ErrorBoundary {
       process.stderr.write(`[ErrorBoundary] Failed to emit: ${JSON.stringify(event)}\n`)
     }
 
-    if (this.devMode) {
+    // A fatal always reaches stderr, dev or not.
+    //
+    // Installing this boundary REPLACES Node's own handling of an unhandled
+    // rejection, which prints the reason and exits. An app that registered no
+    // error listener would otherwise swallow every one of them silently — the
+    // boundary would turn each forgotten `await` from a loud crash into
+    // nothing at all, which is the opposite of what it is for. A duplicated
+    // line when a listener also logs it is a much smaller price.
+    if (this.devMode || event.type === 'system.fatal') {
       const prefix =
         event.type === 'system.fatal'
           ? '✗ FATAL'
@@ -152,6 +160,10 @@ export class ErrorBoundary {
               ? '⚠ SECURITY'
               : '✗ SERVICE'
       process.stderr.write(`${prefix} [${event.source}] ${event.message}\n`)
+      // The stack is the only part that says WHERE the rejection came from.
+      if (event.type === 'system.fatal' && event.originalError !== undefined) {
+        process.stderr.write(`${event.originalError}\n`)
+      }
     }
   }
 }

package/src/HttpKernel.ts

@@ -20,7 +20,7 @@ import type {
   RuntimeValidator,
 } from './middleware/Pipeline.js'
 import { compose } from './middleware/Pipeline.js'
-import type { RouteDefinition, Router } from './router/Router.js'
+import type { AnyConstructor, RouteDefinition, Router } from './router/Router.js'
 import type { CookieSigner } from './security/CookieSigner.js'
 import type { SignedUrl } from './security/SignedUrl.js'
 import type { Dict } from './types/helpers.js'
@@ -41,6 +41,14 @@ export interface HttpKernelConfig {
    * SSE path with a clean error — used by mock servers in unit tests.
    */
   streamBackend?: () => import('./http/SseStream.js').StreamBackend | undefined
+  /**
+   * Honour a `_method` form field on POST (AdonisJS `http.allowMethodSpoofing`).
+   *
+   * OFF by default, as upstream. An HTML form cannot send PUT or DELETE, so an
+   * app that relies on the workaround has to say so — otherwise any POST body
+   * could rewrite itself into a DELETE.
+   */
+  allowMethodSpoofing?: boolean
 }
 
 export interface HttpKernelResponse {
@@ -152,17 +160,22 @@ export function createHttpKernel(
         }
       : { pattern: '', middleware: [] }
 
-    // 4. Create HttpContext. Pass the app container as the per-request
-    //    `ctx.containerResolver` (Adonis idiom) so agnostic middleware
-    //    (Warden, Blackhole) resolve host services from the context they are
-    //    handed instead of importing `@c9up/ream/services/app` at runtime.
-    const ctx = new HttpContext(
-      correlationId,
-      reqData,
-      match?.params ?? {},
-      routeInfo,
-      config.container,
-    )
+    // 4. Create HttpContext with its OWN resolver (Adonis
+    //    `container.createResolver()`), so agnostic middleware (Warden,
+    //    Blackhole) resolve host services from the context they are handed
+    //    instead of importing `@c9up/ream/services/app` at runtime — and so a
+    //    value bound for this request cannot be seen by any other.
+    const resolver = config.container?.createResolver()
+    const ctx = new HttpContext(correlationId, reqData, match?.params ?? {}, routeInfo, resolver)
+    // What Adonis binds on every request's resolver: the context itself, so a
+    // controller or service can take `HttpContext` as a constructor dependency.
+    resolver?.bindValue(HttpContext, ctx)
+    if (config.allowMethodSpoofing === true) {
+      // Was never wired: the setter existed but nothing called it, so a
+      // migrated config asking for spoofing got a `_method` field that did
+      // nothing at all.
+      ctx.request.setMethodSpoofing(true)
+    }
     ctx.setRouteUrlResolver((name, params) => config.router.urlFor(name, params))
     // Inject the async-resolved APP_KEY services + base logger (resolved once).
     await resolveServices()
@@ -296,7 +309,11 @@ export function createHttpKernel(
         path: reqData.path,
         status: ctx.response.getStatus(),
       })
-      return serializeResponse(ctx)
+      const serialized = await serializeResponse(ctx)
+      // The body is built; anything registered with `response.onFinish()` runs
+      // now — after the answer is ready, before we hand it back.
+      ctx.response.runFinishCallbacks()
+      return serialized
     } catch (error) {
       // If the handler opened an SSE stream via `response.sse()` and
       // THEN threw, the reserved stream id is still on the response.
@@ -334,18 +351,24 @@ export function createHttpKernel(
         path: reqData.path,
         status: ctx.response.getStatus(),
       })
-      return serializeResponse(ctx)
+      const serialized = await serializeResponse(ctx)
+      // The body is built; anything registered with `response.onFinish()` runs
+      // now — after the answer is ready, before we hand it back.
+      ctx.response.runFinishCallbacks()
+      return serialized
     }
   }
 }
 
 function createControllerHandler(
-  // biome-ignore lint/suspicious/noExplicitAny: see ControllerAction type — IoC resolves constructor params
-  controller: { target: new (...args: any[]) => any; method: string },
+  controller: { target: AnyConstructor; method: string },
   container?: Container,
 ): (ctx: HttpContext) => Promise<void> {
   return async (ctx: HttpContext) => {
-    const instance = container ? await container.make(controller.target) : new controller.target()
+    // Through the REQUEST resolver when there is one: a controller taking
+    // `HttpContext` as a dependency must get this request's, not a stale one.
+    const resolve = ctx.containerResolver ?? container
+    const instance = resolve ? await resolve.make(controller.target) : new controller.target()
     const method = (instance as Record<string, (ctx: HttpContext) => Promise<void> | void>)[
       controller.method
     ]
@@ -363,7 +386,7 @@ function createControllerHandler(
  * Returns empty arrays if no decorators are present.
  */
 function readControllerGuardMetadata(
-  target: new (...args: unknown[]) => unknown,
+  target: AnyConstructor,
   method: string,
 ): { guards: string[]; roles: string[]; permissions: string[] } {
   try {
@@ -379,7 +402,10 @@ function readControllerGuardMetadata(
   }
 }
 
-function serializeResponse(ctx: HttpContext): HttpKernelResponse {
+async function serializeResponse(ctx: HttpContext): Promise<HttpKernelResponse> {
+  // A body still being drained by `response.stream()` — upstream returns void
+  // there, so a migrated controller does not await it.
+  await ctx.response.settle()
   const streamId = ctx.response.getStreamId()
   return {
     status: ctx.response.getStatus(),

package/src/Ignitor.ts

@@ -29,6 +29,7 @@ import { startHotReload } from './HotReload.js'
 import type { HttpKernelRequest, HttpKernelResponse } from './HttpKernel.js'
 import { createHttpKernel } from './HttpKernel.js'
 import { ExceptionHandler } from './http/Exception.js'
+import { HttpContext } from './http/HttpContext.js'
 import type { MiddlewareFunction } from './middleware/Pipeline.js'
 import { MiddlewareRegistry } from './middleware/Pipeline.js'
 import type { AppContext, ProviderContract } from './Provider.js'
@@ -40,6 +41,7 @@ import { Server } from './server/Server.js'
 import { clearApp, setApp } from './services/app.js'
 import { clearRouter, setRouter } from './services/router.js'
 import { clearServer, setServer } from './services/server.js'
+import { registerSessionTemplateTags } from './session/templateTags.js'
 
 /** Application environment. */
 export type AppEnvironment = 'web' | 'console' | 'test' | 'unknown'
@@ -253,6 +255,12 @@ export class Ignitor {
     this.app.container.singleton('server', () => this.server)
     this.app.container.singleton('middleware', () => this.middleware)
     this.app.container.singleton('app', () => this.app)
+    // The HttpContext CLASS, so an integration provider can extend it the way
+    // AdonisJS does — `HttpContext.getter('view', …)` is how the view layer
+    // attaches `ctx.view`. Exported from the barrel too, but a provider that
+    // must stay agnostic reaches it through the container instead of importing
+    // ream at runtime.
+    this.app.container.singleton('HttpContext', () => HttpContext)
     // `appRoot` is the URL passed to `new Ignitor(new URL('../', import.meta.url))`.
     // Providers resolve it through the container so they can interpret
     // relative paths in config files (e.g. `pages.root: './resources/pages'`)
@@ -431,6 +439,30 @@ export class Ignitor {
     loadEnvFiles(this.appRoot, { skipEnvLocal: this.environment === 'test' })
   }
 
+  /**
+   * Give the template engine `@error` / `@errors` / `@inputError` /
+   * `@flashMessage`, as AdonisJS's session plugin does.
+   *
+   * The engine is duck-typed out of the container so ream carries no dependency
+   * on it, and an app with no template layer simply skips this.
+   */
+  private async registerSessionTemplateTags(): Promise<void> {
+    for (const token of ['inker', 'view']) {
+      if (!this.app.container.has(token)) continue
+      const binding: unknown = await this.app.container.resolve(token)
+      for (const candidate of [binding, Reflect.get(Object(binding), '_templates')]) {
+        const register = Reflect.get(Object(candidate), 'registerTag')
+        if (typeof register !== 'function') continue
+        registerSessionTemplateTags({
+          registerTag: (tag) => {
+            register.call(candidate, tag)
+          },
+        })
+        return
+      }
+    }
+  }
+
   private async phaseRegister(): Promise<void> {
     // Auto-load config/*.ts files into app.config
     await this.autoloadConfig()
@@ -527,6 +559,8 @@ export class Ignitor {
         onError: (error, ctx) => {
           this.errorBoundary.serviceError('HttpKernel', error, ctx.id)
         },
+        // AdonisJS `config/app.ts` → `http: { allowMethodSpoofing: true }`.
+        allowMethodSpoofing: this.app.config.get<boolean>('app.http.allowMethodSpoofing') === true,
         streamBackend: () => {
           const server = this._httpServer
           if (
@@ -601,6 +635,11 @@ export class Ignitor {
     // Install error boundary
     this.errorBoundary.install()
 
+    // Publish the flash-message tags to the template engine, if one is
+    // installed. After boot(), so the engine's own provider has bound it;
+    // before ready(), so a provider that pre-renders finds the tags in place.
+    await this.registerSessionTemplateTags()
+
     // Call ready() on providers
     for (const provider of this.providers) {
       await callProviderPhase(provider, 'ready')

package/src/bodyparser/BodyParserMiddleware.ts

@@ -9,25 +9,32 @@
 import type { HttpContext } from '../http/HttpContext.js'
 import { hydrateMultipartPayload } from './MultipartFile.js'
 import { parseSize } from './parseSize.js'
+import { parseQueryString, type QsParseOptions } from './qsParse.js'
 
 export interface BodyParserConfig {
   json?: {
-    enabled?: boolean
     limit?: string // e.g. '1mb'
     types?: string[]
   }
   form?: {
-    enabled?: boolean
     limit?: string
     types?: string[]
+    /**
+     * Turn `''` into `null`. AdonisJS defaults this to `true`, so an empty
+     * text input arrives as `null` rather than an empty string — which is what
+     * a "nullable" validation rule expects to see.
+     */
+    convertEmptyStringsToNull?: boolean
+    /** Trim surrounding whitespace. AdonisJS defaults this to `true`. */
+    trimWhitespaces?: boolean
+    /** Options for the bracket-notation parser (`depth`, `parameterLimit`). */
+    queryString?: QsParseOptions
   }
   raw?: {
-    enabled?: boolean
     limit?: string
     types?: string[]
   }
   multipart?: {
-    enabled?: boolean
     /** Total multipart body size cap (sum of all file sizes). Default: '20mb'. */
     limit?: string
     /** Maximum number of files per request. Default: 20. */
@@ -47,22 +54,24 @@ interface ResolvedBodyParserConfig {
 
 const DEFAULT_CONFIG: ResolvedBodyParserConfig = {
   json: {
-    enabled: true,
     limit: '1mb',
     types: ['application/json', 'application/vnd.api+json'],
   },
   form: {
-    enabled: true,
     limit: '1mb',
     types: ['application/x-www-form-urlencoded'],
+    // AdonisJS ships both as `true` (define_config: form.convertEmptyStringsToNull
+    // / trimWhitespaces), so a migrated form behaves the same here.
+    convertEmptyStringsToNull: true,
+    trimWhitespaces: true,
+    queryString: {},
   },
   raw: {
-    enabled: false,
+    // AdonisJS parses `text/*` out of the box (define_config: raw.types).
     limit: '1mb',
-    types: ['text/plain'],
+    types: ['text/*'],
   },
   multipart: {
-    enabled: true,
     limit: '20mb',
     maxFiles: 20,
     maxFields: 500,
@@ -75,6 +84,7 @@ export default class BodyParserMiddleware {
   #config: ResolvedBodyParserConfig
 
   constructor(config?: BodyParserConfig) {
+    assertNoEnabledFlag(config)
     this.#config = {
       json: { ...DEFAULT_CONFIG.json, ...config?.json },
       form: { ...DEFAULT_CONFIG.form, ...config?.form },
@@ -96,26 +106,32 @@ export default class BodyParserMiddleware {
     }
 
     // JSON
-    if (this.#config.json.enabled && matchesType(contentType, this.#config.json.types)) {
-      // Request already lazy-parses JSON — nothing to do
+    if (matchesType(contentType, this.#config.json.types)) {
+      // `Request` lazy-parses JSON on first read; nothing to do here.
     }
 
     // Form URL-encoded
-    if (this.#config.form.enabled && matchesType(contentType, this.#config.form.types)) {
-      ctx.request.setParsedBody(parseFormUrlEncoded(rawBody))
+    if (matchesType(contentType, this.#config.form.types)) {
+      ctx.request.setParsedBody(
+        parseQueryString(rawBody, {
+          ...this.#config.form.queryString,
+          convertEmptyStringsToNull: this.#config.form.convertEmptyStringsToNull,
+          trimWhitespaces: this.#config.form.trimWhitespaces,
+        }),
+      )
     }
 
     // Raw text — wrap the string under `_body` so consumers can still
     // reach it through `request.input('_body')`. This matches the fallback
     // shape used by `Request.#ensureParsedBody` when JSON yields a non-object.
-    if (this.#config.raw.enabled && matchesType(contentType, this.#config.raw.types)) {
+    if (matchesType(contentType, this.#config.raw.types)) {
       ctx.request.setParsedBody({ _body: rawBody })
     }
 
     // Multipart — the Rust-side HyperServer parses the body server-side
     // (multer crate) and ships the structured payload on `request.multipart`.
     // JS just hydrates `MultipartFile` instances from the typed envelope.
-    if (this.#config.multipart.enabled && matchesType(contentType, this.#config.multipart.types)) {
+    if (matchesType(contentType, this.#config.multipart.types)) {
       const payload = ctx.request.multipart()
       if (payload) {
         if (this.#rejectMultipart(ctx, payload.files, payload.fields)) return
@@ -177,38 +193,44 @@ export default class BodyParserMiddleware {
   }
 }
 
+/**
+ * Whether a request's content-type is claimed by one of `types`.
+ *
+ * AdonisJS configures wildcards (`raw.types` defaults to `text/*`), so a bare
+ * substring test would never match `text/plain` against `text/*`. Parameters
+ * are stripped first: `application/json; charset=utf-8` is a JSON body.
+ */
 function matchesType(contentType: string, types: string[]): boolean {
-  return types.some((t) => contentType.includes(t))
-}
-
-function parseFormUrlEncoded(body: string): Record<string, unknown> {
-  const result: Record<string, unknown> = {}
-  if (!body) return result
-  for (const pair of body.split('&')) {
-    if (!pair) continue
-    const eqIdx = pair.indexOf('=')
-    if (eqIdx === -1) {
-      result[decodeFormComponent(pair)] = ''
-    } else {
-      result[decodeFormComponent(pair.slice(0, eqIdx))] = decodeFormComponent(pair.slice(eqIdx + 1))
+  const actual = (contentType.split(';')[0] ?? '').trim().toLowerCase()
+  if (!actual) return false
+  return types.some((candidate) => {
+    const pattern = candidate.trim().toLowerCase()
+    if (pattern === '*/*') return true
+    if (pattern.endsWith('/*')) {
+      return actual.startsWith(`${pattern.slice(0, -1)}`)
     }
-  }
-  return result
+    return actual === pattern
+  })
 }
 
-// `application/x-www-form-urlencoded` reserves `+` for space (RFC 1866 / WHATWG
-// URL form spec), so the substitution must happen before percent-decoding —
-// otherwise a literal `+` (encoded as `%2B`) would be turned into a space too.
-//
-// Malformed percent-encoding (e.g. a truncated `a=%E0%A4%A`) makes
-// decodeURIComponent throw URIError; mirror Request.ts#safeDecode and fall back
-// to the substituted-but-undecoded value so an invalid body is a parse miss,
-// not a 500.
-function decodeFormComponent(value: string): string {
-  const spaced = value.replace(/\+/g, ' ')
-  try {
-    return decodeURIComponent(spaced)
-  } catch {
-    return spaced
+/**
+ * `enabled` was an atlas-era invention: AdonisJS has no such flag, and a parser
+ * is turned off by giving it no `types`. It also never worked for JSON, which
+ * `Request` lazy-parses on first read regardless.
+ *
+ * Silently ignoring a config key that used to mean something would re-enable a
+ * parser an app deliberately switched off, so it fails loudly with the
+ * replacement spelled out.
+ */
+function assertNoEnabledFlag(config?: BodyParserConfig): void {
+  if (!config) return
+  for (const section of ['json', 'form', 'raw', 'multipart'] as const) {
+    const value: unknown = config[section]
+    if (value !== null && typeof value === 'object' && 'enabled' in value) {
+      throw new Error(
+        `[E_BODYPARSER_CONFIG] \`${section}.enabled\` is no longer supported — AdonisJS has no such option. ` +
+          `To disable this parser, give it no types: \`${section}: { types: [] }\`.`,
+      )
+    }
   }
 }

package/src/bodyparser/qsParse.ts

@@ -0,0 +1,179 @@
+/**
+ * Bracket-notation form parsing — what AdonisJS gets from `qs`.
+ *
+ * `@adonisjs/bodyparser` runs `qs.parse(body, options.qs)` on every
+ * `application/x-www-form-urlencoded` body, so `user[name]=ada` arrives as
+ * `{ user: { name: 'ada' } }` and a repeated `tags[]` becomes an array. Parsing
+ * flat instead does not merely lose the nesting: a repeated key OVERWRITES,
+ * so a multi-select or a checkbox group silently submits only its last value.
+ *
+ * Reimplemented rather than depending on `qs` — this package ships no runtime
+ * dependency it can write in a screenful, and the limits below are easier to
+ * defend when they are visible.
+ *
+ * Three guards, all of which `qs` also applies:
+ *
+ *  - **Prototype keys are dropped.** `__proto__[x]=1` in a form body is the
+ *    classic prototype-pollution vector; the key never reaches an object.
+ *  - **Depth is capped** (`qs` defaults to 5). Beyond it the remainder is kept
+ *    as a literal key rather than allocating unbounded nesting.
+ *  - **Parameter count is capped** (`qs` defaults to 1000), so a body of a
+ *    million `a[0]`, `a[1]`… cannot be turned into a million-entry object.
+ */
+
+/** `qs` defaults, reproduced so the behaviour is the same out of the box. */
+export const DEFAULT_DEPTH = 5
+export const DEFAULT_PARAMETER_LIMIT = 1000
+
+export interface QsParseOptions {
+  /**
+   * Treat `user.name` as `user[name]`. AdonisJS forces this ON for form
+   * bodies (`queryStringOptions.allowDots ??= true`), so a dotted field name
+   * nests there and must nest here.
+   */
+  allowDots?: boolean
+  depth?: number
+  parameterLimit?: number
+  /** Turn `''` into `null`, as AdonisJS' `convertEmptyStringsToNull` does. */
+  convertEmptyStringsToNull?: boolean
+  /** Trim surrounding whitespace, as AdonisJS' `trimWhitespaces` does. */
+  trimWhitespaces?: boolean
+}
+
+/** Keys that must never be written onto an object. */
+const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
+
+/**
+ * Split `user[address][city]` into `['user', 'address', 'city']`, and
+ * `tags[]` into `['tags', '']` — an empty segment meaning "append".
+ * Segments past `depth` are folded back into one literal key, which is what
+ * `qs` does rather than erroring.
+ */
+function splitKey(key: string, depth: number, allowDots: boolean): string[] {
+  // `user.name` → `user[name]` before anything else, so both spellings take
+  // the same path. AdonisJS forces allowDots on for form bodies.
+  const key2 = allowDots && !key.startsWith('.') ? key.replace(/\.([^.[\]]+)/g, '[$1]') : key
+  const firstBracket = key2.indexOf('[')
+  if (firstBracket === -1) return [key2]
+  const root = key2.slice(0, firstBracket)
+  const segments: string[] = [root]
+  let rest = key2.slice(firstBracket)
+  while (segments.length <= depth) {
+    const match = /^\[([^\]]*)\]/.exec(rest)
+    if (!match) break
+    segments.push(match[1] ?? '')
+    rest = rest.slice(match[0].length)
+    if (rest.length === 0) return segments
+  }
+  // Anything left over (too deep, or malformed) stays literal on the last
+  // segment — no value is dropped, it is just not nested any further.
+  if (rest.length > 0) {
+    segments[segments.length - 1] = `${segments[segments.length - 1] ?? ''}${rest}`
+  }
+  return segments
+}
+
+function isIndex(segment: string): boolean {
+  return /^\d+$/.test(segment)
+}
+
+/** Assign `value` at `segments` inside `target`, creating containers as needed. */
+function assign(target: Record<string, unknown>, segments: string[], value: unknown): void {
+  let cursor: Record<string, unknown> | unknown[] = target
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i] ?? ''
+    const last = i === segments.length - 1
+
+    if (FORBIDDEN_KEYS.has(segment)) return
+
+    if (last) {
+      if (segment === '') {
+        // `tags[]` — append.
+        if (Array.isArray(cursor)) cursor.push(value)
+        return
+      }
+      if (Array.isArray(cursor)) {
+        if (isIndex(segment)) cursor[Number(segment)] = value
+        return
+      }
+      const existing = cursor[segment]
+      if (existing === undefined) {
+        cursor[segment] = value
+        return
+      }
+      // A key repeated WITHOUT brackets collects too, as `qs` does — losing
+      // the earlier value is the bug this whole file exists to fix.
+      if (Array.isArray(existing)) existing.push(value)
+      else cursor[segment] = [existing, value]
+      return
+    }
+
+    const nextSegment = segments[i + 1] ?? ''
+    const wantsArray = nextSegment === '' || isIndex(nextSegment)
+
+    if (Array.isArray(cursor)) {
+      if (!isIndex(segment)) return
+      const index = Number(segment)
+      const existing = cursor[index]
+      if (existing === undefined || typeof existing !== 'object' || existing === null) {
+        cursor[index] = wantsArray ? [] : {}
+      }
+      cursor = cursor[index] as Record<string, unknown> | unknown[]
+      continue
+    }
+
+    const existing = cursor[segment]
+    if (existing === undefined || typeof existing !== 'object' || existing === null) {
+      cursor[segment] = wantsArray ? [] : {}
+    }
+    cursor = cursor[segment] as Record<string, unknown> | unknown[]
+  }
+}
+
+/**
+ * `application/x-www-form-urlencoded` reserves `+` for space (RFC 1866 /
+ * WHATWG URL form spec), so the substitution happens BEFORE percent-decoding —
+ * otherwise a literal `+` (sent as `%2B`) would become a space too.
+ *
+ * Malformed percent-encoding makes `decodeURIComponent` throw; the
+ * substituted-but-undecoded value is kept so a bad body is a parse miss, not
+ * a 500.
+ */
+export function decodeFormComponent(value: string): string {
+  const spaced = value.replace(/\+/g, ' ')
+  try {
+    return decodeURIComponent(spaced)
+  } catch {
+    return spaced
+  }
+}
+
+/** Parse a urlencoded body into a nested object. */
+export function parseQueryString(
+  body: string,
+  options: QsParseOptions = {},
+): Record<string, unknown> {
+  const depth = options.depth ?? DEFAULT_DEPTH
+  const parameterLimit = options.parameterLimit ?? DEFAULT_PARAMETER_LIMIT
+  const result: Record<string, unknown> = {}
+  if (!body) return result
+
+  const pairs = body.split('&')
+  let seen = 0
+  for (const pair of pairs) {
+    if (!pair) continue
+    if (++seen > parameterLimit) break
+
+    const eqIdx = pair.indexOf('=')
+    const rawKey = eqIdx === -1 ? pair : pair.slice(0, eqIdx)
+    const rawValue = eqIdx === -1 ? '' : pair.slice(eqIdx + 1)
+
+    const key = decodeFormComponent(rawKey)
+    let value: unknown = decodeFormComponent(rawValue)
+    if (options.trimWhitespaces && typeof value === 'string') value = value.trim()
+    if (options.convertEmptyStringsToNull && value === '') value = null
+
+    assign(result, splitKey(key, depth, options.allowDots ?? true), value)
+  }
+  return result
+}