hoa 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## v0.2.0 / 2025-10-12
+
+- refactor: rename Application to Hoa
+- docs: update jsdoc comments
+
 ## v0.1.2 / 2025-10-09
 
 - fix: change default status code from 200 to 404

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
   <a href="https://hoa-js.com">
-    <img src="https://raw.githubusercontent.com/hoa-js/hoa/master/logo.png" width="400" height="400" alt="Hoa"/>
+    <img src="https://raw.githubusercontent.com/hoa-js/website/master/logo.png" width="400" height="400" alt="Hoa"/>
   </a>
 </div>
 

package/dist/cjs/context.js

@@ -51,8 +51,8 @@ class HoaContext {
   /**
    * Throw an HttpError.
    *
-   * @param {number} status
-   * @param {string|{message?: string, cause?: any, headers?: HeadersInit}} [messageOrOptions]
+   * @param {number} status - HTTP status code
+   * @param {string|{message?: string, cause?: any, headers?: HeadersInit}} [messageOrOptions] - Error message or options object
    * @throws {HttpError}
    * @public
    */
@@ -73,8 +73,9 @@ class HoaContext {
   }
   /**
    * Default error handling and response builder.
-   * @param {Error} err
-   * @returns {Response}
+   *
+   * @param {Error} err - Error to handle
+   * @returns {Response} Web Standard Response object
    * @private
    */
   onerror(err) {
@@ -98,7 +99,8 @@ class HoaContext {
   }
   /**
    * Return JSON representation of the context.
-   * @returns {CtxJSON}
+   *
+   * @returns {CtxJSON} JSON representation of context
    * @public
    */
   toJSON() {

package/dist/cjs/{application.js → hoa.js}

@@ -25,26 +25,26 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var application_exports = {};
-__export(application_exports, {
-  Hoa: () => Application,
+var hoa_exports = {};
+__export(hoa_exports, {
+  Hoa: () => Hoa,
   HoaContext: () => import_context.default,
   HoaRequest: () => import_request.default,
   HoaResponse: () => import_response.default,
   HttpError: () => import_http_error.default,
   compose: () => import_compose.default,
-  default: () => Application
+  default: () => Hoa
 });
-module.exports = __toCommonJS(application_exports);
+module.exports = __toCommonJS(hoa_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 {
+class Hoa {
   /**
-   * Create an Application instance.
+   * Create an Hoa instance.
    *
    * @param {Object} [options={}] - Application options
    * @param {string} [options.name='Hoa'] - Application name for identification
@@ -59,9 +59,10 @@ class Application {
   }
   /**
    * 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
+   *
+   * @param {HoaExtend} fn - Plugin function that receives the app instance
+   * @returns {Hoa} The Hoa instance for method chaining
+   * @throws {TypeError}
    * @public
    */
   extend(fn) {
@@ -73,9 +74,10 @@ class Application {
   }
   /**
    * 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
+   *
+   * @param {HoaMiddleware} fn - Middleware function
+   * @returns {Hoa} The Hoa instance for method chaining
+   * @throws {TypeError}
    * @public
    */
   use(fn) {
@@ -93,7 +95,7 @@ class Application {
    * @param {Request} request - Web Standard Request object
    * @param {any} [env] - Environment variables (platform-specific)
    * @param {any} [executionCtx] - Execution context (platform-specific)
-   * @returns {Promise<Response>}
+   * @returns {Promise<Response>} Web Standard Response object
    * @public
    */
   fetch(request, env, executionCtx) {
@@ -106,8 +108,8 @@ class Application {
    * Manages error handling and response building.
    *
    * @param {HoaContext} ctx - Request context
-   * @param {(ctx: HoaContext) => Promise<void>} middlewareFn - Composed middleware function
-   * @returns {Promise<Response>}
+   * @param {HoaMiddleware} middlewareFn - Composed middleware function
+   * @returns {Promise<Response>} Web Standard Response object
    * @private
    */
   handleRequest(ctx, middlewareFn) {
@@ -122,7 +124,7 @@ class Application {
    * @param {Request} request - Web Standard Request object
    * @param {any} [env] - Environment variables
    * @param {any} [executionCtx] - Execution context
-   * @returns {HoaContext}
+   * @returns {HoaContext} Created context instance
    * @private
    */
   createContext(request, env, executionCtx) {
@@ -141,7 +143,8 @@ class Application {
    *
    * @param {Error} err - Error to handle
    * @param {HoaContext} [ctx] - Request context (optional)
-   * @throws {TypeError} When err is not a proper Error object
+   * @returns {void}
+   * @throws {TypeError}
    * @private
    */
   onerror(err, ctx) {
@@ -159,16 +162,16 @@ ${msg.replace(/^/gm, "  ")}
   /**
    * ESM/CJS interop helper for default exports.
    *
-   * @returns {typeof Application}
+   * @returns {typeof Hoa} The Hoa class
    * @static
    */
   static get default() {
-    return Application;
+    return Hoa;
   }
   /**
    * Return JSON representation of the app.
    *
-   * @returns {AppJSON}
+   * @returns {AppJSON} JSON representation of application
    * @public
    */
   toJSON() {

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

@@ -28,7 +28,7 @@ class HttpError extends Error {
    * @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
+   * @throws {TypeError}
    */
   constructor(status, message, options) {
     if (!Number.isInteger(status)) {

package/dist/cjs/request.js

@@ -513,7 +513,7 @@ class HoaRequest {
    * This method can only be called once per request.
    *
    * @returns {Promise<any>} The parsed JSON data
-   * @throws {SyntaxError} When the body is not valid JSON
+   * @throws {SyntaxError}
    * @public
    */
   async json() {
@@ -533,7 +533,7 @@ class HoaRequest {
   /**
    * Return JSON representation of the request.
    *
-   * @returns {ReqJSON}
+   * @returns {ReqJSON} JSON representation of request
    * @public
    */
   toJSON() {

package/dist/cjs/response.js

@@ -160,8 +160,7 @@ class HoaResponse {
    * Automatically clears body for status codes that should not have content.
    *
    * @param {number} val - The HTTP status code (100-599)
-   * @throws {TypeError} When status code is not an integer
-   * @throws {TypeError} When status code is out of valid range (100–599)
+   * @throws {TypeError}
    * @public
    */
   set status(val) {
@@ -367,7 +366,7 @@ class HoaResponse {
   /**
    * Return JSON representation of the response.
    *
-   * @returns {ResJSON}
+   * @returns {ResJSON} JSON representation of response
    * @public
    */
   toJSON() {

package/dist/esm/context.js

@@ -19,8 +19,8 @@ class HoaContext {
   /**
    * Throw an HttpError.
    *
-   * @param {number} status
-   * @param {string|{message?: string, cause?: any, headers?: HeadersInit}} [messageOrOptions]
+   * @param {number} status - HTTP status code
+   * @param {string|{message?: string, cause?: any, headers?: HeadersInit}} [messageOrOptions] - Error message or options object
    * @throws {HttpError}
    * @public
    */
@@ -41,8 +41,9 @@ class HoaContext {
   }
   /**
    * Default error handling and response builder.
-   * @param {Error} err
-   * @returns {Response}
+   *
+   * @param {Error} err - Error to handle
+   * @returns {Response} Web Standard Response object
    * @private
    */
   onerror(err) {
@@ -66,7 +67,8 @@ class HoaContext {
   }
   /**
    * Return JSON representation of the context.
-   * @returns {CtxJSON}
+   *
+   * @returns {CtxJSON} JSON representation of context
    * @public
    */
   toJSON() {

package/dist/esm/{application.js → hoa.js}

@@ -4,9 +4,9 @@ import { statusEmptyMapping } from "./lib/utils.js";
 import HoaContext from "./context.js";
 import HoaRequest from "./request.js";
 import HoaResponse from "./response.js";
-class Application {
+class Hoa {
   /**
-   * Create an Application instance.
+   * Create an Hoa instance.
    *
    * @param {Object} [options={}] - Application options
    * @param {string} [options.name='Hoa'] - Application name for identification
@@ -21,9 +21,10 @@ class Application {
   }
   /**
    * 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
+   *
+   * @param {HoaExtend} fn - Plugin function that receives the app instance
+   * @returns {Hoa} The Hoa instance for method chaining
+   * @throws {TypeError}
    * @public
    */
   extend(fn) {
@@ -35,9 +36,10 @@ class Application {
   }
   /**
    * 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
+   *
+   * @param {HoaMiddleware} fn - Middleware function
+   * @returns {Hoa} The Hoa instance for method chaining
+   * @throws {TypeError}
    * @public
    */
   use(fn) {
@@ -55,7 +57,7 @@ class Application {
    * @param {Request} request - Web Standard Request object
    * @param {any} [env] - Environment variables (platform-specific)
    * @param {any} [executionCtx] - Execution context (platform-specific)
-   * @returns {Promise<Response>}
+   * @returns {Promise<Response>} Web Standard Response object
    * @public
    */
   fetch(request, env, executionCtx) {
@@ -68,8 +70,8 @@ class Application {
    * Manages error handling and response building.
    *
    * @param {HoaContext} ctx - Request context
-   * @param {(ctx: HoaContext) => Promise<void>} middlewareFn - Composed middleware function
-   * @returns {Promise<Response>}
+   * @param {HoaMiddleware} middlewareFn - Composed middleware function
+   * @returns {Promise<Response>} Web Standard Response object
    * @private
    */
   handleRequest(ctx, middlewareFn) {
@@ -84,7 +86,7 @@ class Application {
    * @param {Request} request - Web Standard Request object
    * @param {any} [env] - Environment variables
    * @param {any} [executionCtx] - Execution context
-   * @returns {HoaContext}
+   * @returns {HoaContext} Created context instance
    * @private
    */
   createContext(request, env, executionCtx) {
@@ -103,7 +105,8 @@ class Application {
    *
    * @param {Error} err - Error to handle
    * @param {HoaContext} [ctx] - Request context (optional)
-   * @throws {TypeError} When err is not a proper Error object
+   * @returns {void}
+   * @throws {TypeError}
    * @private
    */
   onerror(err, ctx) {
@@ -121,16 +124,16 @@ ${msg.replace(/^/gm, "  ")}
   /**
    * ESM/CJS interop helper for default exports.
    *
-   * @returns {typeof Application}
+   * @returns {typeof Hoa} The Hoa class
    * @static
    */
   static get default() {
-    return Application;
+    return Hoa;
   }
   /**
    * Return JSON representation of the app.
    *
-   * @returns {AppJSON}
+   * @returns {AppJSON} JSON representation of application
    * @public
    */
   toJSON() {
@@ -197,11 +200,11 @@ function respond(ctx) {
   });
 }
 export {
-  Application as Hoa,
+  Hoa,
   HoaContext,
   HoaRequest,
   HoaResponse,
   HttpError,
   compose,
-  Application as default
+  Hoa as default
 };

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

@@ -6,7 +6,7 @@ class HttpError extends Error {
    * @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
+   * @throws {TypeError}
    */
   constructor(status, message, options) {
     if (!Number.isInteger(status)) {

package/dist/esm/request.js

@@ -491,7 +491,7 @@ class HoaRequest {
    * This method can only be called once per request.
    *
    * @returns {Promise<any>} The parsed JSON data
-   * @throws {SyntaxError} When the body is not valid JSON
+   * @throws {SyntaxError}
    * @public
    */
   async json() {
@@ -511,7 +511,7 @@ class HoaRequest {
   /**
    * Return JSON representation of the request.
    *
-   * @returns {ReqJSON}
+   * @returns {ReqJSON} JSON representation of request
    * @public
    */
   toJSON() {

package/dist/esm/response.js

@@ -138,8 +138,7 @@ class HoaResponse {
    * Automatically clears body for status codes that should not have content.
    *
    * @param {number} val - The HTTP status code (100-599)
-   * @throws {TypeError} When status code is not an integer
-   * @throws {TypeError} When status code is out of valid range (100–599)
+   * @throws {TypeError}
    * @public
    */
   set status(val) {
@@ -345,7 +344,7 @@ class HoaResponse {
   /**
    * Return JSON representation of the response.
    *
-   * @returns {ResJSON}
+   * @returns {ResJSON} JSON representation of response
    * @public
    */
   toJSON() {

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "hoa",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "A minimal web framework built on Web Standards",
-  "main": "./dist/cjs/application.js",
+  "main": "./dist/cjs/hoa.js",
   "type": "module",
-  "module": "./dist/esm/application.js",
+  "module": "./dist/esm/hoa.js",
   "types": "./types/index.d.ts",
   "exports": {
     ".": {
       "types": "./types/index.d.ts",
-      "import": "./dist/esm/application.js",
-      "require": "./dist/cjs/application.js",
-      "default": "./dist/esm/application.js"
+      "import": "./dist/esm/hoa.js",
+      "require": "./dist/cjs/hoa.js",
+      "default": "./dist/esm/hoa.js"
     }
   },
   "files": [
@@ -21,9 +21,6 @@
   ],
   "scripts": {
     "lint": "eslint .",
-    "docs:dev": "vitepress dev",
-    "docs:build": "vitepress build",
-    "docs:preview": "vitepress preview",
     "build": "tsup",
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
     "prepublishOnly": "npm run lint && npm run test && npm run build",
@@ -58,8 +55,7 @@
     "husky": "9.1.7",
     "jest": "30.2.0",
     "neostandard": "0.12.2",
-    "tsup": "8.5.0",
-    "vitepress": "1.6.4"
+    "tsup": "8.5.0"
   },
   "engines": {
     "node": ">=20"

package/types/index.d.ts

@@ -1,75 +1,67 @@
-export type NextFunction = () => Promise<void>;
-
-export interface ApplicationOptions {
-  name?: string;
+interface AppJSON {
+  name: string;
 }
 
-export type HeaderEntry = readonly [string, string];
-
-export type HoaHeadersInit = Headers | Record<string, string> | Iterable<HeaderEntry>;
-
-export interface AppJSON {
-  name: string;
+interface CtxJSON {
+  app: AppJSON;
+  req: ReqJSON;
+  res: ResJSON;
 }
 
-export interface ReqJSON {
+interface ReqJSON {
   method: string;
   url: string;
   headers: Record<string, string>;
 }
 
-export interface ResJSON {
+interface ResJSON {
   status: number;
   statusText: string;
   headers: Record<string, string>;
 }
 
-export interface CtxJSON {
-  app: AppJSON;
-  req: ReqJSON;
-  res: ResJSON;
-}
+export type HoaExtend = (app: Hoa) => void;
 
-export interface CtxOptions {
-  request?: Request;
-  env?: any;
-  executionCtx?: any;
-}
+export type HoaMiddleware = (ctx: HoaContext, next?: () => Promise<void>) => Promise<void> | void;
 
-export interface HttpErrorOptions {
-  message?: string;
-  cause?: unknown;
-  expose?: boolean;
-  headers?: HoaHeadersInit;
-}
+export declare class Hoa {
+  constructor(options?: { name?: string });
 
-export type HoaMiddleware<Ctx extends HoaContext = HoaContext> = (ctx: Ctx, next: NextFunction) => Promise<any> | any;
+  name: string;
+  silent?: boolean;
+  readonly HoaContext: typeof HoaContext;
+  readonly HoaRequest: typeof HoaRequest;
+  readonly HoaResponse: typeof HoaResponse;
+  readonly middlewares: HoaMiddleware[];
 
-export declare class HttpError extends Error {
-  constructor(status: number, message?: string | HttpErrorOptions, options?: HttpErrorOptions);
-  readonly status: number;
-  readonly statusCode: number;
-  readonly expose: boolean;
-  readonly headers?: Record<string, string>;
+  extend(fn: HoaExtend): this;
+  use(fn: HoaMiddleware): this;
+  fetch(request: Request, env?: any, executionCtx?: any): Promise<Response>;
+  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;
+
+  static get default(): typeof Hoa;
 }
 
 export declare class HoaContext {
-  constructor(options?: CtxOptions);
-  app: Application;
+  constructor(options?: { request?: Request; env?: any; executionCtx?: any });
+  app: Hoa;
   req: HoaRequest;
   res: HoaResponse;
   request?: Request;
   env?: any;
   executionCtx?: any;
   state: Record<string, any>;
-  throw(status: number, message?: string | HttpErrorOptions, options?: HttpErrorOptions): never;
-  assert<T>(value: T, status: number, message?: string | HttpErrorOptions, options?: HttpErrorOptions): asserts value;
+  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>;
   onerror(err: unknown): Response;
   toJSON(): CtxJSON;
 }
 
 export declare class HoaRequest {
-  app: Application;
+  app: Hoa;
   ctx: HoaContext;
   res: HoaResponse;
 
@@ -107,10 +99,10 @@ export declare class HoaRequest {
   set method(value: string);
 
   get query(): Record<string, string | string[]>;
-  set query(value: Record<string, string | readonly string[]>);
+  set query(value: Record<string, string | string[]>);
 
   get headers(): Record<string, string>;
-  set headers(value: HoaHeadersInit);
+  set headers(value: Headers | Record<string, string> | Iterable<readonly [string, string]>);
 
   get body(): ReadableStream<Uint8Array> | null;
   set body(value: any);
@@ -139,7 +131,7 @@ export declare class HoaRequest {
   toJSON(): ReqJSON;
 }
 
-export type ResponseBody =
+type ResponseBody =
   | string
   | Blob
   | ArrayBuffer
@@ -153,12 +145,12 @@ export type ResponseBody =
   | undefined;
 
 export declare class HoaResponse {
-  app: Application;
+  app: Hoa;
   ctx: HoaContext;
   req: HoaRequest;
 
   get headers(): Record<string, string>;
-  set headers(value: HoaHeadersInit);
+  set headers(value: Headers | Record<string, string> | Iterable<readonly [string, string]>);
 
   get(field: string): string | null;
   getSetCookie(): string[];
@@ -190,45 +182,21 @@ export declare class HoaResponse {
   toJSON(): ResJSON;
 }
 
-export declare class Application {
-  constructor(options?: ApplicationOptions);
-
-  name: string;
-  silent?: boolean;
-  readonly HoaContext: typeof HoaContext;
-  readonly HoaRequest: typeof HoaRequest;
-  readonly HoaResponse: typeof HoaResponse;
-  readonly middlewares: HoaMiddleware[];
-
-  extend(fn: (app: Application) => void): this;
-  use(fn: HoaMiddleware): this;
-  fetch(request: Request, env?: any, executionCtx?: any): Promise<Response>;
-  protected handleRequest(ctx: HoaContext, middlewareFn: (ctx: HoaContext) => Promise<void>): Promise<Response>;
-  protected createContext(request: Request, env?: any, executionCtx?: any): HoaContext;
-  protected onerror(err: unknown, ctx?: HoaContext): void;
-  toJSON(): AppJSON;
-
-  static get default(): typeof Application;
+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]> }
+  );
+  readonly name: string;
+  readonly status: number;
+  readonly statusCode: number;
+  readonly expose: boolean;
+  readonly headers?: Record<string, string>;
 }
 
-export declare function compose<Ctx extends HoaContext = HoaContext>(
-  middlewares: ReadonlyArray<HoaMiddleware<Ctx>> | ReadonlyArray<ReadonlyArray<HoaMiddleware<Ctx>>>
-): (ctx: Ctx, next?: NextFunction) => Promise<void>;
-
-export {
-  ApplicationOptions,
-  AppJSON,
-  CtxJSON,
-  CtxOptions,
-  HoaHeadersInit,
-  HoaMiddleware,
-  HttpErrorOptions,
-  ReqJSON,
-  ResJSON,
-  NextFunction,
-  ResponseBody
-};
-
-export { Application as Hoa, HoaContext, HoaRequest, HoaResponse, HttpError, compose };
-
-export default Application;
+export declare function compose(
+  middlewares: ReadonlyArray<HoaMiddleware> | ReadonlyArray<ReadonlyArray<HoaMiddleware>>
+): HoaMiddleware;
+
+export default Hoa;