@zentjs/zentjs 0.0.2

package/src/core/context.mjs

@@ -0,0 +1,33 @@
+import { ZentRequest } from '../http/request.mjs';
+import { ZentResponse } from '../http/response.mjs';
+
+/**
+ * Objeto de contexto criado por requisição.
+ * Responsabilidade única: agregar req, res, estado e referência ao app.
+ * Serve como único argumento para handlers e middlewares.
+ */
+export class Context {
+  /** @type {ZentRequest} */
+  req;
+
+  /** @type {ZentResponse} */
+  res;
+
+  /** @type {import('./application.mjs').Zent} */
+  app;
+
+  /** @type {Record<string, *>} Espaço livre para middlewares e handlers */
+  state;
+
+  /**
+   * @param {import('node:http').IncomingMessage} rawReq
+   * @param {import('node:http').ServerResponse} rawRes
+   * @param {import('./application.mjs').Zent} app
+   */
+  constructor(rawReq, rawRes, app) {
+    this.req = new ZentRequest(rawReq);
+    this.res = new ZentResponse(rawRes);
+    this.app = app;
+    this.state = {};
+  }
+}

package/src/errors/error-handler.mjs

@@ -0,0 +1,88 @@
+/**
+ * ErrorHandler — Handler centralizado de erros para o framework.
+ *
+ * Responsabilidades:
+ *   - Converter qualquer erro em uma resposta HTTP coerente
+ *   - Suportar handler customizado definido pelo usuário
+ *   - Garantir que erros nunca crashem o processo
+ *   - Invocar hooks onError do lifecycle
+ *
+ * @module errors/error-handler
+ */
+
+import { HttpError, InternalServerError } from './http-error.mjs';
+
+/**
+ * Gerencia o tratamento de erros do framework.
+ * O usuário pode fornecer um handler customizado via setErrorHandler().
+ */
+export class ErrorHandler {
+  /** @type {((error: Error, ctx: object) => void | Promise<void>) | null} */
+  #customHandler;
+
+  constructor() {
+    this.#customHandler = null;
+  }
+
+  /**
+   * Define um handler customizado de erros.
+   * O handler recebe (error, ctx) e deve enviar a resposta via ctx.res.
+   *
+   * @param {(error: Error, ctx: object) => void | Promise<void>} fn
+   * @throws {TypeError} Se fn não for uma função
+   */
+  setErrorHandler(fn) {
+    if (typeof fn !== 'function') {
+      throw new TypeError(`Error handler must be a function, got ${typeof fn}`);
+    }
+
+    this.#customHandler = fn;
+  }
+
+  /**
+   * Trata um erro, enviando a resposta HTTP apropriada.
+   *
+   * Fluxo:
+   *   1. Se a resposta já foi enviada, não faz nada
+   *   2. Se existe handler customizado, delega ao handler
+   *   3. Caso contrário, usa o handler padrão do framework
+   *
+   * @param {Error} error - O erro a ser tratado
+   * @param {object} ctx - Contexto da requisição (req, res, app, state)
+   * @returns {Promise<void>}
+   */
+  async handle(error, ctx) {
+    // Se a resposta já foi enviada, não há nada a fazer
+    if (ctx.res.sent) return;
+
+    // Normaliza: erros não-HttpError viram InternalServerError
+    const httpError =
+      error instanceof HttpError
+        ? error
+        : new InternalServerError(error.message || 'Internal Server Error');
+
+    if (this.#customHandler) {
+      try {
+        await this.#customHandler(httpError, ctx);
+      } catch {
+        // Se o handler customizado falhar, usa o padrão
+        this.#defaultHandler(httpError, ctx);
+      }
+      return;
+    }
+
+    this.#defaultHandler(httpError, ctx);
+  }
+
+  /**
+   * Handler padrão — envia resposta JSON com statusCode, error e message.
+   *
+   * @param {HttpError} error
+   * @param {object} ctx
+   */
+  #defaultHandler(error, ctx) {
+    if (ctx.res.sent) return;
+
+    ctx.res.status(error.statusCode).json(error.toJSON());
+  }
+}

package/src/errors/http-error.mjs

