JCC Express

Request

Introduction

Every HTTP handler receives an Express Request object. JCC Express MVC extends it as AppRequest (jcc-express-mvc/lib/Interface): the same instance is passed as req in route closures and in { req, res, next } / httpContext patterns. After the framework’s request middleware runs, Laravel-style helpers are bound onto req (via HttpRequest in jcc-express-mvc/lib/Request/request.ts), so you call req.input(), req.header(), and so on.

You can also use the global request() helper, which resolves the current AppRequest from the container (only valid during an HTTP request, after the per-request binding middleware runs).

Types: import Request from jcc-express-mvc as the AppRequest alias when you need to annotate parameters (for example FormRequest subclasses). For res, response(), Inertia, flash, and redirectBack, see Response.md in this folder.

When helpers are available

Helpers are attached after the framework runs new HttpRequest(req, res) inside the global middleware stack (see Request lifecycle). Anything that runs before that middleware only sees a plain Express request.

Input from query, body, and merged data

These methods merge query and body for reads (input); file fields are handled separately via file / hasFile / store.

  • req.input() — All merged input, or req.input(key, default?) for one key.
  • req.has(key) — Whether the key exists in merged input.
  • req.filled(key) — Present and non-empty string.
  • req.only(...keys) — Subset of keys.
  • req.except(...keys) — Copy of input without those keys (mutates the merged object for the copy path in the implementation—avoid relying on retaining the full original reference).
  • req.merge(data) — Shallow assign onto req.body.
  • req.replace(data) — Replace req.body entirely.

Route parameters remain on req.params (see Routing). input() does not include params; use req.params.id or route model binding in controllers.

Headers, content negotiation, and API-ish detection

  • req.header(name) — Case-insensitive header lookup.
  • req.ajax() — X-Requested-With: XMLHttpRequest.
  • req.isJson() — JSON Content-Type.
  • req.wantsJson(), req.acceptsJson() — Accept hints.
  • req.expectsJson() — Combines API path prefix (/api), AJAX, and JSON signals.
  • req.isInertia() — Presence of X-Inertia.
  • req.isApi() — true when the path starts with /api.

Use these to branch between JSON errors and HTML redirects, or to tailor Inertia responses.

Auth, session, and flash

  • req.user — Set by auth middleware when a user is authenticated (shape depends on your auth setup).
  • req.session — Express session (requires session middleware).
  • req.flash(...) — Flash API from connect-flash (same session stack).
  • req.jccSession — Framework session bridge when available.
  • Global session() returns req.jccSession when you use the helper style.

Details: put / get / save / regenerate, flash alignment with res.with, and configuration notes are in Session.md.

Validation

  • req.validate(rules, customMessages?) — Validates against the current request; wired in HttpRequest to the shared Validator (see framework validation docs / Validator module).
  • req.validated() — Retrieves validated data after validation has run (when your pipeline stores it).

The global validate(...) helper resolves the current request and calls validate on it.

Files and cookies

  • req.hasFile(key) — Uploaded file field present (express-fileupload style req.files).
  • req.file(name) — Returns the request for chaining; then req.store(directory) on the same req uses saveImage internally (see HttpRequest implementation).
  • req.cookie(key) — Parsed cookies (requires cookie-parser).

FormRequest subclasses can use protected file, store, cloudinaryFileUpload, etc., as defined on the base class.

Other helpers

  • req.bearerToken() — Parses Authorization: Bearer ….
  • req.userAgent() — User-Agent header.
  • req.isMethod("post") — Case-insensitive HTTP method check.
  • req.fullUrl() — Protocol, host, and originalUrl.
  • req.csrfToken() — Available when csrf() middleware ran; same value as res.locals._token (see CSRF-protection).

Express-native fields such as req.path, req.query, req.body, req.params, req.ip, and req.get("host") remain available.

FormRequest (action injection)

For validated or authorized form flows, extend FormRequest (jcc-express-mvc/Core/FormRequest) and type-hint the subclass on a controller method decorated with @Method(). The container constructs it with the current AppRequest, runs await rules() (your async or sync rules hook), then calls the action.

Typical pattern:

  • Implement protected async rules() (or sync) and call this.validate({ field: ["required"], … }) with rule arrays.
  • Optionally override protected authorize() — the base implementation returns false. If your override returns true, the constructor throws AuthorizationException (deny). Return false to allow the request to continue.

Expose domain actions such as save() on your subclass (UserRequest, etc.) and call them from the controller after injection.

Summary

  • AppRequest = Express Request + framework helpers bound per request.
  • Access via req, request(), or httpContext (parameter defaults only for context objects—see Routing).
  • Prefer req.input / only / validate for Laravel-like ergonomics; keep req.params for route segments and binding.
  • Sending the response: Response.md (AppResponse, res.inertia, res.with, redirectBack, globals view / redirect / back / inertia).
  • Session and flash: Session.md.