hoa 0.3.5 → 0.4.0

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## v0.4.0 / 2026-05-09
+
+- feat: add SKILL.md
+- fix: improve Content-Length validation in request.length getter
+- fix: normalize Content-Type in response.type getter with trim and lowercase
+- fix: correct HTTP status code validation range from 100-1000 to 100-599
+- fix: return empty string for empty query objects in stringifyQueryToString
+- docs: clarify middleware array flattening behavior in compose function
+- fix: export status code redirect empty mapping constants types
+- fix(request): should clear search when set to null or undefined
+- fix(response): should return null for invalid Content-Length header
+- perf(response): hoist TextEncoder to a module-level singleton
+- perf(request): hoist client IP header list to a module-level constant
+- fix(types): rename HoaError to HttpErrorOptions for naming consistency
+- chore(test): add content-length above 2 GB
+
 ## v0.3.5 / 2026-02-03
 
 - hotfix: package.json exports

package/dist/cjs/lib/compose.cjs

@@ -17,7 +17,8 @@ const composeSlim = (middlewares) => async (ctx, next) => {
 };
 /**
 * Compose multiple middleware functions into one.
-* Validates input, flattens nested arrays, and returns a composed dispatcher.
+* Validates input, flattens one level of nested arrays,
+* and returns a composed dispatcher.
 *
 * @param {HoaMiddleware[]|HoaMiddleware[][]} middlewares - Array of middleware functions or nested arrays
 * @returns {HoaMiddleware} Composed middleware function

package/dist/cjs/lib/utils.cjs

@@ -24,6 +24,7 @@ function parseSearchParamsToQuery(searchParams) {
 */
 function stringifyQueryToString(query) {
 	if (!query) return "";
+	if (Object.keys(query).length === 0) return "";
 	const params = new URLSearchParams();
 	for (const [key, value] of Object.entries(query)) if (Array.isArray(value)) value.forEach((v) => params.append(key, v ?? ""));
 	else params.append(key, value ?? "");

package/dist/cjs/request.cjs

@@ -1,6 +1,21 @@
 const require_lib_utils = require('./lib/utils.cjs');
 
 //#region src/request.js
+const IP_HEADERS = [
+	"x-client-ip",
+	"x-forwarded-for",
+	"cf-connecting-ip",
+	"do-connecting-ip",
+	"fastly-client-ip",
+	"true-client-ip",
+	"x-real-ip",
+	"x-cluster-client-ip",
+	"x-forwarded",
+	"forwarded-for",
+	"forwarded",
+	"x-appengine-user-ip",
+	"cf-pseudo-ipv4"
+];
 /**
 * @typedef {Object} ReqJSON
 * @property {string} method - Request method
@@ -180,7 +195,7 @@ var HoaRequest = class {
 	* @public
 	*/
 	set search(val) {
-		this.url.search = val.startsWith("?") ? val : val ? `?${val}` : "";
+		this.url.search = val ?? "";
 		this._query = null;
 	}
 	/**
@@ -396,21 +411,7 @@ var HoaRequest = class {
 	* @public
 	*/
 	get ip() {
-		for (const header of [
-			"x-client-ip",
-			"x-forwarded-for",
-			"cf-connecting-ip",
-			"do-connecting-ip",
-			"fastly-client-ip",
-			"true-client-ip",
-			"x-real-ip",
-			"x-cluster-client-ip",
-			"x-forwarded",
-			"forwarded-for",
-			"forwarded",
-			"x-appengine-user-ip",
-			"cf-pseudo-ipv4"
-		]) {
+		for (const header of IP_HEADERS) {
 			const value = this.get(header);
 			if (value) if (header === "x-forwarded-for" || header === "forwarded-for") {
 				const firstIp = value.split(",")[0]?.trim();
@@ -421,7 +422,7 @@ var HoaRequest = class {
 	}
 	/**
 	* Get the request content length from the Content-Length header.
-	* Returns undefined if the header is missing, empty, or not a valid number.
+	* Returns null if the header is missing, empty, or not a valid number.
 	*
 	* @returns {number|null} The content length in bytes, or null if not available
 	* @public
@@ -429,7 +430,10 @@ var HoaRequest = class {
 	get length() {
 		const len = this.get("Content-Length");
 		if (len == null) return null;
-		return ~~len;
+		if (!/^\d+$/.test(len)) return null;
+		const n = Number(len);
+		if (!Number.isSafeInteger(n)) return null;
+		return n;
 	}
 	/**
 	* Get the request content type from the Content-Type header.

package/dist/cjs/response.cjs

@@ -1,6 +1,7 @@
 const require_lib_utils = require('./lib/utils.cjs');
 
 //#region src/response.js
+const encoder = new TextEncoder();
 /**
 * @typedef {Object} ResJSON
 * @property {number} status - Response status code
@@ -142,7 +143,7 @@ var HoaResponse = class {
 	*/
 	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}`);
+		if (val < 100 || val > 599) throw new TypeError(`invalid status code: ${val}`);
 		this._status = val;
 		this._explicitStatus = true;
 		if (!this._explicitStatusText) this._statusText = require_lib_utils.statusTextMapping[val];
@@ -275,7 +276,7 @@ var HoaResponse = class {
 	get type() {
 		const type = this.get("Content-Type");
 		if (!type) return null;
-		return type.split(";", 1)[0];
+		return type.split(";", 1)[0].trim().toLowerCase();
 	}
 	/**
 	* Set the response Content-Type.
@@ -297,14 +298,20 @@ var HoaResponse = class {
 	* @public
 	*/
 	get length() {
-		if (this.has("Content-Length")) return Number.parseInt(this.get("Content-Length"), 10) || 0;
+		const len = this.get("Content-Length");
+		if (len != null) {
+			if (!/^\d+$/.test(len)) return null;
+			const n = Number(len);
+			if (!Number.isSafeInteger(n)) return null;
+			return n;
+		}
 		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 (typeof this.body === "string") return encoder.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;
+		if (this.body instanceof URLSearchParams) return encoder.encode(this.body.toString()).length;
+		return encoder.encode(JSON.stringify(this.body)).length;
 	}
 	/**
 	* Set the response Content-Length header.

package/dist/esm/lib/compose.mjs

@@ -16,7 +16,8 @@ const composeSlim = (middlewares) => async (ctx, next) => {
 };
 /**
 * Compose multiple middleware functions into one.
-* Validates input, flattens nested arrays, and returns a composed dispatcher.
+* Validates input, flattens one level of nested arrays,
+* and returns a composed dispatcher.
 *
 * @param {HoaMiddleware[]|HoaMiddleware[][]} middlewares - Array of middleware functions or nested arrays
 * @returns {HoaMiddleware} Composed middleware function

package/dist/esm/lib/utils.mjs

@@ -23,6 +23,7 @@ function parseSearchParamsToQuery(searchParams) {
 */
 function stringifyQueryToString(query) {
 	if (!query) return "";
+	if (Object.keys(query).length === 0) return "";
 	const params = new URLSearchParams();
 	for (const [key, value] of Object.entries(query)) if (Array.isArray(value)) value.forEach((v) => params.append(key, v ?? ""));
 	else params.append(key, value ?? "");

package/dist/esm/request.mjs

@@ -1,6 +1,21 @@
 import { parseSearchParamsToQuery, stringifyQueryToString } from "./lib/utils.mjs";
 
 //#region src/request.js
+const IP_HEADERS = [
+	"x-client-ip",
+	"x-forwarded-for",
+	"cf-connecting-ip",
+	"do-connecting-ip",
+	"fastly-client-ip",
+	"true-client-ip",
+	"x-real-ip",
+	"x-cluster-client-ip",
+	"x-forwarded",
+	"forwarded-for",
+	"forwarded",
+	"x-appengine-user-ip",
+	"cf-pseudo-ipv4"
+];
 /**
 * @typedef {Object} ReqJSON
 * @property {string} method - Request method
@@ -180,7 +195,7 @@ var HoaRequest = class {
 	* @public
 	*/
 	set search(val) {
-		this.url.search = val.startsWith("?") ? val : val ? `?${val}` : "";
+		this.url.search = val ?? "";
 		this._query = null;
 	}
 	/**
@@ -396,21 +411,7 @@ var HoaRequest = class {
 	* @public
 	*/
 	get ip() {
-		for (const header of [
-			"x-client-ip",
-			"x-forwarded-for",
-			"cf-connecting-ip",
-			"do-connecting-ip",
-			"fastly-client-ip",
-			"true-client-ip",
-			"x-real-ip",
-			"x-cluster-client-ip",
-			"x-forwarded",
-			"forwarded-for",
-			"forwarded",
-			"x-appengine-user-ip",
-			"cf-pseudo-ipv4"
-		]) {
+		for (const header of IP_HEADERS) {
 			const value = this.get(header);
 			if (value) if (header === "x-forwarded-for" || header === "forwarded-for") {
 				const firstIp = value.split(",")[0]?.trim();
@@ -421,7 +422,7 @@ var HoaRequest = class {
 	}
 	/**
 	* Get the request content length from the Content-Length header.
-	* Returns undefined if the header is missing, empty, or not a valid number.
+	* Returns null if the header is missing, empty, or not a valid number.
 	*
 	* @returns {number|null} The content length in bytes, or null if not available
 	* @public
@@ -429,7 +430,10 @@ var HoaRequest = class {
 	get length() {
 		const len = this.get("Content-Length");
 		if (len == null) return null;
-		return ~~len;
+		if (!/^\d+$/.test(len)) return null;
+		const n = Number(len);
+		if (!Number.isSafeInteger(n)) return null;
+		return n;
 	}
 	/**
 	* Get the request content type from the Content-Type header.

package/dist/esm/response.mjs

@@ -1,6 +1,7 @@
 import { commonTypeMapping, encodeUrl, statusEmptyMapping, statusRedirectMapping, statusTextMapping } from "./lib/utils.mjs";
 
 //#region src/response.js
+const encoder = new TextEncoder();
 /**
 * @typedef {Object} ResJSON
 * @property {number} status - Response status code
@@ -142,7 +143,7 @@ var HoaResponse = class {
 	*/
 	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}`);
+		if (val < 100 || val > 599) throw new TypeError(`invalid status code: ${val}`);
 		this._status = val;
 		this._explicitStatus = true;
 		if (!this._explicitStatusText) this._statusText = statusTextMapping[val];
@@ -275,7 +276,7 @@ var HoaResponse = class {
 	get type() {
 		const type = this.get("Content-Type");
 		if (!type) return null;
-		return type.split(";", 1)[0];
+		return type.split(";", 1)[0].trim().toLowerCase();
 	}
 	/**
 	* Set the response Content-Type.
@@ -297,14 +298,20 @@ var HoaResponse = class {
 	* @public
 	*/
 	get length() {
-		if (this.has("Content-Length")) return Number.parseInt(this.get("Content-Length"), 10) || 0;
+		const len = this.get("Content-Length");
+		if (len != null) {
+			if (!/^\d+$/.test(len)) return null;
+			const n = Number(len);
+			if (!Number.isSafeInteger(n)) return null;
+			return n;
+		}
 		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 (typeof this.body === "string") return encoder.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;
+		if (this.body instanceof URLSearchParams) return encoder.encode(this.body.toString()).length;
+		return encoder.encode(JSON.stringify(this.body)).length;
 	}
 	/**
 	* Set the response Content-Length header.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hoa",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "A minimal web framework built on Web Standards",
   "main": "./dist/cjs/hoa.cjs",
   "type": "module",

package/types/index.d.ts

@@ -1,35 +1,28 @@
-interface HoaAppJson {
+export interface HoaAppJson {
   name: string;
 }
 
-interface HoaContextJson {
+export interface HoaContextJson {
   app: HoaAppJson;
   req: HoaRequestJson;
   res: HoaResponseJson;
 }
 
-interface HoaRequestJson {
+export interface HoaRequestJson {
   method: string;
   url: string;
   headers: Record<string, string>;
 }
 
-interface HoaResponseJson {
+export 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;
+export type HoaMiddleware = (ctx: HoaContext, next: () => Promise<void>) => Promise<void> | void;
 
 export declare class Hoa {
   constructor(options?: { name?: string });
@@ -61,8 +54,10 @@ export declare class HoaContext {
   env?: any;
   executionCtx?: any;
   state: Record<string, any>;
-  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>;
+  throw(status: number, message?: string, options?: HttpErrorOptions): never;
+  throw(status: number, options: HttpErrorOptions): never;
+  assert<T>(value: T, status: number, message?: string, options?: HttpErrorOptions): asserts value is NonNullable<T>;
+  assert<T>(value: T, status: number, options: HttpErrorOptions): asserts value is NonNullable<T>;
   onerror(err: unknown): Response;
   toJSON(): HoaContextJson;
   readonly response: Response;
@@ -139,7 +134,7 @@ export declare class HoaRequest {
   toJSON(): HoaRequestJson;
 }
 
-type HoaResponseBody =
+export type HoaResponseBody =
   | string
   | Blob
   | ArrayBuffer
@@ -190,12 +185,16 @@ export declare class HoaResponse {
   toJSON(): HoaResponseJson;
 }
 
+export interface HttpErrorOptions {
+  message?: string;
+  cause?: unknown;
+  expose?: boolean;
+  headers?: Headers | Record<string, string> | Iterable<readonly [string, string]>;
+}
+
 export declare class HttpError extends Error {
-  constructor(
-    status: number,
-    message?: string | HoaError,
-    options?: HoaError
-  );
+  constructor(status: number, message?: string, options?: HttpErrorOptions);
+  constructor(status: number, options: HttpErrorOptions);
   readonly name: string;
   readonly status: number;
   readonly statusCode: number;
@@ -207,4 +206,10 @@ export declare function compose(
   middlewares: ReadonlyArray<HoaMiddleware> | ReadonlyArray<ReadonlyArray<HoaMiddleware>>
 ): HoaMiddleware;
 
+export const statusTextMapping: Record<number, string>;
+
+export const statusRedirectMapping: Record<number, boolean>;
+
+export const statusEmptyMapping: Record<number, boolean>;
+
 export default Hoa;