@@ -0,0 +1,86 @@
+import { HttpStatus, HttpStatusText } from '../utils/http-status.mjs';
+
+export class HttpError extends Error {
+  static showStackTrace = false;
+
+  constructor(statusCode, message) {
+    super(message);
+    this.statusCode = statusCode;
+    this.error = HttpStatusText[statusCode] || 'Unknown Error';
+    this.name = this.constructor.name;
+
+    if (HttpError.showStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    } else {
+      this.stack = undefined;
+    }
+  }
+
+  toJSON() {
+    const payload = {
+      statusCode: this.statusCode,
+      error: this.error,
+      message: this.message,
+    };
+
+    if (HttpError.showStackTrace && this.stack) {
+      payload.stack = this.stack;
+    }
+
+    return payload;
+  }
+}
+
+export class BadRequestError extends HttpError {
+  constructor(message = 'Bad Request') {
+    super(HttpStatus.BAD_REQUEST, message);
+  }
+}
+
+export class UnauthorizedError extends HttpError {
+  constructor(message = 'Unauthorized') {
+    super(HttpStatus.UNAUTHORIZED, message);
+  }
+}
+
+export class ForbiddenError extends HttpError {
+  constructor(message = 'Forbidden') {
+    super(HttpStatus.FORBIDDEN, message);
+  }
+}
+
+export class NotFoundError extends HttpError {
+  constructor(message = 'Not Found') {
+    super(HttpStatus.NOT_FOUND, message);
+  }
+}
+
+export class MethodNotAllowedError extends HttpError {
+  constructor(message = 'Method Not Allowed') {
+    super(HttpStatus.METHOD_NOT_ALLOWED, message);
+  }
+}
+
+export class ConflictError extends HttpError {
+  constructor(message = 'Conflict') {
+    super(HttpStatus.CONFLICT, message);
+  }
+}
+
+export class UnprocessableEntityError extends HttpError {
+  constructor(message = 'Unprocessable Entity') {
+    super(HttpStatus.UNPROCESSABLE_ENTITY, message);
+  }
+}
+
+export class TooManyRequestsError extends HttpError {
+  constructor(message = 'Too Many Requests') {
+    super(HttpStatus.TOO_MANY_REQUESTS, message);
+  }
+}
+
+export class InternalServerError extends HttpError {
+  constructor(message = 'Internal Server Error') {
+    super(HttpStatus.INTERNAL_SERVER_ERROR, message);
+  }
+}

package/src/hooks/lifecycle.mjs

