@zentjs/zentjs 0.0.2

package/src/index.mjs

@@ -0,0 +1,33 @@
+/**
+ * ZentJS — Public API exports.
+ * @module zentjs
+ */
+
+export { Zent, zent } from './core/application.mjs';
+export { Context } from './core/context.mjs';
+export { ErrorHandler } from './errors/error-handler.mjs';
+export {
+  BadRequestError,
+  ConflictError,
+  ForbiddenError,
+  HttpError,
+  InternalServerError,
+  MethodNotAllowedError,
+  NotFoundError,
+  TooManyRequestsError,
+  UnauthorizedError,
+  UnprocessableEntityError,
+} from './errors/http-error.mjs';
+export { HOOK_PHASES, Lifecycle } from './hooks/lifecycle.mjs';
+export { ZentRequest } from './http/request.mjs';
+export { ZentResponse } from './http/response.mjs';
+export { compose } from './middleware/pipeline.mjs';
+export { bodyParser } from './plugins/body-parser.mjs';
+export { cors } from './plugins/cors.mjs';
+export { PluginManager } from './plugins/manager.mjs';
+export {
+  requestMetrics,
+  requestMetricsPlugin,
+} from './plugins/request-metrics.mjs';
+export { Router } from './router/index.mjs';
+export { HttpStatus, HttpStatusText } from './utils/http-status.mjs';

package/src/middleware/pipeline.mjs

@@ -0,0 +1,77 @@
+/**
+ * Pipeline — Compõe middlewares no padrão Onion (Koa-style).
+ *
+ * Cada middleware tem a assinatura: async (ctx, next) => {}
+ *   - ctx:  Contexto da requisição (req, res, app, state)
+ *   - next: Função que delega execução para o próximo middleware
+ *
+ * O compose retorna uma função (ctx) => Promise<void> que executa
+ * toda a cadeia na ordem, permitindo lógica "before" e "after" via await next().
+ *
+ * @module middleware/pipeline
+ */
+
+/**
+ * Compõe um array de middlewares em uma única função executável.
+ *
+ * @param {Array<(ctx: object, next: Function) => Promise<void>>} middlewares
+ * @returns {(ctx: object, next?: Function) => Promise<void>}
+ * @throws {TypeError} Se middlewares não for um array
+ * @throws {TypeError} Se algum elemento não for uma função
+ */
+export function compose(middlewares) {
+  if (!Array.isArray(middlewares)) {
+    throw new TypeError('middlewares must be an array');
+  }
+
+  for (let i = 0; i < middlewares.length; i++) {
+    if (typeof middlewares[i] !== 'function') {
+      throw new TypeError(
+        `Middleware at index ${i} must be a function, got ${typeof middlewares[i]}`
+      );
+    }
+  }
+
+  /**
+   * @param {object} ctx - Contexto da requisição
+   * @param {Function} [finalHandler] - Função final opcional (ex: route handler)
+   * @returns {Promise<void>}
+   */
+  return function pipeline(ctx, finalHandler) {
+    let index = -1;
+
+    return dispatch(0);
+
+    /**
+     * Executa o middleware no índice `i`.
+     * @param {number} i
+     * @returns {Promise<void>}
+     */
+    function dispatch(i) {
+      // Proteção contra chamada duplicada de next()
+      if (i <= index) {
+        return Promise.reject(
+          new Error('next() called multiple times in the same middleware')
+        );
+      }
+
+      index = i;
+
+      // Seleciona o middleware atual ou o finalHandler (último da cadeia)
+      const fn = i < middlewares.length ? middlewares[i] : finalHandler;
+
+      // Nenhuma função restante — cadeia termina
+      if (!fn) {
+        return Promise.resolve();
+      }
+
+      try {
+        // Chama fn(ctx, next) onde next() avança para dispatch(i + 1)
+        return Promise.resolve(fn(ctx, dispatch.bind(null, i + 1)));
+      } catch (err) {
+        // Captura erros síncronos lançados pelo middleware
+        return Promise.reject(err);
+      }
+    }
+  };
+}

package/src/plugins/body-parser.mjs

