hoa 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## v0.3.4 / 2026-01-26
+
+- feat: use tsdown instead of tsup
+- fix: update devDependencies
+
+## v0.3.3 / 2025-12-03
+
+- fix: types improvements
+
 ## v0.3.2 / 2025-11-09
 
 - fix: export statusTextMapping + statusRedirectMapping + statusEmptyMapping

package/dist/cjs/context.cjs

@@ -0,0 +1,152 @@
+const require_lib_utils = require('./lib/utils.cjs');
+const require_lib_http_error = require('./lib/http-error.cjs');
+
+//#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 require_lib_http_error(...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 require_lib_http_error(...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" || !require_lib_utils.statusTextMapping[status]) status = 500;
+		const message = require_lib_utils.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 (require_lib_utils.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
+module.exports = HoaContext;

package/dist/cjs/hoa.cjs

@@ -0,0 +1,158 @@
+Object.defineProperty(exports, '__esModule', { value: true });
+const require_lib_utils = require('./lib/utils.cjs');
+const require_lib_http_error = require('./lib/http-error.cjs');
+const require_context = require('./context.cjs');
+const require_lib_compose = require('./lib/compose.cjs');
+const require_request = require('./request.cjs');
+const require_response = require('./response.cjs');
+
+//#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 = require_context;
+		this.HoaRequest = require_request;
+		this.HoaResponse = require_response;
+		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 = require_lib_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
+exports.Hoa = Hoa;
+exports.default = Hoa;
+exports.HoaContext = require_context;
+exports.HoaRequest = require_request;
+exports.HoaResponse = require_response;
+exports.HttpError = require_lib_http_error;
+exports.compose = require_lib_compose;
+exports.statusEmptyMapping = require_lib_utils.statusEmptyMapping;
+exports.statusRedirectMapping = require_lib_utils.statusRedirectMapping;
+exports.statusTextMapping = require_lib_utils.statusTextMapping;

package/dist/cjs/lib/compose.cjs

@@ -0,0 +1,35 @@
+
+//#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
+module.exports = compose;

package/dist/cjs/lib/http-error.cjs

@@ -0,0 +1,42 @@
+const require_lib_utils = require('./utils.cjs');
+
+//#region src/lib/http-error.js
+/**
+* @typedef {Object} HttpErrorOptions
+* @property {string} [message] - Custom error message
+* @property {Error} [cause] - The underlying cause of this error
+* @property {boolean} [expose] - Whether to expose the error message to clients (defaults based on status)
+* @property {HeadersInit} [headers] - Additional response headers
+*/
+var HttpError = class HttpError extends Error {
+	/**
+	* Create a new HttpError instance.
+	*
+	* @param {number} status - HTTP status code (400-599, invalid codes become 500)
+	* @param {string|HttpErrorOptions} [message] - Error message or options object
+	* @param {HttpErrorOptions} [options] - Additional options when second param is string
+	* @throws {TypeError}
+	*/
+	constructor(status, message, options) {
+		if (!Number.isInteger(status)) throw new TypeError("status code must be an integer");
+		if (status < 400 || status >= 600) status = 500;
+		let finalOptions = {};
+		if (typeof message === "string") {
+			finalOptions.message = message;
+			if (options && typeof options === "object") finalOptions = {
+				...finalOptions,
+				...options
+			};
+		} else if (message && typeof message === "object") finalOptions = message;
+		message = finalOptions.message ?? require_lib_utils.statusTextMapping[status] ?? "Unknown error";
+		super(message, { cause: finalOptions.cause });
+		this.name = "HttpError";
+		this.status = this.statusCode = status;
+		this.expose = finalOptions.expose ?? status < 500;
+		if (finalOptions.headers) this.headers = Object.fromEntries(new Headers(finalOptions.headers).entries());
+		if (Error.captureStackTrace) Error.captureStackTrace(this, HttpError);
+	}
+};
+
+//#endregion
+module.exports = HttpError;

package/dist/cjs/lib/utils.cjs

@@ -0,0 +1,214 @@
+
+//#region src/lib/utils.js
+/**
+* Parse URLSearchParams into a query object, handling multiple values for the same key.
+* When a key appears multiple times, values are collected into an array.
+*
+* @param {URLSearchParams} searchParams - The URLSearchParams object to parse
+* @returns {Record<string, string|string[]>} Query object with string values or arrays for multiple values
+* @public
+*/
+function parseSearchParamsToQuery(searchParams) {
+	const query = {};
+	for (const [key, value] of searchParams) if (query[key] !== void 0) query[key] = [].concat(query[key], value);
+	else query[key] = value;
+	return query;
+}
+/**
+* Convert a query object to a URL query string.
+* Handles arrays by appending multiple parameters with the same key.
+*
+* @param {Record<string, string|string[]|undefined|null>} query - Query object to stringify
+* @returns {string} URL-encoded query string (without leading '?')
+* @public
+*/
+function stringifyQueryToString(query) {
+	if (!query) 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 ?? "");
+	return params.toString();
+}
+/**
+* Mapping of HTTP status codes to their standard reason phrases.
+*
+* @type {Record<number, string>}
+* @public
+*/
+const statusTextMapping = {
+	100: "Continue",
+	101: "Switching Protocols",
+	102: "Processing",
+	103: "Early Hints",
+	200: "OK",
+	201: "Created",
+	202: "Accepted",
+	203: "Non-Authoritative Information",
+	204: "No Content",
+	205: "Reset Content",
+	206: "Partial Content",
+	207: "Multi-Status",
+	208: "Already Reported",
+	226: "IM Used",
+	300: "Multiple Choices",
+	301: "Moved Permanently",
+	302: "Found",
+	303: "See Other",
+	304: "Not Modified",
+	305: "Use Proxy",
+	307: "Temporary Redirect",
+	308: "Permanent Redirect",
+	400: "Bad Request",
+	401: "Unauthorized",
+	402: "Payment Required",
+	403: "Forbidden",
+	404: "Not Found",
+	405: "Method Not Allowed",
+	406: "Not Acceptable",
+	407: "Proxy Authentication Required",
+	408: "Request Timeout",
+	409: "Conflict",
+	410: "Gone",
+	411: "Length Required",
+	412: "Precondition Failed",
+	413: "Payload Too Large",
+	414: "URI Too Long",
+	415: "Unsupported Media Type",
+	416: "Range Not Satisfiable",
+	417: "Expectation Failed",
+	418: "I'm a Teapot",
+	421: "Misdirected Request",
+	422: "Unprocessable Entity",
+	423: "Locked",
+	424: "Failed Dependency",
+	425: "Too Early",
+	426: "Upgrade Required",
+	428: "Precondition Required",
+	429: "Too Many Requests",
+	431: "Request Header Fields Too Large",
+	451: "Unavailable For Legal Reasons",
+	500: "Internal Server Error",
+	501: "Not Implemented",
+	502: "Bad Gateway",
+	503: "Service Unavailable",
+	504: "Gateway Timeout",
+	505: "HTTP Version Not Supported",
+	506: "Variant Also Negotiates",
+	507: "Insufficient Storage",
+	508: "Loop Detected",
+	509: "Bandwidth Limit Exceeded",
+	510: "Not Extended",
+	511: "Network Authentication Required"
+};
+/**
+* Mapping of HTTP status codes that indicate redirects.
+* Used to determine if a response should trigger a redirect.
+*
+* @type {Record<number, boolean>}
+* @readonly
+* @public
+*/
+const statusRedirectMapping = {
+	300: true,
+	301: true,
+	302: true,
+	303: true,
+	305: true,
+	307: true,
+	308: true
+};
+/**
+* Mapping of HTTP status codes that should have empty response bodies.
+* These status codes by specification should not include a message body.
+*
+* @type {Record<number, boolean>}
+* @readonly
+* @public
+*/
+const statusEmptyMapping = {
+	204: true,
+	205: true,
+	304: true
+};
+/**
+* Mapping of common content type aliases to their full MIME types.
+* Provides convenient shortcuts for setting response content types.
+*
+* @type {Record<string, string>}
+* @readonly
+* @public
+*/
+const commonTypeMapping = {
+	html: "text/html;charset=UTF-8",
+	text: "text/plain;charset=UTF-8",
+	xml: "text/xml;charset=UTF-8",
+	md: "text/markdown;charset=UTF-8",
+	json: "application/json",
+	form: "application/x-www-form-urlencoded;charset=UTF-8",
+	pdf: "application/pdf",
+	zip: "application/zip",
+	wasm: "application/wasm",
+	webmanifest: "application/manifest+json",
+	js: "application/javascript;charset=UTF-8",
+	ts: "application/typescript;charset=UTF-8",
+	png: "image/png",
+	jpg: "image/jpeg",
+	jpeg: "image/jpeg",
+	gif: "image/gif",
+	svg: "image/svg+xml",
+	webp: "image/webp",
+	avif: "image/avif",
+	ico: "image/x-icon",
+	mp3: "audio/mpeg",
+	wav: "audio/wav",
+	ogg: "audio/ogg",
+	mp4: "video/mp4",
+	webm: "video/webm",
+	avi: "video/x-msvideo",
+	mov: "video/quicktime",
+	woff: "font/woff",
+	woff2: "font/woff2",
+	ttf: "font/ttf",
+	otf: "font/otf",
+	bin: "application/octet-stream"
+};
+const ENCODE_CHARS_REGEXP = /(?:[^\x21\x23-\x3B\x3D\x3F-\x5F\x61-\x7A\x7C\x7E]|%(?:[^0-9A-Fa-f]|[0-9A-Fa-f][^0-9A-Fa-f]|$))+/g;
+/**
+* RegExp to match unmatched surrogate pair.
+* @private
+*/
+const UNMATCHED_SURROGATE_PAIR_REGEXP = /(^|[^\uD800-\uDBFF])[\uDC00-\uDFFF]|[\uD800-\uDBFF]([^\uDC00-\uDFFF]|$)/g;
+/**
+* String to replace unmatched surrogate pair with.
+* @private
+*/
+const UNMATCHED_SURROGATE_PAIR_REPLACE = "$1�$2";
+/**
+* Encode a URL to a percent-encoded form, excluding already-encoded sequences.
+*
+* This function will take an already-encoded URL and encode all the non-URL
+* code points. This function will not encode the "%" character unless it is
+* not part of a valid sequence (`%20` will be left as-is, but `%foo` will
+* be encoded as `%25foo`).
+*
+* This encode is meant to be "safe" and does not throw errors. It will try as
+* hard as it can to properly encode the given URL, including replacing any raw,
+* unpaired surrogate pairs with the Unicode replacement character prior to
+* encoding.
+*
+* @param {string} url - URL string to encode
+* @return {string} Encoded URL string
+* @public
+*/
+function encodeUrl(url) {
+	return String(url).replace(UNMATCHED_SURROGATE_PAIR_REGEXP, UNMATCHED_SURROGATE_PAIR_REPLACE).replace(ENCODE_CHARS_REGEXP, encodeURI);
+}
+
+//#endregion
+exports.commonTypeMapping = commonTypeMapping;
+exports.encodeUrl = encodeUrl;
+exports.parseSearchParamsToQuery = parseSearchParamsToQuery;
+exports.statusEmptyMapping = statusEmptyMapping;
+exports.statusRedirectMapping = statusRedirectMapping;
+exports.statusTextMapping = statusTextMapping;
+exports.stringifyQueryToString = stringifyQueryToString;