hoa 0.3.2 → 0.3.4

package/dist/cjs/response.cjs

@@ -0,0 +1,335 @@
+const require_lib_utils = require('./lib/utils.cjs');
+
+//#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 = require_lib_utils.statusTextMapping[val];
+		if (this.body && require_lib_utils.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 = require_lib_utils.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 (!require_lib_utils.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", require_lib_utils.encodeUrl(url));
+		if (!require_lib_utils.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 = require_lib_utils.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
+module.exports = HoaResponse;

package/dist/esm/context.mjs

@@ -0,0 +1,152 @@
+import { statusEmptyMapping, statusTextMapping } from "./lib/utils.mjs";
+import HttpError from "./lib/http-error.mjs";
+
+//#region src/context.js
+/**
+* @typedef {Object} CtxJSON
+* @property {ReturnType<import('./hoa.js').default.prototype.toJSON>} app
+* @property {ReturnType<import('./request.js').default.prototype.toJSON>} req
+* @property {ReturnType<import('./response.js').default.prototype.toJSON>} res
+*/
+/**
+* @class HoaContext
+*/
+var HoaContext = class {
+	/**
+	* Create a context for a single HTTP request.
+	*
+	* @param {Object} [options={}]
+	* @param {Request} [options.request] - Web Standard Request
+	* @param {any} [options.env] - Environment (platform-specific)
+	* @param {any} [options.executionCtx] - Execution context (platform-specific)
+	* @public
+	*/
+	constructor(options = {}) {
+		this.request = options.request;
+		this.env = options.env;
+		this.executionCtx = options.executionCtx;
+		this.state = Object.create(null);
+	}
+	/**
+	* Throw an HttpError.
+	*
+	* @param {number} status - HTTP status code
+	* @param {string|{message?: string, cause?: any, headers?: HeadersInit}} [messageOrOptions] - Error message or options object
+	* @throws {HttpError}
+	* @public
+	*/
+	throw(...args) {
+		throw new HttpError(...args);
+	}
+	/**
+	* Assert condition or throw an HttpError.
+	*
+	* @param {any} value - Condition to assert
+	* @param {...any} args - Arguments passed to HttpError constructor
+	* @throws {HttpError}
+	* @public
+	*/
+	assert(value, ...args) {
+		if (value) return;
+		throw new HttpError(...args);
+	}
+	/**
+	* Default error handling and response builder.
+	*
+	* @param {Error} err - Error to handle
+	* @returns {Response} Web Standard Response object
+	* @private
+	*/
+	onerror(err) {
+		const { res } = this;
+		if (!(Object.prototype.toString.call(err) === "[object Error]" || err instanceof Error)) err = /* @__PURE__ */ new Error(`non-error thrown: ${JSON.stringify(err)}`);
+		this.app.onerror(err, this);
+		res.headers = new Headers();
+		res.set(err.headers);
+		res.type = "text";
+		let status = err.status || err.statusCode;
+		if (typeof status !== "number" || !statusTextMapping[status]) status = 500;
+		const message = statusTextMapping[status];
+		const msg = err.expose ? err.message : message;
+		res.status = status;
+		res.body = msg;
+		return new Response(res.body, {
+			status: res.status,
+			headers: res._headers
+		});
+	}
+	/**
+	* Build Web Standard Response from current context state.
+	* Handles various body types, HEAD requests, and status-specific behaviors.
+	*
+	* @returns {Response} Web Standard Response object
+	* @public
+	*/
+	get response() {
+		const { res, req } = this;
+		let body = res.body;
+		if (req.method === "HEAD") {
+			if (!res.has("Content-Length")) {
+				const contentLength = res.length;
+				if (Number.isInteger(contentLength)) res.length = contentLength;
+			}
+			return new Response(null, {
+				status: res.status,
+				statusText: res.statusText,
+				headers: res._headers
+			});
+		}
+		if (statusEmptyMapping[res.status]) {
+			res.body = null;
+			return new Response(null, {
+				status: res.status,
+				statusText: res.statusText,
+				headers: res._headers
+			});
+		}
+		if (body == null) {
+			if (res._explicitNullBody) {
+				res.delete("Content-Type");
+				res.delete("Transfer-Encoding");
+				res.set("Content-Length", "0");
+			}
+			return new Response(null, {
+				status: res.status,
+				statusText: res.statusText,
+				headers: res._headers
+			});
+		}
+		if (typeof body === "string" || body instanceof Blob || body instanceof ArrayBuffer || ArrayBuffer.isView(body) || body instanceof ReadableStream || body instanceof FormData || body instanceof URLSearchParams) return new Response(body, {
+			status: res.status,
+			statusText: res.statusText,
+			headers: res._headers
+		});
+		if (body instanceof Response) return new Response(body.body, {
+			status: res.status,
+			statusText: res.statusText,
+			headers: res._headers
+		});
+		body = JSON.stringify(body);
+		return new Response(body, {
+			status: res.status,
+			statusText: res.statusText,
+			headers: res._headers
+		});
+	}
+	/**
+	* Return JSON representation of the context.
+	*
+	* @returns {CtxJSON} JSON representation of context
+	* @public
+	*/
+	toJSON() {
+		return {
+			app: this.app.toJSON(),
+			req: this.req.toJSON(),
+			res: this.res.toJSON()
+		};
+	}
+};
+
+//#endregion
+export { HoaContext as default };

package/dist/esm/hoa.mjs

@@ -0,0 +1,148 @@
+import { statusEmptyMapping, statusRedirectMapping, statusTextMapping } from "./lib/utils.mjs";
+import HttpError from "./lib/http-error.mjs";
+import HoaContext from "./context.mjs";
+import compose from "./lib/compose.mjs";
+import HoaRequest from "./request.mjs";
+import HoaResponse from "./response.mjs";
+
+//#region src/hoa.js
+/**
+* @typedef {Object} AppJSON
+* @property {string} name - Application name
+*/
+/**
+* @class Hoa
+* @property {string} name - Application name
+* @property {boolean} [silent] - Suppress error console output when true
+*/
+var Hoa = class Hoa {
+	/**
+	* Create an Hoa instance.
+	*
+	* @param {Object} [options={}] - Application options
+	* @param {string} [options.name='Hoa'] - Application name for identification
+	*/
+	constructor(options = {}) {
+		this.name = options.name || "Hoa";
+		this.HoaContext = HoaContext;
+		this.HoaRequest = HoaRequest;
+		this.HoaResponse = HoaResponse;
+		this.middlewares = [];
+		this.fetch = this.fetch.bind(this);
+	}
+	/**
+	* Extend the application with a plugin initializer.
+	*
+	* @param {HoaExtension} fn - Plugin function that receives the app instance
+	* @returns {Hoa} The Hoa instance for method chaining
+	* @throws {TypeError}
+	* @public
+	*/
+	extend(fn) {
+		if (typeof fn !== "function") throw new TypeError("extend() must receive a function!");
+		fn(this);
+		return this;
+	}
+	/**
+	* Register a middleware. Executed in registration order.
+	*
+	* @param {HoaMiddleware} fn - Middleware function
+	* @returns {Hoa} The Hoa instance for method chaining
+	* @throws {TypeError}
+	* @public
+	*/
+	use(fn) {
+		if (typeof fn !== "function") throw new TypeError("use() must receive a function!");
+		this.middlewares.push(fn);
+		this._composedMiddleware = null;
+		return this;
+	}
+	/**
+	* Web Standards fetch handler - main entry point for HTTP requests.
+	* Compatible with Cloudflare Workers, Deno, and other Web Standards environments.
+	*
+	* @param {Request} request - Web Standard Request object
+	* @param {any} [env] - Environment variables (platform-specific)
+	* @param {any} [executionCtx] - Execution context (platform-specific)
+	* @returns {Promise<Response>} Web Standard Response object
+	* @public
+	*/
+	fetch(request, env, executionCtx) {
+		const ctx = this.createContext(request, env, executionCtx);
+		if (!this._composedMiddleware) this._composedMiddleware = compose(this.middlewares);
+		return this.handleRequest(ctx, this._composedMiddleware);
+	}
+	/**
+	* Handle incoming request through the middleware stack.
+	* Manages error handling and response building.
+	*
+	* @param {HoaContext} ctx - Request context
+	* @param {HoaMiddleware} middlewareFn - Composed middleware function
+	* @returns {Promise<Response>} Web Standard Response object
+	* @private
+	*/
+	handleRequest(ctx, middlewareFn) {
+		return middlewareFn(ctx).then(() => ctx.response).catch((err) => ctx.onerror(err));
+	}
+	/**
+	* Create context for incoming request with linked request/response objects.
+	* Establishes the context chain: ctx ↔ req ↔ res ↔ app
+	*
+	* @param {Request} request - Web Standard Request object
+	* @param {any} [env] - Environment variables
+	* @param {any} [executionCtx] - Execution context
+	* @returns {HoaContext} Created context instance
+	* @private
+	*/
+	createContext(request, env, executionCtx) {
+		const ctx = new this.HoaContext({
+			request,
+			env,
+			executionCtx
+		});
+		const req = ctx.req = new this.HoaRequest();
+		const res = ctx.res = new this.HoaResponse();
+		ctx.app = req.app = res.app = this;
+		req.ctx = res.ctx = ctx;
+		req.res = res;
+		res.req = req;
+		return ctx;
+	}
+	/**
+	* Default error handler for unhandled application errors.
+	* Logs errors to console unless they're client errors (4xx) or explicitly exposed.
+	*
+	* @param {Error} err - Error to handle
+	* @param {HoaContext} [ctx] - Request context (optional)
+	* @returns {void}
+	* @throws {TypeError}
+	* @private
+	*/
+	onerror(err, ctx) {
+		if (!(Object.prototype.toString.call(err) === "[object Error]" || err instanceof Error)) throw new TypeError(`non-error thrown: ${JSON.stringify(err)}`);
+		if (err.status === 404 || err.expose) return;
+		if (this.silent) return;
+		console.error(err);
+	}
+	/**
+	* ESM/CJS interop helper for default exports.
+	*
+	* @returns {typeof Hoa} The Hoa class
+	* @static
+	*/
+	static get default() {
+		return Hoa;
+	}
+	/**
+	* Return JSON representation of the app.
+	*
+	* @returns {AppJSON} JSON representation of application
+	* @public
+	*/
+	toJSON() {
+		return { name: this.name };
+	}
+};
+
+//#endregion
+export { Hoa, Hoa as default, HoaContext, HoaRequest, HoaResponse, HttpError, compose, statusEmptyMapping, statusRedirectMapping, statusTextMapping };

package/dist/esm/lib/compose.mjs

@@ -0,0 +1,34 @@
+//#region src/lib/compose.js
+/**
+* Compose middleware functions into a single dispatcher.
+*
+* @param {HoaMiddleware[]} middlewares - Array of middleware functions
+* @returns {HoaMiddleware} Composed middleware function
+* @private
+*/
+const composeSlim = (middlewares) => async (ctx, next) => {
+	const dispatch = (i) => async () => {
+		const fn = i === middlewares.length ? next : middlewares[i];
+		if (!fn) return;
+		return await fn(ctx, dispatch(i + 1));
+	};
+	return dispatch(0)();
+};
+/**
+* Compose multiple middleware functions into one.
+* Validates input, flattens nested arrays, and returns a composed dispatcher.
+*
+* @param {HoaMiddleware[]|HoaMiddleware[][]} middlewares - Array of middleware functions or nested arrays
+* @returns {HoaMiddleware} Composed middleware function
+* @throws {TypeError}
+* @public
+*/
+function compose(middlewares) {
+	if (!Array.isArray(middlewares)) throw new TypeError("compose() must receive an array of middleware functions!");
+	middlewares = middlewares.flat();
+	for (const middleware of middlewares) if (typeof middleware !== "function") throw new TypeError("Middleware must be composed of functions!");
+	return composeSlim(middlewares);
+}
+
+//#endregion
+export { compose as default };