@@ -0,0 +1,165 @@
+/**
+ * bodyParser — Middleware built-in para parsing do body da requisição.
+ *
+ * Suporta:
+ *   - application/json
+ *   - text/plain
+ *   - application/x-www-form-urlencoded
+ *
+ * Não parseia automaticamente requests sem body (GET, HEAD, DELETE, OPTIONS).
+ * O body é populado em ctx.req.body após parsing.
+ *
+ * Decisão (ADR-007): Lazy body parsing — exige middleware explícito.
+ *
+ * @module plugins/body-parser
+ */
+
+import { BadRequestError } from '../errors/http-error.mjs';
+
+/** Métodos HTTP que tipicamente não possuem body */
+const NO_BODY_METHODS = new Set(['GET', 'HEAD', 'DELETE', 'OPTIONS']);
+
+/** Limite padrão de tamanho do body: 1 MB */
+const DEFAULT_LIMIT = 1024 * 1024;
+
+/**
+ * @typedef {object} BodyParserOptions
+ * @property {number} [limit=1048576] - Limite máximo do body em bytes
+ */
+
+/**
+ * @callback MiddlewareNext
+ * @returns {void|Promise<void>}
+ */
+
+/**
+ * @callback BodyParserMiddleware
+ * @param {import('../core/context.mjs').Context} ctx
+ * @param {MiddlewareNext} next
+ * @returns {Promise<void>}
+ */
+
+/**
+ * Lê o body bruto da requisição como Buffer.
+ * Suporta tanto streams reais (IncomingMessage) quanto
+ * objetos mockados pelo inject() (que possuem rawReq.body).
+ *
+ * @param {object} raw - IncomingMessage ou mock
+ * @param {number} limit - Limite máximo em bytes
+ * @returns {Promise<Buffer>}
+ * @throws {Error} Quando body excede o limite configurado (statusCode 413)
+ */
+function readRawBody(raw, limit) {
+  // inject() mock — body já é string, não é stream
+  if (raw.body !== undefined && raw.body !== null) {
+    const buf = Buffer.from(raw.body);
+
+    if (buf.length > limit) {
+      const error = new Error(`Body exceeds size limit of ${limit} bytes`);
+      error.statusCode = 413;
+      throw error;
+    }
+
+    return Promise.resolve(buf);
+  }
+
+  // Stream real (node:http IncomingMessage)
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+
+    raw.on('data', (chunk) => {
+      size += chunk.length;
+
+      if (size > limit) {
+        raw.destroy();
+        const error = new Error(`Body exceeds size limit of ${limit} bytes`);
+        error.statusCode = 413;
+        reject(error);
+        return;
+      }
+
+      chunks.push(chunk);
+    });
+
+    raw.on('end', () => {
+      resolve(Buffer.concat(chunks));
+    });
+
+    raw.on('error', (err) => {
+      reject(err);
+    });
+  });
+}
+
+/**
+ * Parseia o body de acordo com o Content-Type.
+ *
+ * @param {Buffer} buffer - Body bruto
+ * @param {string} contentType - Valor do header Content-Type
+ * @returns {*} Body parseado (objeto, string ou raw)
+ * @throws {SyntaxError} Quando JSON for inválido
+ */
+function parseBody(buffer, contentType) {
+  const type = (contentType || '').toLowerCase();
+
+  if (type.includes('application/json')) {
+    const text = buffer.toString('utf-8');
+
+    if (text.length === 0) return {};
+
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new BadRequestError('Invalid JSON body');
+    }
+  }
+
+  if (type.includes('application/x-www-form-urlencoded')) {
+    const text = buffer.toString('utf-8');
+    return Object.fromEntries(new URLSearchParams(text));
+  }
+
+  if (type.includes('text/')) {
+    return buffer.toString('utf-8');
+  }
+
+  // Tipo desconhecido — retorna buffer como string
+  return buffer.toString('utf-8');
+}
+
+/**
+ * Cria o middleware bodyParser.
+ *
+ * @param {BodyParserOptions} [opts={}]
+ * @returns {BodyParserMiddleware} Middleware (ctx, next) => Promise
+ *
+ * @example
+ * import { bodyParser } from 'zentjs';
+ *
+ * app.use(bodyParser());
+ * app.use(bodyParser({ limit: 512 * 1024 })); // 512 KB
+ */
+export function bodyParser(opts = {}) {
+  const limit = opts.limit ?? DEFAULT_LIMIT;
+
+  return async function bodyParserMiddleware(ctx, next) {
+    // Pula métodos sem body
+    if (NO_BODY_METHODS.has(ctx.req.method)) {
+      return next();
+    }
+
+    const contentType = ctx.req.get('content-type') || '';
+
+    // Sem content-type — pula parsing
+    if (!contentType) {
+      return next();
+    }
+
+    const buffer = await readRawBody(ctx.req.raw, limit);
+
+    ctx.req.body = parseBody(buffer, contentType);
+
+    return next();
+  };
+}

