@prexjs/request 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Prexjs (https://prexjs.com)
+Copyright (c) 2026 Sorabh (https://sorabh.org)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+# @prexjs/request
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Extended HTTP Request prototype and interfaces for Prex and Express applications.**
+
+[![npm version](https://img.shields.io/npm/v/@prexjs/request)](https://www.npmjs.com/package/@prexjs/request)
+[![npm downloads](https://img.shields.io/npm/dm/@prexjs/request)](https://www.npmjs.com/package/@prexjs/request)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-supported-blue)](https://www.typescriptlang.org/)
+
+`@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:
+
+```bash
+# npm
+npm install @prexjs/request
+
+# pnpm
+pnpm add @prexjs/request
+
+# Yarn
+yarn add @prexjs/request
+
+# Bun
+bun add @prexjs/request
+```
+
+## Quick start
+
+```ts
+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`](https://github.com/prexjs/prex.js/tree/main/packages/response): HTTP Response prototype.
+- [`@prexjs/application`](https://github.com/prexjs/prex.js/tree/main/packages/application): Core application prototype.
+- [`@prexjs/prex`](https://github.com/prexjs/prex.js/tree/main/packages/prex): The fast and modular web framework.
+
+## License
+
+[MIT](./LICENSE)

package/lib/index.cjs

@@ -0,0 +1,7 @@
+/*!
+ * @prexjs/request
+ * Copyright (c) 2026 Prexjs (https://prexjs.com)
+ * Copyright (c) 2026 Sorabh (https://Sorabh.org)
+ * MIT Licensed
+ */
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e=require("node:http"),t=require("node:net"),r=require("@prexjs/accepts"),s=require("@prexjs/type-is"),n=require("@prexjs/fresh"),i=require("@prexjs/range-parser"),u=require("@prexjs/parseurl"),o=require("@prexjs/proxy-address");function a(e){return e&&"object"==typeof e&&"default"in e?e:{default:e}}var f=a(e),c=a(r),h=a(n),d=a(i),p=a(u),l=a(o);const g=function(e){let t=e;for(;t&&"object"==typeof t&&"default"in t&&void 0!==t.default;)t=t.default;return t}(p.default),y=Object.create(f.default.IncomingMessage.prototype);function x(e,t,r){Object.defineProperty(e,t,{configurable:!0,enumerable:!0,get:r})}y.get=y.header=function(e){if(!e)throw new TypeError("name argument is required to req.get");if("string"!=typeof e)throw new TypeError("name must be a string to req.get");const t=e.toLowerCase();switch(t){case"referer":case"referrer":return this.headers.referrer||this.headers.referer;default:return this.headers[t]}},y.accepts=function(...e){return c.default(this).types(...e)},y.acceptsEncodings=function(...e){return c.default(this).encodings(...e)},y.acceptsCharsets=function(...e){return c.default(this).charsets(...e)},y.acceptsLanguages=function(...e){return c.default(this).languages(...e)},y.range=function(e,t){const r=this.get("Range");if(r)return d.default(e,r,t)},x(y,"query",function(){const e=this.app.get("query parser fn");if(!e)return Object.create(null);return e(g(this).query)}),y.is=function(e,...t){let r;if(r=Array.isArray(e)?e:void 0===e?t:[e,...t],!s.hasBody(this))return null;if(!r||0===r.length)return null;try{return new s.TypeIs(r).request(this)||!1}catch{return!1}},x(y,"protocol",function(){const e=this.socket.encrypted?"https":"http";if(!this.app.get("trust proxy fn")(this.socket.remoteAddress,0))return e;const t=this.get("X-Forwarded-Proto")||e,r=t.indexOf(",");return-1!==r?t.substring(0,r).trim():t.trim()}),x(y,"secure",function(){return"https"===this.protocol}),x(y,"ip",function(){const e=this.app.get("trust proxy fn");return l.default(this,e)}),x(y,"ips",function(){const e=this.app.get("trust proxy fn"),t=l.default.all(this,e);return t.reverse().pop(),t}),x(y,"subdomains",function(){const e=this.hostname;if(!e)return[];const r=this.app.get("subdomain offset");return(t.isIP(e)?[e]:e.split(".").reverse()).slice(r)}),x(y,"path",function(){return g(this).pathname}),x(y,"host",function(){const e=this.app.get("trust proxy fn");let t=this.get("X-Forwarded-Host");return t&&e(this.socket.remoteAddress,0)?-1!==t.indexOf(",")&&(t=t.substring(0,t.indexOf(",")).trimEnd()):t=this.get("Host"),t||void 0}),x(y,"hostname",function(){const e=this.host;if(!e)return;const t="["===e[0]?e.indexOf("]")+1:0,r=e.indexOf(":",t);return-1!==r?e.substring(0,r):e}),x(y,"fresh",function(){const e=this.method,t=this.res,r=t.statusCode;return("GET"===e||"HEAD"===e||"QUERY"===e)&&((r>=200&&r<300||304===r)&&h.default(this.headers,{etag:t.get("ETag"),"last-modified":t.get("Last-Modified")}))}),x(y,"stale",function(){return!this.fresh}),x(y,"xhr",function(){return"xmlhttprequest"===(this.get("X-Requested-With")||"").toLowerCase()}),exports.default=y;

package/lib/index.d.cts

@@ -0,0 +1,63 @@
+import http from 'node:http';
+import { Options, Result, Ranges } from '@prexjs/range-parser';
+import { Application } from '@prexjs/application';
+import { Response } from '@prexjs/response';
+
+interface Request extends http.IncomingMessage {
+    app: Application;
+    res: Response;
+    next?: (err?: unknown) => void;
+    secret?: string | string[];
+    params?: Record<string, string>;
+    body?: any;
+    /** Return request header. `Referrer` and `Referer` are interchangeable. Aliased as `req.header()`. */
+    get(name: "set-cookie"): string[] | undefined;
+    get(name: string): string | undefined;
+    header(name: "set-cookie"): string[] | undefined;
+    header(name: string): string | undefined;
+    /** Check if the given `type(s)` is acceptable, returning the best match, otherwise `false`. */
+    accepts(): string[];
+    accepts(type: string): string | false;
+    accepts(type: string[]): string | false;
+    accepts(...type: string[]): string | false;
+    acceptsEncodings(): string[];
+    acceptsEncodings(encoding: string): string | false;
+    acceptsEncodings(encoding: string[]): string | false;
+    acceptsEncodings(...encoding: string[]): string | false;
+    /** Checks if the specified `charset`s are acceptable based on `Accept-Charset`. */
+    acceptsCharsets(): string[];
+    acceptsCharsets(...charsets: string[]): string | false;
+    acceptsLanguages(): string[];
+    acceptsLanguages(...languages: string[]): string | false;
+    /**
+     * Parse Range header field, capping to the given `size`.
+     * Returns `undefined` if no header, `-1` when unsatisfiable, `-2` when invalid.
+     */
+    range(size: number, options?: Options): Result | Ranges | undefined;
+    /** Parsed query string, using the "query parser" setting. */
+    readonly query: any;
+    /** Check if the incoming request's Content-Type contains the given mime `type`. */
+    is(...types: string[]): string | false | null;
+    is(types: string[]): string | false | null;
+    /** "http" or "https"; honours X-Forwarded-Proto when "trust proxy" applies. */
+    readonly protocol: string;
+    readonly secure: boolean;
+    /** Remote address, taking "trust proxy" into account. */
+    readonly ip: string | undefined;
+    /** When "trust proxy" is set, trusted proxy addresses + client. */
+    readonly ips: string[];
+    readonly subdomains: string[];
+    readonly path: string;
+    readonly host: string | undefined;
+    readonly hostname: string | undefined;
+    /** True when Last-Modified / ETag still match. */
+    readonly fresh: boolean;
+    readonly stale: boolean;
+    /** True if the request was an _XMLHttpRequest_. */
+    readonly xhr: boolean;
+}
+/** Request prototype. */
+declare const req: Request;
+
+export { req as default };
+export type { Request };

package/lib/index.d.mts

@@ -0,0 +1,63 @@
+import http from 'node:http';
+import { Options, Result, Ranges } from '@prexjs/range-parser';
+import { Application } from '@prexjs/application';
+import { Response } from '@prexjs/response';
+
+interface Request extends http.IncomingMessage {
+    app: Application;
+    res: Response;
+    next?: (err?: unknown) => void;
+    secret?: string | string[];
+    params?: Record<string, string>;
+    body?: any;
+    /** Return request header. `Referrer` and `Referer` are interchangeable. Aliased as `req.header()`. */
+    get(name: "set-cookie"): string[] | undefined;
+    get(name: string): string | undefined;
+    header(name: "set-cookie"): string[] | undefined;
+    header(name: string): string | undefined;
+    /** Check if the given `type(s)` is acceptable, returning the best match, otherwise `false`. */
+    accepts(): string[];
+    accepts(type: string): string | false;
+    accepts(type: string[]): string | false;
+    accepts(...type: string[]): string | false;
+    acceptsEncodings(): string[];
+    acceptsEncodings(encoding: string): string | false;
+    acceptsEncodings(encoding: string[]): string | false;
+    acceptsEncodings(...encoding: string[]): string | false;
+    /** Checks if the specified `charset`s are acceptable based on `Accept-Charset`. */
+    acceptsCharsets(): string[];
+    acceptsCharsets(...charsets: string[]): string | false;
+    acceptsLanguages(): string[];
+    acceptsLanguages(...languages: string[]): string | false;
+    /**
+     * Parse Range header field, capping to the given `size`.
+     * Returns `undefined` if no header, `-1` when unsatisfiable, `-2` when invalid.
+     */
+    range(size: number, options?: Options): Result | Ranges | undefined;
+    /** Parsed query string, using the "query parser" setting. */
+    readonly query: any;
+    /** Check if the incoming request's Content-Type contains the given mime `type`. */
+    is(...types: string[]): string | false | null;
+    is(types: string[]): string | false | null;
+    /** "http" or "https"; honours X-Forwarded-Proto when "trust proxy" applies. */
+    readonly protocol: string;
+    readonly secure: boolean;
+    /** Remote address, taking "trust proxy" into account. */
+    readonly ip: string | undefined;
+    /** When "trust proxy" is set, trusted proxy addresses + client. */
+    readonly ips: string[];
+    readonly subdomains: string[];
+    readonly path: string;
+    readonly host: string | undefined;
+    readonly hostname: string | undefined;
+    /** True when Last-Modified / ETag still match. */
+    readonly fresh: boolean;
+    readonly stale: boolean;
+    /** True if the request was an _XMLHttpRequest_. */
+    readonly xhr: boolean;
+}
+/** Request prototype. */
+declare const req: Request;
+
+export { req as default };
+export type { Request };

package/lib/index.mjs

@@ -0,0 +1,7 @@
+/*!
+ * @prexjs/request
+ * Copyright (c) 2026 Prexjs (https://prexjs.com)
+ * Copyright (c) 2026 Sorabh (https://Sorabh.org)
+ * MIT Licensed
+ */
+import t from"node:http";import{isIP as e}from"node:net";import r from"@prexjs/accepts";import{hasBody as s,TypeIs as n}from"@prexjs/type-is";import o from"@prexjs/fresh";import i from"@prexjs/range-parser";import u from"@prexjs/parseurl";import c from"@prexjs/proxy-address";const f=function(t){let e=t;for(;e&&"object"==typeof e&&"default"in e&&void 0!==e.default;)e=e.default;return e}(u),a=Object.create(t.IncomingMessage.prototype);function p(t,e,r){Object.defineProperty(t,e,{configurable:!0,enumerable:!0,get:r})}a.get=a.header=function(t){if(!t)throw new TypeError("name argument is required to req.get");if("string"!=typeof t)throw new TypeError("name must be a string to req.get");const e=t.toLowerCase();switch(e){case"referer":case"referrer":return this.headers.referrer||this.headers.referer;default:return this.headers[e]}},a.accepts=function(...t){return r(this).types(...t)},a.acceptsEncodings=function(...t){return r(this).encodings(...t)},a.acceptsCharsets=function(...t){return r(this).charsets(...t)},a.acceptsLanguages=function(...t){return r(this).languages(...t)},a.range=function(t,e){const r=this.get("Range");if(r)return i(t,r,e)},p(a,"query",function(){const t=this.app.get("query parser fn");if(!t)return Object.create(null);return t(f(this).query)}),a.is=function(t,...e){let r;if(r=Array.isArray(t)?t:void 0===t?e:[t,...e],!s(this))return null;if(!r||0===r.length)return null;try{return new n(r).request(this)||!1}catch{return!1}},p(a,"protocol",function(){const t=this.socket.encrypted?"https":"http";if(!this.app.get("trust proxy fn")(this.socket.remoteAddress,0))return t;const e=this.get("X-Forwarded-Proto")||t,r=e.indexOf(",");return-1!==r?e.substring(0,r).trim():e.trim()}),p(a,"secure",function(){return"https"===this.protocol}),p(a,"ip",function(){const t=this.app.get("trust proxy fn");return c(this,t)}),p(a,"ips",function(){const t=this.app.get("trust proxy fn"),e=c.all(this,t);return e.reverse().pop(),e}),p(a,"subdomains",function(){const t=this.hostname;if(!t)return[];const r=this.app.get("subdomain offset");return(e(t)?[t]:t.split(".").reverse()).slice(r)}),p(a,"path",function(){return f(this).pathname}),p(a,"host",function(){const t=this.app.get("trust proxy fn");let e=this.get("X-Forwarded-Host");return e&&t(this.socket.remoteAddress,0)?-1!==e.indexOf(",")&&(e=e.substring(0,e.indexOf(",")).trimEnd()):e=this.get("Host"),e||void 0}),p(a,"hostname",function(){const t=this.host;if(!t)return;const e="["===t[0]?t.indexOf("]")+1:0,r=t.indexOf(":",e);return-1!==r?t.substring(0,r):t}),p(a,"fresh",function(){const t=this.method,e=this.res,r=e.statusCode;return("GET"===t||"HEAD"===t||"QUERY"===t)&&((r>=200&&r<300||304===r)&&o(this.headers,{etag:e.get("ETag"),"last-modified":e.get("Last-Modified")}))}),p(a,"stale",function(){return!this.fresh}),p(a,"xhr",function(){return"xmlhttprequest"===(this.get("X-Requested-With")||"").toLowerCase()});export{a as default};

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@prexjs/request",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Extended HTTP Request prototype and interfaces for Prex and Express applications.",
+  "authors": [
+    {
+      "name": "Prexjs",
+      "email": "hello@prexjs.com",
+      "url": "https://prexjs.com"
+    },
+    {
+      "name": "Sorabh",
+      "email": "hello@sorabh.org",
+      "url": "https://sorabh.org"
+    }
+  ],
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./lib/index.cjs",
+  "module": "./lib/index.mjs",
+  "types": "./lib/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./lib/index.d.mts",
+        "default": "./lib/index.mjs"
+      },
+      "require": {
+        "types": "./lib/index.d.cts",
+        "default": "./lib/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/prexjs/prex.js.git",
+    "directory": "packages/request"
+  },
+  "homepage": "https://github.com/prexjs/prex.js/tree/main/packages/request#readme",
+  "bugs": {
+    "url": "https://github.com/prexjs/prex.js/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "prex",
+    "request",
+    "req",
+    "http",
+    "incoming-message",
+    "express",
+    "headers",
+    "query"
+  ]
+}