@ecdt/server-common 1.4.0 → 1.5.0

package/README.md

@@ -155,3 +155,36 @@ app.listen(3000);
 ```
 
 ---
+
+## TypeScript
+
+O pacote publica os tipos em `src/index.d.ts` (declarado em `types` no `package.json`), tipados com `express` e `http`. **Não é necessário declarar `declare module '@ecdt/server-common'` na aplicação** — se você tem um arquivo desses em `src/@types/`, pode apagar: uma declaração ambiente local sombreia os tipos do pacote e passa a mentir em silêncio se as assinaturas divergirem.
+
+```ts
+import express from "express";
+import http from "http";
+import { expressCommonMiddlewares, expressCors, setupRedMetrics, setupGracefulShutdown } from "@ecdt/server-common";
+
+const app = express();
+
+app.use(...expressCommonMiddlewares());              // RequestHandler[]
+app.use(expressCors({ econodataOrigins: true }));    // RequestHandler
+setupRedMetrics(app, { serviceName: "meu-ms" });
+
+const server = http.createServer(app);
+server.listen(3000);
+setupGracefulShutdown(server, { onShutdown: () => pool.end() });
+```
+
+As interfaces de options são exportadas para reuso: `ExpressCommonMiddlewaresOptions`, `ExpressCorsOptions` (e sua base `ExpressCorsOptionsBase`), `GracefulShutdownOptions`, `RedMetricsOptions` e `MetricsRegistry`.
+
+`ExpressCorsOptions` é uma união que exige `origins` e/ou `econodataOrigins: true` — sem nenhum dos dois o `expressCors` lança no boot, então o erro aparece já em compilação:
+
+```ts
+expressCors({ econodataOrigins: true });  // ok
+expressCors({ methods: ["GET"] });        // erro TS2345 — lançaria no boot
+```
+
+`prom-client` aparece nos tipos como a interface estrutural `MetricsRegistry`, e não como `import` do pacote — assim quem não usa métricas compila sem tê-lo instalado.
+
+---

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@ecdt/server-common",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Conjunto de ferramentas e configurações comuns nos servidores da Econodata",
   "main": "src/index.js",
+  "types": "src/index.d.ts",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },

package/src/index.d.ts

@@ -1,75 +1,113 @@
-declare module '@ecdt/server-common' {
-    export interface ExpressCommonMiddlewaresOptions {
-        /**
-         * Nome(s) do cookie de sessão, em ordem de preferência.
-         * Quando omitido, o nome é resolvido por requisição a partir da origem (origin > referer > host):
-         * origens com subdomínio "hml" usam `hml-ecdt_token_site`, as demais usam `ecdt_token_site`.
-         */
-        cookieName?: string | string[];
-    }
+import type { Express, RequestHandler } from 'express';
+import type { Server } from 'http';
 
-    /**
-     * Aplica bodyParser.text(), bodyParser.json(), bodyParser.urlencoded({extended: false}) e devMktTokenSanitaze()
-     * no middleware do express.
-     *
-     * Uso: app.use(...expressCommonMiddlewares())
-     */
-    export function expressCommonMiddlewares(
-        options?: ExpressCommonMiddlewaresOptions
-    ): Array<(req: unknown, res: unknown, next: (err?: unknown) => void) => void>;
+export interface ExpressCommonMiddlewaresOptions {
+  /**
+   * Nome(s) do cookie de sessão, em ordem de preferência.
+   * Quando omitido, o nome é resolvido por requisição a partir da origem (origin > referer > host):
+   * origens com subdomínio "hml" usam `hml-ecdt_token_site`, as demais usam `ecdt_token_site`.
+   */
+  cookieName?: string | string[];
+}
 
-    export interface ExpressCorsOptions {
-        /** Origins permitidas (ex: ["https://app.econodata.com.br"]). Obrigatório se econodataOrigins não for true. */
-        origins?: string[];
-        /** Permite todas as origins https do domínio econodata.com.br (qualquer subdomínio). */
-        econodataOrigins?: boolean;
-        /** Headers adicionais além dos padrões (Authorization, Content-Type, X-Requested-With). */
-        extraHeaders?: string[];
-        /** Lista exata de headers permitidos — substitui os padrões. Não combinar com extraHeaders. */
-        headers?: string[];
-        /** Lista exata de métodos permitidos. Default: todos (GET, HEAD, PUT, PATCH, POST, DELETE, OPTIONS). */
-        methods?: string[];
-    }
+/**
+ * Aplica bodyParser.text(), bodyParser.json(), bodyParser.urlencoded({extended: false}) e
+ * devMktTokenSanitaze() no middleware do express.
+ *
+ * Uso: app.use(...expressCommonMiddlewares())
+ */
+export declare function expressCommonMiddlewares(
+  options?: ExpressCommonMiddlewaresOptions
+): RequestHandler[];
 
-    /**
-     * Cria o middleware de CORS padrão dos servidores Econodata.
-     * Credentials sempre habilitado; origins não listadas não recebem headers CORS.
-     *
-     * Uso: app.use(expressCors({ origins: ["https://app.econodata.com.br"] }))
-     */
-    export function expressCors(options: ExpressCorsOptions): (req: unknown, res: unknown, next: (err?: unknown) => void) => void;
+export interface ExpressCorsOptionsBase {
+  /** Origins permitidas (ex: ["https://app.econodata.com.br"]). */
+  origins?: string[];
+  /** Permite todas as origins https do domínio econodata.com.br (qualquer subdomínio). */
+  econodataOrigins?: boolean;
+  /** Headers adicionais além dos padrões (Authorization, Content-Type, X-Requested-With). */
+  extraHeaders?: string[];
+  /** Lista exata de headers permitidos — substitui os padrões. Não combinar com extraHeaders. */
+  headers?: string[];
+  /** Lista exata de métodos permitidos. Default: todos (GET, HEAD, PUT, PATCH, POST, DELETE, OPTIONS). */
+  methods?: string[];
+}
 
-    export interface RedMetricsOptions {
-        /** Nome do microsserviço. Vira o label `service` em todas as métricas. Fallback: env SERVICE_NAME > npm_package_name. */
-        serviceName?: string;
-        /** Caminho do endpoint de métricas. Default: '/metrics'. */
-        metricsPath?: string;
-        /** Buckets do histograma de latência, em segundos. */
-        buckets?: number[];
-        /** Coletar métricas default do Node (heap, event loop, GC...). Default: true. */
-        collectDefaultMetrics?: boolean;
-        /** Registry alternativo do prom-client. Default: registry global. */
-        registry?: unknown;
-    }
+/**
+ * Exige `origins` e/ou `econodataOrigins: true`: sem nenhum dos dois o expressCors lança no boot,
+ * então a união recusa em compilação o que o runtime já recusa.
+ */
+export type ExpressCorsOptions =
+  | (ExpressCorsOptionsBase & { origins: string[] })
+  | (ExpressCorsOptionsBase & { econodataOrigins: true });
 
-    /**
-     * Configura as métricas RED (Rate, Errors, Duration) no app express: registra o
-     * middleware de medição (antes das rotas) e o endpoint /metrics.
-     *
-     * Alimenta o histograma `http_request_duration_seconds{method,route,status_code}`,
-     * que habilita latência por endpoint, latência total, RPS, erros e top endpoints com erro.
-     *
-     * Requer `prom-client` instalado no microsserviço (peerDependency).
-     *
-     * Uso: setupRedMetrics(app, { serviceName: "dev-mkt-busca" })
-     */
-    export function setupRedMetrics(app: unknown, options?: RedMetricsOptions): void;
+/**
+ * Cria o middleware de CORS padrão dos servidores Econodata.
+ * Credentials sempre habilitado; origins não listadas não recebem headers CORS.
+ *
+ * Uso: app.use(expressCors({ origins: ["https://app.econodata.com.br"] }))
+ */
+export declare function expressCors(options: ExpressCorsOptions): RequestHandler;
 
-    /** Middleware do express que alimenta o histograma `http_request_duration_seconds`. */
-    export function redMetricsMiddleware(
-        options?: Pick<RedMetricsOptions, "buckets" | "registry">
-    ): (req: unknown, res: unknown, next: (err?: unknown) => void) => void;
+export interface GracefulShutdownOptions {
+  /** Cleanup extra (fechar pools, Redis, etc.) executado após o server fechar. */
+  onShutdown?: () => void | Promise<void>;
+  /** Tempo máximo do graceful antes de forçar a saída. Default: 10000 (grace de 40s − 20s de preStop). */
+  failsafeTimeoutMs?: number;
+}
 
-    /** Handler do endpoint de métricas (exposição no formato Prometheus). */
-    export function metricsHandler(registry?: unknown): (req: unknown, res: unknown) => void;
-}
+/**
+ * Registra o graceful shutdown padrão dos microsserviços em Kubernetes: em SIGTERM/SIGINT fecha o
+ * server, drena as conexões em voo, roda o onShutdown e encerra o processo.
+ *
+ * Uso: setupGracefulShutdown(server, { onShutdown: () => pool.end() })
+ */
+export declare function setupGracefulShutdown(
+  server: Server,
+  options?: GracefulShutdownOptions
+): void;
+
+/**
+ * Registry do prom-client, descrito estruturalmente para não acoplar a resolução destes tipos ao
+ * pacote: quem não usa métricas continua compilando sem `prom-client` instalado.
+ */
+export interface MetricsRegistry {
+  contentType: string;
+  metrics(): Promise<string>;
+  setDefaultLabels(labels: Record<string, string>): void;
+  getSingleMetric(name: string): unknown;
+}
+
+export interface RedMetricsOptions {
+  /** Nome do microsserviço. Vira o label `service` em todas as métricas. Fallback: env SERVICE_NAME > npm_package_name. */
+  serviceName?: string;
+  /** Caminho do endpoint de métricas. Default: '/metrics'. */
+  metricsPath?: string;
+  /** Buckets do histograma de latência, em segundos. */
+  buckets?: number[];
+  /** Coletar métricas default do Node (heap, event loop, GC...). Default: true. */
+  collectDefaultMetrics?: boolean;
+  /** Registry alternativo do prom-client. Default: registry global. */
+  registry?: MetricsRegistry;
+}
+
+/**
+ * Configura as métricas RED (Rate, Errors, Duration) no app express: registra o middleware de
+ * medição (antes das rotas) e o endpoint /metrics.
+ *
+ * Alimenta o histograma `http_request_duration_seconds{method,route,status_code}`, que habilita
+ * latência por endpoint, latência total, RPS, erros e top endpoints com erro.
+ *
+ * Requer `prom-client` instalado no microsserviço (peerDependency).
+ *
+ * Uso: setupRedMetrics(app, { serviceName: "dev-mkt-busca" })
+ */
+export declare function setupRedMetrics(app: Express, options?: RedMetricsOptions): void;
+
+/** Middleware do express que alimenta o histograma `http_request_duration_seconds`. */
+export declare function redMetricsMiddleware(
+  options?: Pick<RedMetricsOptions, 'buckets' | 'registry'>
+): RequestHandler;
+
+/** Handler do endpoint de métricas (exposição no formato Prometheus). */
+export declare function metricsHandler(registry?: MetricsRegistry): RequestHandler;