@@ -0,0 +1,175 @@
+/**
+ * Lifecycle — Gerencia hooks de ciclo de vida da requisição.
+ *
+ * Hooks são executados em fases bem definidas, permitindo
+ * interceptar e modificar o fluxo em cada etapa.
+ *
+ * Fases (ordem de execução):
+ *   1. onRequest    — Primeira fase, antes de qualquer processamento
+ *   2. preParsing   — Antes de parsear o body
+ *   3. preValidation — Antes de validar input
+ *   4. preHandler   — Após validação, antes do handler
+ *   5. onSend       — Antes de enviar a resposta (pode modificar payload)
+ *   6. onResponse   — Após envio da resposta (cleanup, métricas)
+ *   7. onError      — Chamado quando ocorre erro em qualquer fase
+ *
+ * @module hooks/lifecycle
+ */
+
+/** Fases válidas do lifecycle */
+export const HOOK_PHASES = Object.freeze([
+  'onRequest',
+  'preParsing',
+  'preValidation',
+  'preHandler',
+  'onSend',
+  'onResponse',
+  'onError',
+]);
+
+/**
+ * Gerenciador de hooks de lifecycle.
+ * Responsabilidade única: registrar e executar hooks por fase.
+ */
+export class Lifecycle {
+  /** @type {Map<string, Function[]>} */
+  #hooks;
+
+  constructor() {
+    this.#hooks = new Map();
+
+    for (const phase of HOOK_PHASES) {
+      this.#hooks.set(phase, []);
+    }
+  }
+
+  /**
+   * Registra um hook para uma fase do lifecycle.
+   *
+   * @param {string} phase - Nome da fase (ex: 'onRequest', 'preHandler')
+   * @param {Function} fn - Função do hook
+   * @throws {Error} Se a fase não for válida
+   * @throws {TypeError} Se fn não for uma função
+   */
+  addHook(phase, fn) {
+    if (!this.#hooks.has(phase)) {
+      throw new Error(
+        `Invalid hook phase: "${phase}". Valid phases: ${HOOK_PHASES.join(', ')}`
+      );
+    }
+
+    if (typeof fn !== 'function') {
+      throw new TypeError(`Hook must be a function, got ${typeof fn}`);
+    }
+
+    this.#hooks.get(phase).push(fn);
+  }
+
+  /**
+   * Retorna os hooks registrados para uma fase.
+   *
+   * @param {string} phase
+   * @returns {Function[]}
+   */
+  getHooks(phase) {
+    return this.#hooks.get(phase) || [];
+  }
+
+  /**
+   * Verifica se uma fase possui hooks registrados.
+   *
+   * @param {string} phase
+   * @returns {boolean}
+   */
+  hasHooks(phase) {
+    const hooks = this.#hooks.get(phase);
+    return hooks !== undefined && hooks.length > 0;
+  }
+
+  /**
+   * Executa todos os hooks de uma fase sequencialmente.
+   * Cada hook recebe os argumentos passados (tipicamente ctx, ou ctx + payload).
+   *
+   * Para a fase 'onSend', o retorno do hook substitui o payload
+   * (permite transformação encadeada).
+   *
+   * @param {string} phase - Fase do lifecycle
+   * @param {object} ctx - Contexto da requisição
+   * @param {...*} args - Argumentos adicionais (ex: payload para onSend, error para onError)
+   * @returns {Promise<*>} O último payload (para onSend) ou undefined
+   */
+  async run(phase, ctx, ...args) {
+    const hooks = this.getHooks(phase);
+
+    if (hooks.length === 0) return args[0];
+
+    if (phase === 'onSend') {
+      return this.#runOnSend(hooks, ctx, args[0]);
+    }
+
+    if (phase === 'onError') {
+      return this.#runOnError(hooks, ctx, args[0]);
+    }
+
+    // Fases normais: onRequest, preParsing, preValidation, preHandler, onResponse
+    for (const hook of hooks) {
+      await hook(ctx);
+    }
+  }
+
+  /**
+   * Executa hooks de onSend encadeando o payload.
+   * Cada hook pode retornar um payload modificado.
+   *
+   * @param {Function[]} hooks
+   * @param {object} ctx
+   * @param {*} payload
+   * @returns {Promise<*>}
+   */
+  async #runOnSend(hooks, ctx, payload) {
+    let current = payload;
+
+    for (const hook of hooks) {
+      const result = await hook(ctx, current);
+      // Se o hook retornar algo, substitui o payload
+      if (result !== undefined) {
+        current = result;
+      }
+    }
+
+    return current;
+  }
+
+  /**
+   * Executa hooks de onError sequencialmente.
+   * Cada hook recebe (ctx, error).
+   *
+   * @param {Function[]} hooks
+   * @param {object} ctx
+   * @param {Error} error
+   * @returns {Promise<void>}
+   */
+  async #runOnError(hooks, ctx, error) {
+    for (const hook of hooks) {
+      await hook(ctx, error);
+    }
+  }
+
+  /**
+   * Cria uma cópia do lifecycle com os mesmos hooks.
+   * Útil para encapsulamento de plugins (herança de escopo pai).
+   *
+   * @returns {Lifecycle}
+   */
+  clone() {
+    const cloned = new Lifecycle();
+
+    for (const [phase, hooks] of this.#hooks) {
+      for (const hook of hooks) {
+        cloned.addHook(phase, hook);
+      }
+    }
+
+    return cloned;
+  }
+}

package/src/http/request.mjs

