@getsoda/core 0.1.0 → 0.2.0

package/dist/logger/logger.js

@@ -0,0 +1,66 @@
+/**
+ * @module
+ * The logger contract.
+ *
+ * `Logger` is both the type and the DI token: the application provides one
+ * (a `ConsoleLogger` unless told otherwise) and any class injects it.
+ *
+ * ```ts
+ * class UsersService {
+ *   readonly #logger = inject(Logger).child('UsersService')
+ *
+ *   create(user: User) {
+ *     this.#logger.log('User created', { id: user.id })
+ *   }
+ * }
+ * ```
+ *
+ * Levels are Nest's. Unlike Nest's `Logger`, it is not a static global: each
+ * application has its own, and tests replace it with `overrides`.
+ */
+/** Levels, from the most to the least verbose. */
+export const LOG_LEVELS = ['verbose', 'debug', 'log', 'warn', 'error', 'fatal'];
+/**
+ * A logger. Implementations only write entries; levels and contexts are handled here.
+ */
+export class Logger {
+    verbose(message, data) {
+        this.write({ level: 'verbose', message, data, context: undefined });
+    }
+    debug(message, data) {
+        this.write({ level: 'debug', message, data, context: undefined });
+    }
+    log(message, data) {
+        this.write({ level: 'log', message, data, context: undefined });
+    }
+    warn(message, data) {
+        this.write({ level: 'warn', message, data, context: undefined });
+    }
+    error(message, data) {
+        this.write({ level: 'error', message, data, context: undefined });
+    }
+    fatal(message, data) {
+        this.write({ level: 'fatal', message, data, context: undefined });
+    }
+    /** A logger writing through this one, with `context` on every entry. */
+    child(context) {
+        return new ContextLogger(this, context);
+    }
+}
+class ContextLogger extends Logger {
+    #parent;
+    #context;
+    constructor(parent, context) {
+        super();
+        this.#parent = parent;
+        this.#context = context;
+    }
+    write(entry) {
+        this.#parent.write({ ...entry, context: this.#context });
+    }
+}
+/** A logger that writes nothing: `createApp(AppModule, { logger: false })`. */
+export class SilentLogger extends Logger {
+    write() { }
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/logger/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,kDAAkD;AAClD,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAU,CAAA;AAkBxF;;GAEG;AACH,MAAM,OAAgB,MAAM;IAI1B,OAAO,CAAC,OAAe,EAAE,IAAc;QACrC,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAA;IACrE,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,IAAc;QACnC,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAA;IACnE,CAAC;IAED,GAAG,CAAC,OAAe,EAAE,IAAc;QACjC,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAA;IACjE,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,IAAc;QAClC,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAA;IAClE,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,IAAc;QACnC,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAA;IACnE,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,IAAc;QACnC,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAA;IACnE,CAAC;IAED,wEAAwE;IACxE,KAAK,CAAC,OAAe;QACnB,OAAO,IAAI,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;IACzC,CAAC;CACF;AAED,MAAM,aAAc,SAAQ,MAAM;IACvB,OAAO,CAAQ;IACf,QAAQ,CAAQ;IAEzB,YAAY,MAAc,EAAE,OAAe;QACzC,KAAK,EAAE,CAAA;QACP,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;QACrB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAA;IACzB,CAAC;IAED,KAAK,CAAC,KAAe;QACnB,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAA;IAC1D,CAAC;CACF;AAED,+EAA+E;AAC/E,MAAM,OAAO,YAAa,SAAQ,MAAM;IACtC,KAAK,KAAU,CAAC;CACjB"}

package/dist/routing/types.d.ts

@@ -30,7 +30,7 @@ export type Params = Record<string, string>;
  *
  * `params` may be the very object Bun put on `req.params`: treat it as read-only.
  */
-export type Handler = (req: Request, params: Params) => Response | Promise<Response>;
+export type Handler = (req: Bun.BunRequest, params: Params) => Response | Promise<Response>;
 /**
  * Route definition.
  *

package/dist/routing/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/routing/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,eAAO,MAAM,UAAU,QAAQ,CAAA;AAE/B;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,SAAU,CAAA;AAExC;;;;;;;GAOG;AACH,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAE3C;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;AAEpF;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAClE,oFAAoF;IACpF,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAClC;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,UAAU,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;AAEjF;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IAC9C,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;CAC/D"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/routing/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,eAAO,MAAM,UAAU,QAAQ,CAAA;AAE/B;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,SAAU,CAAA;AAExC;;;;;;;GAOG;AACH,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAE3C;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;AAE3F;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAClE,oFAAoF;IACpF,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAClC;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,UAAU,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;AAEjF;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IAC9C,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;CAC/D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getsoda/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Class-based web framework for Bun: modules, dependency injection and decorators like Nest, on Bun's native router",
   "keywords": [
     "bun",
@@ -28,6 +28,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./jwt": {
+      "types": "./dist/jwt/index.d.ts",
+      "default": "./dist/jwt/index.js"
+    },
     "./package.json": "./package.json"
   },
   "types": "./dist/index.d.ts",
@@ -42,16 +46,6 @@
   },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
-    "typecheck": "bun check",
-    "lint": "oxlint",
-    "lint:fix": "oxlint --fix",
-    "test": "bun test",
-    "prepublishOnly": "bun run lint && bun run typecheck && bun run test && bun run build"
-  },
-  "devDependencies": {
-    "@stylistic/eslint-plugin": "5.10.0",
-    "@types/bun": "latest",
-    "oxlint": "1.93.0",
-    "typescript": "7.0.2"
+    "prepublishOnly": "cd ../.. && bun run lint && bun run typecheck && bun run test && cd packages/core && bun run build"
   }
 }

package/src/app/app.ts

@@ -19,11 +19,14 @@
  * are being destroyed; here they cannot.
  */
 
-import { createContainer } from '../di/index.ts'
+import { createContainer, provide } from '../di/index.ts'
 import type { Container, ContainerOptions, ModuleImport } from '../di/index.ts'
 import { destroyAll, initializeAll } from '../di/lifecycle.ts'
 import { buildRoutes } from '../http/index.ts'
-import type { ControllerRoutesOptions } from '../http/index.ts'
+import type { ControllerRoutesOptions, Middleware } from '../http/index.ts'
+import { errorResponse } from '../http/exceptions.ts'
+import { applyMiddleware, resolveMiddleware } from '../http/middleware.ts'
+import { ConsoleLogger, Logger, SilentLogger } from '../logger/index.ts'
 import { compileRoutes } from '../routing/index.ts'
 import type { CompiledRoutes, CompileOptions } from '../routing/index.ts'
 import { release, takeOver } from './hot.ts'
@@ -31,7 +34,18 @@ import { release, takeOver } from './hot.ts'
 /**
  * Options of `createApp`.
  */
-export interface AppOptions extends ContainerOptions, ControllerRoutesOptions, CompileOptions {}
+export interface AppOptions extends ContainerOptions, ControllerRoutesOptions, CompileOptions {
+  /**
+   * Middleware run around every request, before routing (404 and preflights
+   * included), first one outermost: `[cors(), requestId]`.
+   */
+  readonly middleware?: readonly Middleware[]
+  /**
+   * Logger of the application, injectable everywhere as `inject(Logger)`.
+   * Defaults to a `ConsoleLogger`; `false` writes nothing.
+   */
+  readonly logger?: Logger | false
+}
 
 /**
  * Where to listen. `port: 0` picks a free port.
@@ -39,6 +53,11 @@ export interface AppOptions extends ContainerOptions, ControllerRoutesOptions, C
 export interface ListenOptions {
   readonly port?: number
   readonly hostname?: string
+  /**
+   * Largest request body accepted, in bytes; bigger ones are refused before any
+   * handler runs. Bun's default is 128 MiB.
+   */
+  readonly maxRequestBodySize?: number
 }
 
 /** Signals `enableShutdownSignals()` listens to by default. */