package/src/plugins/cors.mjs

@@ -0,0 +1,183 @@
+/**
+ * cors — Middleware built-in para Cross-Origin Resource Sharing (CORS).
+ *
+ * Suporta:
+ *   - Preflight requests (OPTIONS)
+ *   - Origens configuráveis (string, array, function, '*')
+ *   - Methods, headers, credentials, maxAge, exposedHeaders
+ *
+ * Sem dependências externas.
+ *
+ * @module plugins/cors
+ */
+
+/**
+ * Opções padrão do CORS.
+ * @type {object}
+ */
+const DEFAULTS = {
+  origin: '*',
+  methods: 'GET,HEAD,PUT,PATCH,POST,DELETE',
+  allowedHeaders: null,
+  exposedHeaders: null,
+  credentials: false,
+  maxAge: null,
+};
+
+/**
+ * @callback CorsOriginResolver
+ * @param {string} requestOrigin
+ * @returns {string|false|Promise<string|false>}
+ */
+
+/**
+ * @typedef {object} CorsOptions
+ * @property {string|string[]|CorsOriginResolver|boolean} [origin='*']
+ * @property {string|string[]} [methods='GET,HEAD,PUT,PATCH,POST,DELETE']
+ * @property {string|string[]|null} [allowedHeaders=null]
+ * @property {string|string[]|null} [exposedHeaders=null]
+ * @property {boolean} [credentials=false]
+ * @property {number|null} [maxAge=null]
+ */
+
+/**
+ * @callback MiddlewareNext
+ * @returns {void|Promise<void>}
+ */
+
+/**
+ * @callback CorsMiddleware
+ * @param {import('../core/context.mjs').Context} ctx
+ * @param {MiddlewareNext} next
+ * @returns {Promise<void>}
+ */
+
+/**
+ * Resolve o valor de origin a partir da configuração.
+ *
+ * @param {string|string[]|CorsOriginResolver|boolean} origin - Config de origin
+ * @param {string} requestOrigin - Origin do request (header)
+ * @returns {Promise<string|false>} Header Access-Control-Allow-Origin ou false
+ */
+async function resolveOrigin(origin, requestOrigin) {
+  if (origin === true || origin === '*') {
+    return '*';
+  }
+
+  if (origin === false) {
+    return false;
+  }
+
+  if (typeof origin === 'string') {
+    return origin;
+  }
+
+  if (Array.isArray(origin)) {
+    return origin.includes(requestOrigin) ? requestOrigin : false;
+  }
+
+  if (typeof origin === 'function') {
+    return origin(requestOrigin);
+  }
+
+  return false;
+}
+
+/**
+ * Configura os headers de CORS na resposta.
+ *
+ * @param {object} ctx - Contexto da requisição
+ * @param {object} opts - Opções CORS resolvidas
+ * @param {string} allowOrigin - Valor do Access-Control-Allow-Origin
+ */
+function setCorsHeaders(ctx, opts, allowOrigin) {
+  ctx.res.header('Access-Control-Allow-Origin', allowOrigin);
+
+  if (opts.credentials) {
+    ctx.res.header('Access-Control-Allow-Credentials', 'true');
+  }
+
+  if (opts.exposedHeaders) {
+    const value = Array.isArray(opts.exposedHeaders)
+      ? opts.exposedHeaders.join(', ')
+      : opts.exposedHeaders;
+    ctx.res.header('Access-Control-Expose-Headers', value);
+  }
+}
+
+/**
+ * Configura headers adicionais para preflight (OPTIONS).
+ *
+ * @param {object} ctx - Contexto da requisição
+ * @param {object} opts - Opções CORS resolvidas
+ */
+function setPreflightHeaders(ctx, opts) {
+  // Methods
+  const methods = Array.isArray(opts.methods)
+    ? opts.methods.join(', ')
+    : opts.methods;
+  ctx.res.header('Access-Control-Allow-Methods', methods);
+
+  // Allowed Headers
+  if (opts.allowedHeaders) {
+    const headers = Array.isArray(opts.allowedHeaders)
+      ? opts.allowedHeaders.join(', ')
+      : opts.allowedHeaders;
+    ctx.res.header('Access-Control-Allow-Headers', headers);
+  } else {
+    // Reflect request headers
+    const requestHeaders = ctx.req.get('access-control-request-headers');
+    if (requestHeaders) {
+      ctx.res.header('Access-Control-Allow-Headers', requestHeaders);
+    }
+  }
+
+  // Max Age
+  if (opts.maxAge !== null && opts.maxAge !== undefined) {
+    ctx.res.header('Access-Control-Max-Age', String(opts.maxAge));
+  }
+}
+
+/**
+ * Cria o middleware CORS.
+ *
+ * @param {CorsOptions} [opts={}]
+ * @returns {CorsMiddleware} Middleware (ctx, next) => Promise
+ *
+ * @example
+ * import { cors } from 'zentjs';
+ *
+ * app.use(cors());
+ * app.use(cors({ origin: 'https://example.com', credentials: true }));
+ * app.use(cors({ origin: ['https://a.com', 'https://b.com'] }));
+ */
+export function cors(opts = {}) {
+  const config = { ...DEFAULTS, ...opts };
+
+  return async function corsMiddleware(ctx, next) {
+    const requestOrigin = ctx.req.get('origin') || '';
+
+    const allowOrigin = await resolveOrigin(config.origin, requestOrigin);
+
+    // Origin não permitida — prossegue sem headers CORS
+    if (allowOrigin === false) {
+      return next();
+    }
+
+    // Configura headers base de CORS
+    setCorsHeaders(ctx, config, allowOrigin);
+
+    // Vary header para caches
+    if (allowOrigin !== '*') {
+      ctx.res.header('Vary', 'Origin');
+    }
+
+    // Preflight (OPTIONS)
+    if (ctx.req.method === 'OPTIONS') {
+      setPreflightHeaders(ctx, config);
+      return ctx.res.empty(204);
+    }
+
+    return next();
+  };
+}