@@ -0,0 +1,166 @@
+function resolvePathFromUrl(rawUrl) {
+  if (!rawUrl) return '/';
+
+  const queryIndex = rawUrl.indexOf('?');
+  const path = queryIndex === -1 ? rawUrl : rawUrl.slice(0, queryIndex);
+
+  return path || '/';
+}
+
+function resolveQueryFromUrl(rawUrl) {
+  if (!rawUrl) return {};
+
+  const queryIndex = rawUrl.indexOf('?');
+  if (queryIndex === -1 || queryIndex === rawUrl.length - 1) return {};
+
+  return Object.fromEntries(new URLSearchParams(rawUrl.slice(queryIndex + 1)));
+}
+
+function resolveHostnameFromHostHeader(host) {
+  if (!host) return 'localhost';
+
+  const rawHost = Array.isArray(host) ? host[0] : host;
+  if (!rawHost) return 'localhost';
+
+  if (rawHost.startsWith('[')) {
+    const end = rawHost.indexOf(']');
+    if (end !== -1) {
+      return rawHost.slice(0, end + 1);
+    }
+  }
+
+  const colonIndex = rawHost.indexOf(':');
+  if (colonIndex === -1) return rawHost;
+
+  return rawHost.slice(0, colonIndex);
+}
+
+/**
+ * Wrapper sobre http.IncomingMessage.
+ * Responsabilidade única: leitura e parse dos dados da requisição.
+ */
+export class ZentRequest {
+  /** @type {import('node:http').IncomingMessage} */
+  #raw;
+
+  /** @type {string | undefined} */
+  #pathCache;
+
+  /** @type {Record<string, string> | undefined} */
+  #queryCache;
+
+  /** @type {string | undefined} */
+  #hostnameCache;
+
+  /** @type {Record<string, string>} */
+  #params = {};
+
+  /** @type {*} */
+  #body = undefined;
+
+  /**
+   * @param {import('node:http').IncomingMessage} raw
+   */
+  constructor(raw) {
+    this.#raw = raw;
+    this.#pathCache = undefined;
+    this.#queryCache = undefined;
+    this.#hostnameCache = undefined;
+  }
+
+  /** Objeto IncomingMessage original (escape hatch) */
+  get raw() {
+    return this.#raw;
+  }
+
+  /** @returns {string} Método HTTP em uppercase */
+  get method() {
+    return this.#raw.method;
+  }
+
+  /** @returns {string} URL completa (path + query) */
+  get url() {
+    return this.#raw.url;
+  }
+
+  /** @returns {string} Path sem query string */
+  get path() {
+    if (this.#pathCache === undefined) {
+      this.#pathCache = resolvePathFromUrl(this.#raw.url);
+    }
+
+    return this.#pathCache;
+  }
+
+  /** @returns {Record<string, string>} Query params como objeto */
+  get query() {
+    if (this.#queryCache === undefined) {
+      this.#queryCache = resolveQueryFromUrl(this.#raw.url);
+    }
+
+    return this.#queryCache;
+  }
+
+  /** @returns {import('node:http').IncomingHttpHeaders} */
+  get headers() {
+    return this.#raw.headers;
+  }
+
+  /** @returns {Record<string, string>} Route params populados pelo router */
+  get params() {
+    return this.#params;
+  }
+
+  set params(value) {
+    this.#params = value;
+  }
+
+  /** @returns {string} IP do cliente */
+  get ip() {
+    return this.#raw.socket.remoteAddress;
+  }
+
+  /** @returns {string} Hostname da requisição */
+  get hostname() {
+    if (this.#hostnameCache === undefined) {
+      this.#hostnameCache = resolveHostnameFromHostHeader(
+        this.#raw.headers.host
+      );
+    }
+
+    return this.#hostnameCache;
+  }
+
+  /** @returns {string} 'http' ou 'https' */
+  get protocol() {
+    return this.#raw.socket.encrypted ? 'https' : 'http';
+  }
+
+  /** @returns {*} Body parseado (definido pelo body-parser middleware) */
+  get body() {
+    return this.#body;
+  }
+
+  set body(value) {
+    this.#body = value;
+  }
+
+  /**
+   * Retorna o valor de um header (case-insensitive).
+   * @param {string} name
+   * @returns {string | undefined}
+   */
+  get(name) {
+    return this.#raw.headers[name.toLowerCase()];
+  }
+
+  /**
+   * Verifica se o Content-Type bate com o tipo informado.
+   * @param {string} type - Ex: 'json', 'application/json'
+   * @returns {boolean}
+   */
+  is(type) {
+    const contentType = this.get('content-type') || '';
+    return contentType.includes(type);
+  }
+}

