hoa 0.0.1 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,3 @@
+v0.1.0 / 2025-09-25
+
+- init

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 - present, Hoa contributors
+
+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

@@ -0,0 +1,49 @@
+## Hoa
+
+Hoa is a minimal Web framework inspired by [Koa](https://github.com/koajs/koa) and [Hono](https://github.com/honojs/hono), built entirely on Web Standards. It runs seamlessly on any modern JavaScript runtime: Cloudflare Workers, Fastly Compute, Deno, Bun, Vercel, AWS Lambda, Lambda@Edge, and Node.js.
+
+## Features
+
+- ⚡ Minimal - Only ~4.4KB (gzipped).
+- 🚫 Zero Dependencies - Built on modern Web Standards with no external dependencies.
+- 🛠️ Highly Extensible - Features a flexible extension and middleware system.
+- 😊 Standards-Based - Designed entirely around modern Web Standard APIs.
+- 🌐 Multi-Runtime - The same code runs on Cloudflare Workers, Deno, Bun, Node.js, and more.
+- ✅ 100% Tested – Backed by a full-coverage automated test suite.
+
+## Installation
+
+```bash
+npm i hoa --save
+```
+
+## Quick Start
+
+```js
+import { Hoa } from 'hoa'
+const app = new Hoa()
+
+app.use(async (ctx, next) => {
+  ctx.res.body = 'Hello, Hoa!'
+})
+
+export default app
+```
+
+## Documentation
+
+The documentation is available on [hoa-js.com](https://hoa-js.com)
+
+## Contributing
+
+Contributions Welcome! You can contribute in the following ways.
+
+- Create an Issue - Propose a new feature. Report a bug.
+- Pull Request - Fix a bug and typo. Refactor the code.
+- Create third-party middleware.
+- Share your thoughts on the Blog, X, and others.
+- Make your application.
+
+## License
+
+Distributed under the MIT License.

package/dist/cjs/application.js

@@ -0,0 +1,245 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var application_exports = {};
+__export(application_exports, {
+  Hoa: () => Application,
+  HoaContext: () => import_context.default,
+  HoaRequest: () => import_request.default,
+  HoaResponse: () => import_response.default,
+  HttpError: () => import_http_error.default,
+  compose: () => import_compose.default,
+  default: () => Application
+});
+module.exports = __toCommonJS(application_exports);
+var import_compose = __toESM(require("./lib/compose.js"), 1);
+var import_http_error = __toESM(require("./lib/http-error.js"), 1);
+var import_utils = require("./lib/utils.js");
+var import_context = __toESM(require("./context.js"), 1);
+var import_request = __toESM(require("./request.js"), 1);
+var import_response = __toESM(require("./response.js"), 1);
+class Application {
+  /**
+   * Create an Application instance.
+   *
+   * @param {Object} [options={}] - Application options
+   * @param {string} [options.name='Hoa'] - Application name for identification
+   */
+  constructor(options = {}) {
+    this.name = options.name || "Hoa";
+    this.HoaContext = import_context.default;
+    this.HoaRequest = import_request.default;
+    this.HoaResponse = import_response.default;
+    this.middlewares = [];
+    this.fetch = this.fetch.bind(this);
+  }
+  /**
+   * Extend the application with a plugin initializer.
+   * @param {(app: Application) => void} fn - Plugin function that receives the app instance
+   * @returns {Application}
+   * @throws {TypeError} If fn is not a function
+   * @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 {(ctx: HoaContext, next: () => Promise<void>) => Promise<any | void>} fn - Middleware function
+   * @returns {Application}
+   * @throws {TypeError} If fn is not a function
+   * @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>}
+   * @public
+   */
+  fetch(request, env, executionCtx) {
+    const ctx = this.createContext(request, env, executionCtx);
+    if (!this._composedMiddleware) this._composedMiddleware = (0, import_compose.default)(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 {(ctx: HoaContext) => Promise<void>} middlewareFn - Composed middleware function
+   * @returns {Promise<Response>}
+   * @private
+   */
+  handleRequest(ctx, middlewareFn) {
+    const onerror = (err) => ctx.onerror(err);
+    const handleResponse = () => respond(ctx);
+    return middlewareFn(ctx).then(handleResponse).catch(onerror);
+  }
+  /**
+   * 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}
+   * @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)
+   * @throws {TypeError} When err is not a proper Error object
+   * @private
+   */
+  onerror(err, ctx) {
+    const isNativeError = Object.prototype.toString.call(err) === "[object Error]" || err instanceof Error;
+    if (!isNativeError) {
+      throw new TypeError(`non-error thrown: ${JSON.stringify(err)}`);
+    }
+    if (err.status === 404 || err.expose) return;
+    if (this.silent) return;
+    const msg = err.stack || err.toString();
+  }
+  /**
+   * ESM/CJS interop helper for default exports.
+   *
+   * @returns {typeof Application}
+   * @static
+   */
+  static get default() {
+    return Application;
+  }
+  /**
+   * Return JSON representation of the app.
+   *
+   * @returns {AppJSON}
+   * @public
+   */
+  toJSON() {
+    return {
+      name: this.name
+    };
+  }
+}
+function respond(ctx) {
+  const { res, req } = ctx;
+  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 (import_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");
+    }
+    if (!res._explicitStatus) {
+      res.status = 404;
+    }
+    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
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Hoa,
+  HoaContext,
+  HoaRequest,
+  HoaResponse,
+  HttpError,
+  compose
+});

package/dist/cjs/context.js

@@ -0,0 +1,111 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var context_exports = {};
+__export(context_exports, {
+  default: () => HoaContext
+});
+module.exports = __toCommonJS(context_exports);
+var import_http_error = __toESM(require("./lib/http-error.js"), 1);
+var import_utils = require("./lib/utils.js");
+class HoaContext {
+  /**
+   * 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 = /* @__PURE__ */ Object.create(null);
+  }
+  /**
+   * Throw an HttpError.
+   *
+   * @param {number} status
+   * @param {string|{message?: string, cause?: any, headers?: HeadersInit}} [messageOrOptions]
+   * @throws {HttpError}
+   * @public
+   */
+  throw(...args) {
+    throw new import_http_error.default(...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 import_http_error.default(...args);
+  }
+  /**
+   * Default error handling and response builder.
+   * @param {Error} err
+   * @returns {Response}
+   * @private
+   */
+  onerror(err) {
+    const { res } = this;
+    const isNativeError = Object.prototype.toString.call(err) === "[object Error]" || err instanceof Error;
+    if (!isNativeError) err = 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" || !import_utils.statusTextMapping[status]) status = 500;
+    const message = import_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
+    });
+  }
+  /**
+   * Return JSON representation of the context.
+   * @returns {CtxJSON}
+   * @public
+   */
+  toJSON() {
+    return {
+      app: this.app.toJSON(),
+      req: this.req.toJSON(),
+      res: this.res.toJSON()
+    };
+  }
+}

package/dist/cjs/lib/compose.js

@@ -0,0 +1,40 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var compose_exports = {};
+__export(compose_exports, {
+  default: () => compose
+});
+module.exports = __toCommonJS(compose_exports);
+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)();
+};
+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);
+}

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

@@ -0,0 +1,61 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var http_error_exports = {};
+__export(http_error_exports, {
+  default: () => HttpError
+});
+module.exports = __toCommonJS(http_error_exports);
+var import_utils = require("./utils.js");
+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} When status is not an integer
+   */
+  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 ?? import_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);
+    }
+  }
+}