package/src/plugins/manager.mjs

@@ -0,0 +1,112 @@
+/**
+ * PluginManager — Gerencia registro e carregamento de plugins.
+ *
+ * Cada plugin é uma função assíncrona que recebe uma instância
+ * encapsulada do app e opções. Plugins podem registrar rotas,
+ * hooks, middlewares e decorators sem vazar para o escopo pai.
+ *
+ * Inspirado no sistema de plugins do Fastify.
+ *
+ * @module plugins/manager
+ */
+
+/**
+ * @typedef {object} PluginEntry
+ * @property {PluginFunction} fn - Função do plugin
+ * @property {object} opts - Opções passadas ao plugin
+ */
+
+/**
+ * @callback PluginFunction
+ * @param {object} app - Escopo encapsulado com API do app
+ * @param {object} opts - Opções recebidas no register
+ * @returns {void|Promise<void>}
+ */
+
+/**
+ * @callback CreateScopeFunction
+ * @param {object} opts - Opções do plugin atual
+ * @returns {object} Escopo encapsulado para o plugin
+ */
+
+/**
+ * Gerenciador de plugins com suporte a encapsulamento de escopo.
+ * Responsabilidade única: registrar, ordenar e carregar plugins.
+ */
+export class PluginManager {
+  /** @type {PluginEntry[]} */
+  #queue;
+
+  /** @type {boolean} */
+  #loaded;
+
+  constructor() {
+    this.#queue = [];
+    this.#loaded = false;
+  }
+
+  /**
+   * Indica se os plugins já foram carregados.
+   * @returns {boolean}
+   */
+  get loaded() {
+    return this.#loaded;
+  }
+
+  /**
+   * Registra um plugin para ser carregado posteriormente.
+   *
+   * @param {PluginFunction} fn - async (app, opts) => {}
+   * @param {object} [opts={}] - Opções do plugin (prefix, etc.)
+   * @throws {TypeError} Se fn não for uma função
+   * @throws {Error} Se plugins já foram carregados
+   */
+  register(fn, opts = {}) {
+    if (typeof fn !== 'function') {
+      throw new TypeError(`Plugin must be a function, got ${typeof fn}`);
+    }
+
+    if (this.#loaded) {
+      throw new Error(
+        'Cannot register plugins after they have been loaded. ' +
+          'Call register() before listen().'
+      );
+    }
+
+    this.#queue.push({ fn, opts });
+  }
+
+  /**
+   * Carrega todos os plugins registrados sequencialmente.
+   * Cada plugin recebe uma instância encapsulada via `createScope`.
+   *
+   * @param {CreateScopeFunction} createScope - (opts) => encapsulatedApp
+   * @throws {TypeError} Se createScope não for uma função
+   * @throws {Error} Se já foi carregado anteriormente
+   */
+  async load(createScope) {
+    if (typeof createScope !== 'function') {
+      throw new TypeError('createScope must be a function');
+    }
+
+    if (this.#loaded) {
+      throw new Error('Plugins have already been loaded');
+    }
+
+    for (const entry of this.#queue) {
+      const scopedApp = createScope(entry.opts);
+
+      await entry.fn(scopedApp, entry.opts);
+    }
+
+    this.#loaded = true;
+  }
+
+  /**
+   * Retorna o número de plugins registrados.
+   * @returns {number}
+   */
+  get size() {
+    return this.#queue.length;
+  }
+}