@@ -80,11 +99,13 @@ class Application implements App {
   #closing: Promise<void> | undefined
   readonly #enhancers: readonly unknown[]
   readonly #signals = new Map<NodeJS.Signals, () => void>()
+  readonly #logger: Logger
 
-  constructor(container: Container, routes: CompiledRoutes, enhancers: readonly unknown[]) {
+  constructor(container: Container, routes: CompiledRoutes, enhancers: readonly unknown[], logger: Logger) {
     this.container = container
     this.routes = routes
     this.#enhancers = enhancers
+    this.#logger = logger
   }
 
   get server(): Bun.Server<undefined> | undefined {
@@ -100,9 +121,9 @@ class Application implements App {
       throw new Error(`The application already listens on ${this.#server.url.href}`)
     }
 
-    const { port = 0, hostname } = typeof options === 'number' ? { port: options } : options
+    const { port = 0, hostname, maxRequestBodySize } = typeof options === 'number' ? { port: options } : options
 
-    const server = Bun.serve({ port, hostname, ...this.routes })
+    const server = Bun.serve({ port, hostname, maxRequestBodySize, ...this.routes })
 
     this.#server = server
 
@@ -110,6 +131,8 @@ class Application implements App {
       await takeOver(server.port, this)
     }
 
+    this.#logger.log(`Listening on ${server.url.href}`)
+
     return server
   }
 
@@ -151,7 +174,7 @@ class Application implements App {
             process.kill(process.pid, signal)
           },
           (error: unknown) => {
-            console.error('Error during shutdown', error)
+            this.#logger.fatal('Shutdown failed', { error })
             process.exit(1)
           }
         )
@@ -230,16 +253,34 @@ const destroyEverything = async (enhancers: readonly unknown[], container: Conta
  * error first, as `createContainer` does.
  */
 export const createApp = async (root: ModuleImport, options: AppOptions = {}): Promise<App> => {
-  const container = await createContainer(root, options)
-  let enhancers: readonly unknown[] = []
+  const logger = options.logger === false ? new SilentLogger() : (options.logger ?? new ConsoleLogger())
+  const own = logger.child('Soda')
+  const onError =
+    options.onError ??
+    ((error: unknown, req: Request) =>
+      own.error('Unhandled error while handling a request', { error, method: req.method, url: req.url }))
+  const container = await createContainer(root, {
+    ...options,
+    providers: [...(options.providers ?? []), provide(Logger, { useValue: logger })],
+  })
+  const enhancers: unknown[] = []
 
   try {
-    const built = buildRoutes(container, options)
+    // Middleware first: it wraps everything, so it is initialized first and destroyed last.
+    const middleware = resolveMiddleware(options.middleware ?? [], (fn) => container.runInContext(fn), (instance) => {
+      enhancers.push(instance)
+    })
+    const built = buildRoutes(container, { ...options, onError })
 
-    enhancers = built.enhancers
+    enhancers.push(...built.enhancers)
     await initializeAll(enhancers)
 
-    return new Application(container, compileRoutes(built.routes, options), enhancers)
+    const compiled = compileRoutes(built.routes, options)
+    const routes = applyMiddleware(middleware, compiled.routes, compiled.fetch, (error, req) =>
+      errorResponse(error, (unknown) => onError(unknown, req))
+    )
+
+    return new Application(container, routes, enhancers, own)
   } catch (error) {
     try {
       await destroyEverything(enhancers, container)

package/src/di/container.ts

@@ -19,11 +19,13 @@
 import { isThenable } from '../utils/promise.ts'
 import { runInContext } from './context.ts'
 import type { InjectionContext } from './context.ts'
-import type { ModuleClass, ModuleImport } from './decorators.ts'
+import { Module } from './decorators.ts'
+import type { DynamicModule, ModuleClass, ModuleImport } from './decorators.ts'
 import { DiError } from './errors.ts'
 import { buildGraph } from './graph.ts'
 import type { ModuleGraph, ModuleNode, ProviderNode } from './graph.ts'
 import { destroyAll, initializeAll } from './lifecycle.ts'
+import { isProviderRecord } from './provider.ts'
 import type { Provider, ProviderDefinition } from './provider.ts'
 import { tokenName } from './token.ts'
 import type { Constructor, Token } from './token.ts'
@@ -43,6 +45,25 @@ export interface ContainerOptions {
    * ```
    */
   readonly overrides?: readonly Provider[]
+  /**
+   * Providers visible in every module, as if exported by a global module:
+   * what the application itself provides, such as its `Logger`.
+   */
+  readonly providers?: readonly Provider[]
+}
+
+/** Module holding `ContainerOptions.providers`. */
+@Module({})
+class ContainerProvidersModule {}
+
+const providersModule = (providers: readonly Provider[]): DynamicModule => {
+  const exports: Token<unknown>[] = []
+
+  for (const provider of providers) {
+    exports.push(isProviderRecord(provider) ? provider.token : provider)
+  }
+
+  return { module: ContainerProvidersModule, providers, exports, global: true }
 }
 
 /**
@@ -524,7 +545,8 @@ const createAll = async (graph: ModuleGraph, resolver: Resolver): Promise<Contro
  * hooks fail too, everything is rethrown as one `AggregateError`, startup error first.
  */
 export const createContainer = async (root: ModuleImport, options: ContainerOptions = {}): Promise<Container> => {
-  const graph = await buildGraph(root, options.overrides ?? [])
+  const providers = options.providers ?? []
+  const graph = await buildGraph(root, options.overrides ?? [], providers.length > 0 ? [providersModule(providers)] : [])
   const resolver = new Resolver(graph)
 
   try {

package/src/di/graph.ts

@@ -139,7 +139,17 @@ class GraphBuilder {
     }
   }
 
-  async build(root: ModuleImport): Promise<ModuleGraph> {
+  /**
+   * `globals` are global modules added next to `root` (the container's own
+   * providers); they are created first, before anything that may inject them.
+   */
+  async build(root: ModuleImport, globals: readonly ModuleImport[]): Promise<ModuleGraph> {
+    const globalNodes: ModuleNode[] = []
+
+    for (let i = 0, len = globals.length; i < len; i++) {
+      globalNodes.push(await this.#module(globals[i], 'createContainer()', i))
+    }
+
     const rootNode = await this.#module(root, 'createContainer()', 0)
 
     // The queue grows while modules are read: breadth-first over imports.
@@ -149,8 +159,8 @@ class GraphBuilder {
 
     this.#assertReplacementsUsed()
 
-    const modules = orderModules(rootNode)
-    const globals: ModuleNode[] = []
+    const modules = orderModules([...globalNodes, rootNode])
+    const globalModules: ModuleNode[] = []
     const providers: ProviderNode[] = []
     const controllers: ProviderNode[] = []
 
@@ -160,14 +170,14 @@ class GraphBuilder {
       assertExportsProvided(node)
 
       if (node.global) {
-        globals.push(node)
+        globalModules.push(node)
       }
 
       providers.push(...node.providers.values())
       controllers.push(...node.controllers)
     }
 
-    return { root: rootNode, modules, globals, providers, controllers }
+    return { root: rootNode, modules, globals: globalModules, providers, controllers }
   }
 
   /** Node for an `imports` entry, created on first sight. */
@@ -320,8 +330,8 @@ const assertExportsProvided = (node: ModuleNode): void => {
   }
 }
 
-/** Modules reachable from `root`, each after the modules it imports. */
-const orderModules = (root: ModuleNode): ModuleNode[] => {
+/** Modules reachable from `roots`, each after the modules it imports. */
+const orderModules = (roots: readonly ModuleNode[]): ModuleNode[] => {
   const ordered: ModuleNode[] = []
   const visited = new Set<ModuleNode>()
 
@@ -339,15 +349,20 @@ const orderModules = (root: ModuleNode): ModuleNode[] => {
     ordered.push(node)
   }
 
-  visit(root)
+  for (const root of roots) {
+    visit(root)
+  }
 
   return ordered
 }
 
 /**
- * Builds the module graph rooted at `root`.
+ * Builds the module graph rooted at `root`, with `globals` as extra global modules.
  *
  * `overrides` replace the provider of their token in every module providing it (for tests).
  */
-export const buildGraph = (root: ModuleImport, overrides: readonly Provider[]): Promise<ModuleGraph> =>
-  new GraphBuilder(overrides).build(root)
+export const buildGraph = (
+  root: ModuleImport,
+  overrides: readonly Provider[],
+  globals: readonly ModuleImport[] = []
+): Promise<ModuleGraph> => new GraphBuilder(overrides).build(root, globals)

package/src/http/arguments.ts

@@ -16,18 +16,21 @@
  * called by the framework before the method instead of by the method itself.
  */
 
+import type { FormFields, FormLimits } from './body.ts'
+import type { ContextKey } from './context-key.ts'
 import type { Context, ParamNameOf } from './context.ts'
 import type { Parsed, ValueParser } from './parsers.ts'
+import { isStandardSchema } from './schema.ts'
 import type { InferOutput, StandardSchemaV1 } from './schema.ts'
 
-export type ArgumentKind = 'param' | 'query' | 'header' | 'body' | 'context'
+export type ArgumentKind = 'param' | 'query' | 'header' | 'cookie' | 'body' | 'context' | 'value'
 
 /**
  * One argument of a handler: where it comes from and how it is read.
  */
 export interface Argument<T, K extends ArgumentKind = ArgumentKind, N extends string = string> {
   readonly kind: K
-  /** Parameter, query or header name; empty for `body` and `context`. */
+  /** Parameter, query, header or cookie name; the key description for `value`; empty for `body` and `context`. */
   readonly name: N
   readonly read: (ctx: Context) => T | Promise<T>
 }
@@ -78,6 +81,17 @@ export function header(name: string, parser?: ValueParser<unknown>): Argument<un
   }
 }
 
+/** Cookie. Like `@Cookies('session')` with `cookie-parser`; `signed(signer)` checks a signed one. */
+export function cookie(name: string): Argument<string | undefined, 'cookie'>
+export function cookie<V extends ValueParser<unknown>>(name: string, parser: V): Argument<Parsed<V>, 'cookie'>
+export function cookie(name: string, parser?: ValueParser<unknown>): Argument<unknown, 'cookie'> {
+  return {
+    kind: 'cookie',
+    name,
+    read: parser === undefined ? (ctx) => ctx.cookie(name) : (ctx) => ctx.cookie(name, parser),
+  }
+}
+
 /** JSON body, validated by `schema`. Like `@Body() dto: CreateUserDto` with a validation pipe. */
 export function body(): Argument<unknown, 'body'>
 export function body<S extends StandardSchemaV1>(schema: S): Argument<InferOutput<S>, 'body'>
@@ -91,3 +105,29 @@ export function body(schema?: StandardSchemaV1): Argument<unknown, 'body'> {
 
 /** The context itself, for what no other argument covers. Like `@Req()`. */
 export const context = (): Argument<Context, 'context'> => ({ kind: 'context', name: '', read: (ctx) => ctx })
+
+/**
+ * Value a guard or an interceptor attached to the request. Like a custom Nest
+ * parameter decorator such as `@User()`.
+ *
+ * ```ts
+ * @Get('me', [value(USER)])
+ * me(user: User) {}
+ * ```
+ */
+export const value = <T>(key: ContextKey<T>): Argument<T, 'value'> => ({
+  kind: 'value',
+  name: key.description,
+  read: (ctx) => ctx.get(key),
+})
+
+/** Form body, validated by `schema` when given, within `limits`. Like `@Body()` on a form, or Nest's file interceptors with multer limits. */
+export function form(limits?: FormLimits): Argument<FormFields, 'body'>
+export function form<S extends StandardSchemaV1>(schema: S, limits?: FormLimits): Argument<InferOutput<S>, 'body'>
+export function form(schemaOrLimits?: StandardSchemaV1 | FormLimits, limits?: FormLimits): Argument<unknown, 'body'> {
+  return {
+    kind: 'body',
+    name: '',
+    read: isStandardSchema(schemaOrLimits) ? (ctx) => ctx.form(schemaOrLimits, limits) : (ctx) => ctx.form(schemaOrLimits),
+  }
+}

package/src/http/body.ts

@@ -15,7 +15,7 @@
  *    (`"constructor": "Ford"`) is legitimate and kept.
  */
 
-import { BadRequestException, UnsupportedMediaTypeException } from './exceptions.ts'
+import { BadRequestException, PayloadTooLargeException, UnsupportedMediaTypeException } from './exceptions.ts'
 
 const SUSPECT_PROTO =
   /"(?:_|\\u005[Ff])(?:_|\\u005[Ff])(?:p|\\u0070)(?:r|\\u0072)(?:o|\\u006[Ff])(?:t|\\u0074)(?:o|\\u006[Ff])(?:_|\\u005[Ff])(?:_|\\u005[Ff])"\s*:/
@@ -79,3 +79,144 @@ export const readJsonBody = async (req: Request): Promise<unknown> => {
 
   return parseJson(text)
 }
+
+const FORM_TYPE = /^(?:multipart\/form-data|application\/x-www-form-urlencoded)(?:\s*;|$)/i
+const ARRAY_SUFFIX = '[]'
+
+/** Parsed form data, as `Request.formData()` gives it. */
+type FormBody = Awaited<ReturnType<Request['formData']>>
+
+/** A form value: text, or a file of a multipart body. */
+export type FormValue = string | File
+
+/** Fields of a form; repeated fields and fields named `name[]` are arrays. */
+export type FormFields = Record<string, FormValue | FormValue[]>
+
+/**
+ * Turns form data into an object without prototype.
+ *
+ * ```ts
+ * 'a=1&a=2'      => { a: ['1', '2'] }   // repeated fields are kept, not overwritten
+ * 'tags[]=x'     => { tags: ['x'] }     // `[]` always gives an array, even with one value
+ * 'name=Ann'     => { name: 'Ann' }
+ * ```
+ */
+const toFields = (data: FormBody): FormFields => {
+  const fields: FormFields = Object.create(null)
+
+  for (const [rawKey, value] of data) {
+    const array = rawKey.endsWith(ARRAY_SUFFIX)
+    const key = array ? rawKey.slice(0, -ARRAY_SUFFIX.length) : rawKey
+    const current = fields[key]
+
+    if (current === undefined) {
+      fields[key] = array ? [value] : value
+    } else if (Array.isArray(current)) {
+      current.push(value)
+    } else {
+      fields[key] = [current, value]
+    }
+  }
+
+  return fields
+}
+
+/**
+ * Limits of a form body, beyond the server's `maxRequestBodySize`; each one
+ * exceeded is a `413`. Like the `limits` of multer and `@fastify/multipart`.
+ */
+export interface FormLimits {
+  /** Bytes of the whole body, refused as soon as they are exceeded, before the body is read entirely. */
+  readonly maxBodySize?: number
+  /** Bytes of each file. */
+  readonly maxFileSize?: number
+  /** Number of files. */
+  readonly maxFiles?: number
+  /** Number of fields, files included. */
+  readonly maxFields?: number
+}
+
+/** The body, read up to `max` bytes: `413` as soon as it is larger. */
+const readUpTo = async (req: Request, max: number): Promise<Uint8Array<ArrayBuffer>> => {
+  if (Number(req.headers.get('content-length') ?? 0) > max) {
+    throw new PayloadTooLargeException(`Request body is larger than ${max} bytes`)
+  }
+
+  if (req.body === null) {
+    return new Uint8Array()
+  }
+
+  const chunks: Uint8Array[] = []
+  let size = 0
+
+  for await (const chunk of req.body) {
+    size += chunk.byteLength
+
+    if (size > max) {
+      throw new PayloadTooLargeException(`Request body is larger than ${max} bytes`)
+    }
+
+    chunks.push(chunk)
+  }
+
+  return Buffer.concat(chunks)
+}
+
+/** `413` for the first limit the form exceeds. */
+const checkLimits = (data: FormBody, limits: FormLimits): void => {
+  const { maxFileSize = Infinity, maxFiles = Infinity, maxFields = Infinity } = limits
+  let fields = 0
+  let files = 0
+
+  for (const [name, value] of data) {
+    fields++
+
+    if (fields > maxFields) {
+      throw new PayloadTooLargeException(`Form has more than ${maxFields} fields`)
+    }
+
+    if (typeof value !== 'string') {
+      files++
+
+      if (files > maxFiles) {
+        throw new PayloadTooLargeException(`Form has more than ${maxFiles} files`)
+      }
+
+      if (value.size > maxFileSize) {
+        throw new PayloadTooLargeException(`File "${name}" is larger than ${maxFileSize} bytes`)
+      }
+    }
+  }
+}
+
+/**
+ * Reads a `multipart/form-data` or `application/x-www-form-urlencoded` body:
+ * `415` for another content type, `400` for a malformed body, `413` past a limit.
+ *
+ * Kept apart from JSON on purpose: an HTML form on another site can post a form
+ * without a CORS preflight, a JSON body cannot. A JSON endpoint must not accept forms.
+ *
+ * `File.type` is the type the client declared, not checked against the content.
+ */
+export const readFormBody = async (req: Request, limits: FormLimits = {}): Promise<FormFields> => {
+  const type = req.headers.get('content-type')
+
+  if (type === null || !FORM_TYPE.test(type)) {
+    throw new UnsupportedMediaTypeException(`Expected a form body, got ${type ?? 'no content type'}`)
+  }
+
+  // Parsed from the bytes read so far, as only a whole body can be parsed.
+  const source =
+    limits.maxBodySize === undefined ? req : new Response(await readUpTo(req, limits.maxBodySize), { headers: { 'content-type': type } })
+  let data: FormBody
+
+  try {
+    data = await source.formData()
+  } catch (error) {
+    throw new BadRequestException('Request body is not a valid form', { cause: error })
+  }
+
+  checkLimits(data, limits)
+
+  return toFields(data)
+}

package/src/http/context-key.ts

@@ -0,0 +1,35 @@
+/**
+ * @module
+ * Typed keys for values attached to a request: what a guard found (the user,
+ * the tenant), read later by interceptors and the handler.
+ *
+ * Like Angular's `HttpContextToken`: the key is an object, so two keys can
+ * never collide, and it carries the value type. Unlike it, a default is
+ * optional: reading a key nobody set and that has no default is a programming
+ * error (a guard missing on the route), reported as such.
+ *
+ * ```ts
+ * export const USER = new ContextKey<User>('user')
+ *
+ * // guard
+ * ctx.set(USER, await this.#auth.verify(ctx.header('authorization')))
+ *
+ * // handler
+ * const user = ctx.get(USER)
+ * ```
+ */
+
+/**
+ * Key of a value attached to a request.
+ */
+export class ContextKey<T> {
+  constructor(
+    readonly description: string,
+    /** Value of the key when nothing was set. Without it, reading an unset key throws. */
+    readonly defaultValue?: () => T
+  ) {}
+
+  toString(): string {
+    return `ContextKey(${this.description})`
+  }
+}