hoa 0.0.1 → 0.1.1

package/dist/esm/response.js

@@ -0,0 +1,361 @@
+import { statusTextMapping, statusEmptyMapping, statusRedirectMapping, commonTypeMapping, encodeUrl } from "./lib/utils.js";
+class HoaResponse {
+  /**
+   * 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 200 if not explicitly set.
+   *
+   * @returns {number} The HTTP status code
+   * @public
+   */
+  get status() {
+    return this._status || 200;
+  }
+  /**
+   * 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} When status code is not an integer
+   * @throws {TypeError} When status code is out of valid range (100–599)
+   * @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 = statusTextMapping[val];
+    }
+    if (this.body && 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 = 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 (!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", encodeUrl(url));
+    if (!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;
+      }
+      const url = new URL(referrer, this.req.href);
+      if (url.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(type) {
+    if (!type) return;
+    type = commonTypeMapping[type] || type;
+    this.set("Content-Type", type);
+  }
+  /**
+   * 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}
+   * @public
+   */
+  toJSON() {
+    return {
+      status: this.status,
+      statusText: this.statusText,
+      headers: this.headers
+    };
+  }
+}
+export {
+  HoaResponse as default
+};

package/package.json

@@ -1,12 +1,67 @@
 {
   "name": "hoa",
-  "version": "0.0.1",
-  "description": "",
-  "main": "index.js",
+  "version": "0.1.1",
+  "description": "A minimal web framework built on Web Standards",
+  "main": "./dist/cjs/application.js",
+  "type": "module",
+  "module": "./dist/esm/application.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"
+    }
+  },
+  "files": [
+    "dist",
+    "types",
+    "CHANGELOG.md"
+  ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "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",
+    "prepare": "husky"
+  },
+  "author": "nswbmw",
+  "license": "MIT",
+  "homepage": "https://hoa-js.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hoa-js/hoa.git"
+  },
+  "keywords": [
+    "web",
+    "app",
+    "http",
+    "application",
+    "framework",
+    "middleware",
+    "nodejs",
+    "deno",
+    "bun",
+    "cloudflare",
+    "serverless",
+    "lambda"
+  ],
+  "devDependencies": {
+    "@commitlint/cli": "20.1.0",
+    "@commitlint/config-conventional": "20.0.0",
+    "eslint": "9.37.0",
+    "globals": "16.4.0",
+    "husky": "9.1.7",
+    "jest": "30.2.0",
+    "neostandard": "0.12.2",
+    "tsup": "8.5.0",
+    "vitepress": "1.6.4"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC"
+  "engines": {
+    "node": ">=20"
+  }
 }

package/types/index.d.ts

@@ -0,0 +1,233 @@
+export type NextFunction = () => Promise<void>;
+
+export interface ApplicationOptions {
+  name?: string;
+}
+
+export type HeaderEntry = readonly [string, string];
+
+export type HoaHeadersInit = Headers | Record<string, string> | Iterable<HeaderEntry>;
+
+export interface AppJSON {
+  name: string;
+}
+
+export interface ReqJSON {
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+}
+
+export interface ResJSON {
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+}
+
+export interface CtxJSON {
+  app: AppJSON;
+  req: ReqJSON;
+  res: ResJSON;
+}
+
+export interface CtxOptions {
+  request?: Request;
+  env?: any;
+  executionCtx?: any;
+}
+
+export interface HttpErrorOptions {
+  message?: string;
+  cause?: unknown;
+  expose?: boolean;
+  headers?: HoaHeadersInit;
+}
+
+export type HoaMiddleware<Ctx extends HoaContext = HoaContext> = (ctx: Ctx, next: NextFunction) => Promise<any> | any;
+
+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>;
+}
+
+export declare class HoaContext {
+  constructor(options?: CtxOptions);
+  app: Application;
+  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;
+  onerror(err: unknown): Response;
+  toJSON(): CtxJSON;
+}
+
+export declare class HoaRequest {
+  app: Application;
+  ctx: HoaContext;
+  res: HoaResponse;
+
+  get url(): URL;
+  set url(value: string | URL);
+
+  get href(): string;
+  set href(value: string);
+
+  get origin(): string;
+  set origin(value: string);
+
+  get protocol(): string;
+  set protocol(value: string);
+
+  get host(): string;
+  set host(value: string);
+
+  get hostname(): string;
+  set hostname(value: string);
+
+  get port(): string;
+  set port(value: string);
+
+  get pathname(): string;
+  set pathname(value: string);
+
+  get search(): string;
+  set search(value: string);
+
+  get hash(): string;
+  set hash(value: string);
+
+  get method(): string;
+  set method(value: string);
+
+  get query(): Record<string, string | string[]>;
+  set query(value: Record<string, string | readonly string[]>);
+
+  get headers(): Record<string, string>;
+  set headers(value: HoaHeadersInit);
+
+  get body(): ReadableStream<Uint8Array> | null;
+  set body(value: any);
+
+  get(field: string): string | null;
+  getSetCookie(): string[];
+  has(field: string): boolean;
+  set(field: string, value: string): void;
+  set(values: Record<string, string>): void;
+  append(field: string, value: string): void;
+  append(values: Record<string, string>): void;
+  delete(field: string): void;
+
+  get ips(): string[];
+  get ip(): string;
+
+  get length(): number | null;
+
+  get type(): string | null;
+
+  blob(): Promise<Blob>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  text(): Promise<string>;
+  json<T = any>(): Promise<T>;
+  formData(): Promise<FormData>;
+  toJSON(): ReqJSON;
+}
+
+export type ResponseBody =
+  | string
+  | Blob
+  | ArrayBuffer
+  | ArrayBufferView
+  | ReadableStream<any>
+  | FormData
+  | URLSearchParams
+  | Response
+  | Record<string, any>
+  | null
+  | undefined;
+
+export declare class HoaResponse {
+  app: Application;
+  ctx: HoaContext;
+  req: HoaRequest;
+
+  get headers(): Record<string, string>;
+  set headers(value: HoaHeadersInit);
+
+  get(field: string): string | null;
+  getSetCookie(): string[];
+  has(field: string): boolean;
+  set(field: string, value: string): void;
+  set(values: Record<string, string>): void;
+  append(field: string, value: string): void;
+  append(values: Record<string, string>): void;
+  delete(field: string): void;
+
+  get status(): number;
+  set status(value: number);
+
+  get statusText(): string;
+  set statusText(value: string);
+
+  get body(): ResponseBody;
+  set body(value: ResponseBody);
+
+  redirect(url: string): void;
+  back(alt?: string): void;
+
+  get type(): string | null;
+  set type(value: string);
+
+  get length(): number | null;
+  set length(value: number | string);
+
+  toJSON(): ResJSON;
+}
+
+export declare class Application {
+  constructor(options?: ApplicationOptions);
+
+  name: string;
+  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 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;