hoa 0.3.2 → 0.3.4

package/dist/esm/response.mjs

@@ -0,0 +1,335 @@
+import { commonTypeMapping, encodeUrl, statusEmptyMapping, statusRedirectMapping, statusTextMapping } from "./lib/utils.mjs";
+
+//#region src/response.js
+/**
+* @typedef {Object} ResJSON
+* @property {number} status - Response status code
+* @property {string} statusText - Response status text
+* @property {Record<string, string|string[]>} headers - Response headers
+*/
+/**
+* @class HoaResponse
+*/
+var HoaResponse = class {
+	/**
+	* Expose a plain object snapshot of response headers.
+	* Uses the Web Standard Headers API internally for proper header handling.
+	* Returns a plain object representation where header names are normalized.
+	*
+	* @returns {Record<string, string>} Object with all response headers
+	* @public
+	*/
+	get headers() {
+		this._headers = this._headers || new Headers();
+		return Object.fromEntries(this._headers.entries());
+	}
+	/**
+	* Set the response headers.
+	* Accepts either a Headers object or a plain object/array of header entries.
+	* This replaces all existing headers with the new ones.
+	*
+	* @param {Headers|Record<string, string>|Array<[string, string]>} val - Headers to set
+	* @public
+	*/
+	set headers(val) {
+		if (val instanceof Headers) this._headers = val;
+		else this._headers = new Headers(val);
+	}
+	/**
+	* Get a response header value by name (case-insensitive).
+	* Uses the Web Standard Headers API for proper header retrieval.
+	* Special-cases "referer/referrer" for compatibility.
+	* Returns null for empty or whitespace-only field names.
+	*
+	* @param {string} field - The header name
+	* @returns {string|null} The header value or null if not found
+	* @public
+	*/
+	get(field) {
+		if (!field) return null;
+		this._headers = this._headers || new Headers();
+		switch (field = field.toLowerCase()) {
+			case "referer":
+			case "referrer": return this._headers.get("referrer") ?? this._headers.get("referer");
+			default: return this._headers.get(field);
+		}
+	}
+	/**
+	* Get all Set-Cookie header values as an array.
+	* Returns all Set-Cookie headers that will be sent with the response.
+	*
+	* @returns {string[]} Array of Set-Cookie header values
+	* @public
+	*/
+	getSetCookie() {
+		this._headers = this._headers || new Headers();
+		return this._headers.getSetCookie();
+	}
+	/**
+	* Check if a response header is present.
+	* Uses the Web Standard Headers API for case-insensitive header checking.
+	*
+	* @param {string} field - The header name to check
+	* @returns {boolean} True if the header exists
+	* @public
+	*/
+	has(field) {
+		if (!field) return false;
+		this._headers = this._headers || new Headers();
+		return this._headers.has(field);
+	}
+	/**
+	* Set response header(s) using the Web Standard Headers API.
+	* Accepts various input formats:
+	* - Single key/value pair
+	* - Plain object with multiple headers
+	* Replaces existing header values.
+	*
+	* @param {string|Record<string,string>} field - Header name or headers object
+	* @param {string} [val] - Header value when field is a string
+	* @public
+	*/
+	set(field, val) {
+		if (!field) return;
+		this._headers = this._headers || new Headers();
+		if (typeof field === "string") this._headers.set(field, val);
+		else Object.keys(field).forEach((header) => this._headers.set(header, field[header]));
+	}
+	/**
+	* Append a response header value using the Web Standard Headers API.
+	* Does not replace existing values, but appends to them.
+	* This is useful for headers that can have multiple values like Set-Cookie.
+	*
+	* @param {string|Record<string,string>} field - The header name or headers object
+	* @param {string} [val] - The value to append when field is a string
+	* @public
+	*/
+	append(field, val) {
+		if (!field) return;
+		this._headers = this._headers || new Headers();
+		if (typeof field === "string") this._headers.append(field, val);
+		else Object.keys(field).forEach((header) => this._headers.append(header, field[header]));
+	}
+	/**
+	* Delete a response header by name using the Web Standard Headers API.
+	* Header deletion is case-insensitive.
+	*
+	* @param {string} field - The header name to delete
+	* @public
+	*/
+	delete(field) {
+		if (!field) return;
+		this._headers = this._headers || new Headers();
+		this._headers.delete(field);
+	}
+	/**
+	* Get the response status code.
+	* Defaults to 404 if not explicitly set.
+	*
+	* @returns {number} The HTTP status code
+	* @public
+	*/
+	get status() {
+		return this._status || 404;
+	}
+	/**
+	* Set the response status code.
+	* Automatically clears body for status codes that should not have content.
+	*
+	* @param {number} val - The HTTP status code (100-599)
+	* @throws {TypeError}
+	* @public
+	*/
+	set status(val) {
+		if (!Number.isInteger(val)) throw new TypeError("status code must be an integer");
+		if (val < 100 || val > 1e3) throw new TypeError(`invalid status code: ${val}`);
+		this._status = val;
+		this._explicitStatus = true;
+		if (!this._explicitStatusText) this._statusText = statusTextMapping[val];
+		if (this.body && statusEmptyMapping[val]) this.body = null;
+	}
+	/**
+	* Get the response status text.
+	*
+	* @returns {string} The statusText (e.g., 'OK', 'Not Found')
+	* @public
+	*/
+	get statusText() {
+		if (this._explicitStatusText) return this._statusText;
+		return this._statusText || (this._statusText = statusTextMapping[this.status]);
+	}
+	/**
+	* Set a custom response status text.
+	*
+	* @param {string} val - The custom status text
+	* @public
+	*/
+	set statusText(val) {
+		this._statusText = val;
+		this._explicitStatusText = true;
+	}
+	/**
+	* Get the response body.
+	*
+	* @returns {any} The response body content
+	* @public
+	*/
+	get body() {
+		return this._body;
+	}
+	/**
+	* Set response body with automatic content-type detection.
+	* Supports various body types and automatically sets appropriate headers.
+	* When set to null/undefined, if current Content-Type is application/json,
+	* body becomes the literal string 'null'; otherwise status is set to 204 and
+	* Content-Type/Transfer-Encoding are removed.
+	*
+	* @param {string|Object|ReadableStream|Blob|Response|ArrayBuffer|TypedArray|FormData|URLSearchParams|null} val - The response body
+	* @public
+	*/
+	set body(val) {
+		this._body = val;
+		if (val == null) {
+			if (!statusEmptyMapping[this.status]) {
+				if (this.type === "application/json") {
+					this._body = "null";
+					return;
+				}
+				this.status = 204;
+			}
+			if (val === null) this._explicitNullBody = true;
+			this.delete("Content-Type");
+			this.delete("Content-Length");
+			this.delete("Transfer-Encoding");
+			return;
+		}
+		if (!this._explicitStatus) this.status = 200;
+		const noType = !this.has("Content-Type");
+		if (typeof val === "string") {
+			if (noType) this.type = /^\s*</.test(val) ? "html" : "text";
+			return;
+		}
+		if (val instanceof Blob || val instanceof ArrayBuffer || ArrayBuffer.isView(val) || val instanceof ReadableStream) {
+			if (noType) if (val instanceof Blob && val.type) this.set("Content-Type", val.type);
+			else this.type = "bin";
+			return;
+		}
+		if (val instanceof FormData) return;
+		if (val instanceof URLSearchParams) {
+			if (noType) this.type = "form";
+			return;
+		}
+		if (val instanceof Response) {
+			if (noType) this.type = "bin";
+			this.status = val.status;
+			for (const [k, v] of val.headers) this.set(k, v);
+			return;
+		}
+		if (!this.type || !/\bjson\b/i.test(this.type)) this.type = "json";
+	}
+	/**
+	* Perform an HTTP redirect to the specified URL.
+	* Automatically sets the Location header and appropriate status code.
+	* Absolute URLs are normalized and Location value is URL-encoded.
+	*
+	* @param {string} url - The URL to redirect to (absolute or relative)
+	* @public
+	*/
+	redirect(url) {
+		if (/^https?:\/\//i.test(url)) url = new URL(url).toString();
+		this.set("Location", encodeUrl(url));
+		if (!statusRedirectMapping[this.status]) this.status = 302;
+		this.type = "text";
+		this.body = `Redirecting to ${url}.`;
+	}
+	/**
+	* Perform a special-cased "back" redirect using the Referrer header.
+	* When Referrer is not present or unsafe, falls back to the provided alternative or "/".
+	* Only redirects to same-origin referrers for security.
+	* If referrer is an absolute URL with different origin or an invalid URL, falls back.
+	*
+	* @param {string} [alt='/'] - Alternative URL when referrer is unavailable or unsafe
+	* @public
+	*/
+	back(alt) {
+		const referrer = this.req.get("Referrer");
+		if (referrer) {
+			if (referrer.startsWith("/")) {
+				this.redirect(referrer);
+				return;
+			}
+			if (new URL(referrer, this.req.href).origin === this.req.origin) {
+				this.redirect(referrer);
+				return;
+			}
+		}
+		this.redirect(alt || "/");
+	}
+	/**
+	* Get the response Content-Type without parameters.
+	* Returns only the media type without parameters (e.g., 'application/json').
+	*
+	* @returns {string|null} The content type, or null if not set
+	* @public
+	*/
+	get type() {
+		const type = this.get("Content-Type");
+		if (!type) return null;
+		return type.split(";", 1)[0];
+	}
+	/**
+	* Set the response Content-Type.
+	* Supports both full MIME types and shorthand aliases.
+	*
+	* @param {string} type - The content type or alias (e.g., 'json', 'html', 'application/json')
+	* @public
+	*/
+	set type(val) {
+		if (!val) return;
+		val = commonTypeMapping[val] || val;
+		this.set("Content-Type", val);
+	}
+	/**
+	* Get the response Content-Length as a number.
+	* Returns the parsed Content-Length header value, or calculates it from the body if available.
+	*
+	* @returns {number|null} The content length in bytes, or null if not determinable
+	* @public
+	*/
+	get length() {
+		if (this.has("Content-Length")) return Number.parseInt(this.get("Content-Length"), 10) || 0;
+		if (this.body == null || this.body instanceof ReadableStream || this.body instanceof FormData || this.body instanceof Response) return null;
+		if (typeof this.body === "string") return new TextEncoder().encode(this.body).length;
+		if (this.body instanceof Blob) return this.body.size;
+		if (this.body instanceof ArrayBuffer) return this.body.byteLength;
+		if (ArrayBuffer.isView(this.body)) return this.body.byteLength;
+		if (this.body instanceof URLSearchParams) return new TextEncoder().encode(this.body.toString()).length;
+		return new TextEncoder().encode(JSON.stringify(this.body)).length;
+	}
+	/**
+	* Set the response Content-Length header.
+	* Only sets the header if Transfer-Encoding is not present.
+	*
+	* @param {number|string} val - The content length in bytes
+	* @public
+	*/
+	set length(val) {
+		if (!this.has("Transfer-Encoding")) this.set("Content-Length", val);
+	}
+	/**
+	* Return JSON representation of the response.
+	*
+	* @returns {ResJSON} JSON representation of response
+	* @public
+	*/
+	toJSON() {
+		return {
+			status: this.status,
+			statusText: this.statusText,
+			headers: this.headers
+		};
+	}
+};
+
+//#endregion
+export { HoaResponse as default };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hoa",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "A minimal web framework built on Web Standards",
   "main": "./dist/cjs/hoa.js",
   "type": "module",
@@ -21,7 +21,7 @@
   ],
   "scripts": {
     "lint": "eslint .",
-    "build": "tsup",
+    "build": "tsdown",
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
     "prepublishOnly": "npm run lint && npm run test && npm run build",
     "prepare": "husky"
@@ -48,14 +48,14 @@
     "lambda"
   ],
   "devDependencies": {
-    "@commitlint/cli": "20.1.0",
-    "@commitlint/config-conventional": "20.0.0",
-    "eslint": "9.39.1",
-    "globals": "16.5.0",
+    "@commitlint/cli": "20.3.1",
+    "@commitlint/config-conventional": "20.3.1",
+    "eslint": "9.39.2",
+    "globals": "17.1.0",
     "husky": "9.1.7",
     "jest": "30.2.0",
     "neostandard": "0.12.2",
-    "tsup": "8.5.0"
+    "tsdown": "0.20.1"
   },
   "engines": {
     "node": ">=20"

package/types/index.d.ts

@@ -1,25 +1,32 @@
-interface AppJSON {
+interface HoaAppJson {
   name: string;
 }
 
-interface CtxJSON {
-  app: AppJSON;
-  req: ReqJSON;
-  res: ResJSON;
+interface HoaContextJson {
+  app: HoaAppJson;
+  req: HoaRequestJson;
+  res: HoaResponseJson;
 }
 
-interface ReqJSON {
+interface HoaRequestJson {
   method: string;
   url: string;
   headers: Record<string, string>;
 }
 
-interface ResJSON {
+interface HoaResponseJson {
   status: number;
   statusText: string;
   headers: Record<string, string>;
 }
 
+interface HoaError {
+  message?: string;
+  cause?: unknown;
+  expose?: boolean;
+  headers?: Headers | Record<string, string> | Iterable<readonly [string, string]>;
+}
+
 export type HoaExtension = (app: Hoa) => void;
 
 export type HoaMiddleware = (ctx: HoaContext, next?: () => Promise<void>) => Promise<void> | void;
@@ -40,7 +47,7 @@ export declare class Hoa {
   protected handleRequest(ctx: HoaContext, middlewareFn: HoaMiddleware): Promise<Response>;
   protected createContext(request: Request, env?: any, executionCtx?: any): HoaContext;
   protected onerror(err: unknown, ctx?: HoaContext): void;
-  toJSON(): AppJSON;
+  toJSON(): HoaAppJson;
 
   static get default(): typeof Hoa;
 }
@@ -54,10 +61,10 @@ export declare class HoaContext {
   env?: any;
   executionCtx?: any;
   state: Record<string, any>;
-  throw(status: number, message?: string | { message?: string; cause?: unknown; expose?: boolean; headers?: Headers | Record<string, string> | Iterable<readonly [string, string]> }, options?: { message?: string; cause?: unknown; expose?: boolean; headers?: Headers | Record<string, string> | Iterable<readonly [string, string]> }): never;
-  assert<T>(value: T, status: number, message?: string | { message?: string; cause?: unknown; expose?: boolean; headers?: Headers | Record<string, string> | Iterable<readonly [string, string]> }, options?: { message?: string; cause?: unknown; expose?: boolean; headers?: Headers | Record<string, string> | Iterable<readonly [string, string]> }): asserts value is NonNullable<T>;
+  throw(status: number, message?: string | HoaError, options?: HoaError): never;
+  assert<T>(value: T, status: number, message?: string | HoaError, options?: HoaError): asserts value is NonNullable<T>;
   onerror(err: unknown): Response;
-  toJSON(): CtxJSON;
+  toJSON(): HoaContextJson;
   readonly response: Response;
 }
 
@@ -67,54 +74,54 @@ export declare class HoaRequest {
   res: HoaResponse;
 
   get url(): URL;
-  set url(value: string | URL);
+  set url(val: string | URL);
 
   get href(): string;
-  set href(value: string);
+  set href(val: string);
 
   get origin(): string;
-  set origin(value: string);
+  set origin(val: string);
 
   get protocol(): string;
-  set protocol(value: string);
+  set protocol(val: string);
 
   get host(): string;
-  set host(value: string);
+  set host(val: string);
 
   get hostname(): string;
-  set hostname(value: string);
+  set hostname(val: string);
 
   get port(): string;
-  set port(value: string);
+  set port(val: string);
 
   get pathname(): string;
-  set pathname(value: string);
+  set pathname(val: string);
 
   get search(): string;
-  set search(value: string);
+  set search(val: string);
 
   get hash(): string;
-  set hash(value: string);
+  set hash(val: string);
 
   get method(): string;
-  set method(value: string);
+  set method(val: string);
 
   get query(): Record<string, string | string[]>;
-  set query(value: Record<string, string | string[]>);
+  set query(val: Record<string, string | string[]>);
 
   get headers(): Record<string, string>;
-  set headers(value: Headers | Record<string, string> | Iterable<readonly [string, string]>);
+  set headers(val: Headers | Record<string, string> | Iterable<readonly [string, string]>);
 
   get body(): ReadableStream<Uint8Array> | null;
-  set body(value: any);
+  set body(val: any);
 
   get(field: string): string | null;
   getSetCookie(): string[];
   has(field: string): boolean;
-  set(field: string, value: string): void;
-  set(values: Record<string, string>): void;
-  append(field: string, value: string): void;
-  append(values: Record<string, string>): void;
+  set(field: string, val: string): void;
+  set(field: Record<string, string>): void;
+  append(field: string, val: string): void;
+  append(field: Record<string, string>): void;
   delete(field: string): void;
 
   get ips(): string[];
@@ -129,10 +136,10 @@ export declare class HoaRequest {
   text(): Promise<string>;
   json<T = any>(): Promise<T>;
   formData(): Promise<FormData>;
-  toJSON(): ReqJSON;
+  toJSON(): HoaRequestJson;
 }
 
-type ResponseBody =
+type HoaResponseBody =
   | string
   | Blob
   | ArrayBuffer
@@ -151,43 +158,43 @@ export declare class HoaResponse {
   req: HoaRequest;
 
   get headers(): Record<string, string>;
-  set headers(value: Headers | Record<string, string> | Iterable<readonly [string, string]>);
+  set headers(val: Headers | Record<string, string> | Iterable<readonly [string, string]>);
 
   get(field: string): string | null;
   getSetCookie(): string[];
   has(field: string): boolean;
-  set(field: string, value: string): void;
-  set(values: Record<string, string>): void;
-  append(field: string, value: string): void;
-  append(values: Record<string, string>): void;
+  set(field: string, val: string): void;
+  set(field: Record<string, string>): void;
+  append(field: string, val: string): void;
+  append(field: Record<string, string>): void;
   delete(field: string): void;
 
   get status(): number;
-  set status(value: number);
+  set status(val: number);
 
   get statusText(): string;
-  set statusText(value: string);
+  set statusText(val: string);
 
-  get body(): ResponseBody;
-  set body(value: ResponseBody);
+  get body(): HoaResponseBody;
+  set body(val: HoaResponseBody);
 
   redirect(url: string): void;
   back(alt?: string): void;
 
   get type(): string | null;
-  set type(value: string);
+  set type(val: string);
 
   get length(): number | null;
-  set length(value: number | string);
+  set length(val: number | string);
 
-  toJSON(): ResJSON;
+  toJSON(): HoaResponseJson;
 }
 
 export declare class HttpError extends Error {
   constructor(
     status: number,
-    message?: string | { message?: string; cause?: unknown; expose?: boolean; headers?: Headers | Record<string, string> | Iterable<readonly [string, string]> },
-    options?: { message?: string; cause?: unknown; expose?: boolean; headers?: Headers | Record<string, string> | Iterable<readonly [string, string]> }
+    message?: string | HoaError,
+    options?: HoaError
   );
   readonly name: string;
   readonly status: number;