package/src/http/response.mjs

@@ -0,0 +1,151 @@
+import { HttpStatus } from '../utils/http-status.mjs';
+
+const CONTENT_TYPE = 'Content-Type';
+const MIME_JSON = 'application/json; charset=utf-8';
+const MIME_HTML = 'text/html; charset=utf-8';
+const MIME_TEXT = 'text/plain; charset=utf-8';
+
+/**
+ * Wrapper sobre http.ServerResponse.
+ * Responsabilidade única: construção e envio da resposta HTTP.
+ * API fluente (chainable) para status e headers.
+ */
+export class ZentResponse {
+  /** @type {import('node:http').ServerResponse} */
+  #raw;
+
+  /** @type {number} */
+  #statusCode = HttpStatus.OK;
+
+  /**
+   * @param {import('node:http').ServerResponse} raw
+   */
+  constructor(raw) {
+    this.#raw = raw;
+  }
+
+  /** Objeto ServerResponse original (escape hatch) */
+  get raw() {
+    return this.#raw;
+  }
+
+  /** @returns {boolean} Já enviou a resposta? */
+  get sent() {
+    return this.#raw.writableEnded;
+  }
+
+  /** @returns {number} Status code atual */
+  get statusCode() {
+    return this.#statusCode;
+  }
+
+  /**
+   * Define o status code.
+   * @param {number} code
+   * @returns {this}
+   */
+  status(code) {
+    if (this.sent) return this;
+
+    this.#statusCode = code;
+    return this;
+  }
+
+  /**
+   * Define um header.
+   * @param {string} name
+   * @param {string | number} value
+   * @returns {this}
+   */
+  header(name, value) {
+    if (this.sent) return this;
+
+    this.#raw.setHeader(name, value);
+    return this;
+  }
+
+  /**
+   * Atalho para Content-Type.
+   * @param {string} contentType
+   * @returns {this}
+   */
+  type(contentType) {
+    return this.header(CONTENT_TYPE, contentType);
+  }
+
+  /**
+   * Envia resposta JSON.
+   * @param {*} data
+   */
+  json(data) {
+    if (this.sent) return;
+
+    const body = JSON.stringify(data);
+    this.type(MIME_JSON);
+    this.#end(body);
+  }
+
+  /**
+   * Envia string ou Buffer.
+   * @param {string | Buffer} data
+   */
+  send(data) {
+    if (this.sent) return;
+
+    if (!this.#raw.getHeader(CONTENT_TYPE)) {
+      this.type(Buffer.isBuffer(data) ? 'application/octet-stream' : MIME_TEXT);
+    }
+    this.#end(data);
+  }
+
+  /**
+   * Envia resposta HTML.
+   * @param {string} data
+   */
+  html(data) {
+    if (this.sent) return;
+
+    this.type(MIME_HTML);
+    this.#end(data);
+  }
+
+  /**
+   * Redireciona para outra URL.
+   * @param {string} url
+   * @param {number} [code=HttpStatus.FOUND]
+   */
+  redirect(url, code = HttpStatus.FOUND) {
+    if (this.sent) return;
+
+    this.#statusCode = code;
+    this.header('Location', url);
+    this.#end();
+  }
+
+  /**
+   * Resposta sem body.
+   * @param {number} [code=HttpStatus.NO_CONTENT]
+   */
+  empty(code = HttpStatus.NO_CONTENT) {
+    if (this.sent) return;
+
+    this.#statusCode = code;
+    this.#end();
+  }
+
+  /**
+   * Finaliza a resposta. Método interno compartilhado.
+   * @param {string | Buffer} [body]
+   */
+  #end(body) {
+    if (this.sent) return;
+
+    this.#raw.writeHead(this.#statusCode);
+
+    if (body !== undefined) {
+      this.#raw.end(body);
+    } else {
+      this.#raw.end();
+    }
+  }
+}