@prexjs/request

Extended HTTP Request prototype and interfaces for Prex and Express applications.

@prexjs/request defines the extended HTTP Request prototype and TypeScript definitions that build on Node's native http.IncomingMessage. It provides high-level properties and convenience methods for content negotiation, header normalization, query string parsing, byte-range evaluation, and IP resolution.

Features

• Header Access: Case-insensitive header lookup with .get(name) and .header(name), with special handling for 'Referrer'.
• Content Negotiation: Built-in methods for .accepts(), .acceptsEncodings(), .acceptsCharsets(), and .acceptsLanguages().
• Content-Type Validation: Match incoming payloads against MIME types and wildcards with .is(types).
• Proxy-Aware Network Properties: Robust .ip, .ips, .protocol, .secure, and .hostname getters that respect trust proxy settings.
• Cache Freshness Checks: Automatic evaluation of .fresh and .stale based on client headers and response tags.
• Byte Range Parsing: Built-in .range(size, options) method leveraging @prexjs/range-parser.

Installation

Install using your preferred package manager:

# npm
npm install @prexjs/request

# pnpm
pnpm add @prexjs/request

# Yarn
yarn add @prexjs/request

# Bun
bun add @prexjs/request

Quick start

import type { Request } from '@prexjs/request';
import prex from '@prexjs/prex';

const app = prex();

app.get('/api/resource', (req: Request, res) => {
  // Access normalized headers
  const auth = req.get('Authorization');

  // Negotiate response type
  if (req.accepts('json')) {
    res.json({ ip: req.ip, secure: req.secure });
  } else {
    res.type('txt').send(`IP: ${req.ip}`);
  }
});

API

Methods

• req.get(name) / req.header(name): Get the specified HTTP request header.
• req.accepts(types): Check if the specified content types are acceptable.
• req.acceptsEncodings(encodings): Check if specified transfer encodings are acceptable.
• req.acceptsCharsets(charsets): Check if specified character sets are acceptable.
• req.acceptsLanguages(languages): Check if specified languages are acceptable.
• req.range(size, options?): Parse Range header field.
• req.is(types): Check if the incoming request contains the specified Content-Type.

Getters

• req.ip: Remote IP address (respects proxy configuration).
• req.ips: Array of proxy IP addresses when proxy trust is enabled.
• req.hostname: Hostname derived from the Host header field.
• req.protocol: Protocol ('http' or 'https').
• req.secure: Boolean, true when req.protocol === 'https'.
• req.query: Parsed query string object.
• req.fresh: Check if response is still fresh in the client's cache.
• req.stale: Check if response is stale.
• req.xhr: Boolean, true if X-Requested-With header is 'xmlhttprequest'.

Compatibility

• Node.js >= 18.0.0
• Supports both ESM and CommonJS
• TypeScript 5.0+

Related Packages

• @prexjs/response: HTTP Response prototype.
• @prexjs/application: Core application prototype.
• @prexjs/prex: The fast and modular web framework.

License

MIT