package/src/plugins/request-metrics.mjs

@@ -0,0 +1,74 @@
+/**
+ * requestMetrics — Plugin de observabilidade mínima baseado em hooks.
+ *
+ * Registra hooks de onRequest/onResponse para capturar:
+ * - method
+ * - path
+ * - statusCode
+ * - durationMs
+ *
+ * @module plugins/request-metrics
+ */
+
+/**
+ * @typedef {object} RequestMetricRecord
+ * @property {string} method
+ * @property {string} path
+ * @property {number} statusCode
+ * @property {number} durationMs
+ */
+
+/**
+ * @typedef {object} RequestMetricsOptions
+ * @property {(record: RequestMetricRecord, ctx: object) => void | Promise<void>} [onRecord]
+ * @property {() => bigint} [clock]
+ * @property {string} [stateKey]
+ */
+
+/**
+ * Cria hooks para coletar métricas por requisição.
+ *
+ * @param {RequestMetricsOptions} [opts={}]
+ * @returns {{ onRequest: Function, onResponse: Function }}
+ */
+export function requestMetrics(opts = {}) {
+  const onRecord = opts.onRecord || (async () => {});
+  const clock = opts.clock || process.hrtime.bigint;
+  const stateKey = opts.stateKey || '__zent_request_metrics_start';
+
+  return {
+    async onRequest(ctx) {
+      ctx.state[stateKey] = clock();
+    },
+
+    async onResponse(ctx) {
+      const start = ctx.state[stateKey];
+      if (typeof start !== 'bigint') return;
+
+      const durationMs = Number(clock() - start) / 1_000_000;
+
+      const record = {
+        method: ctx.req.method,
+        path: ctx.req.path,
+        statusCode: ctx.res.statusCode,
+        durationMs,
+      };
+
+      await onRecord(record, ctx);
+    },
+  };
+}
+
+/**
+ * Cria plugin escopado para registrar hooks de requestMetrics.
+ * @param {RequestMetricsOptions} [opts={}]
+ * @returns {(app: object) => Promise<void>}
+ */
+export function requestMetricsPlugin(opts = {}) {
+  const hooks = requestMetrics(opts);
+
+  return async function registerRequestMetrics(app) {
+    app.addHook('onRequest', hooks.onRequest);
+    app.addHook('onResponse', hooks.onResponse);
+  };
+}