APIs Elysia (stack Astro / feature modules)

Visão geral

Padrão para APIs Bun + Elysia + Drizzle (`pg`) + Zod + Scalar: feature folders, plugins por categoria, bootstrap ordenado, erros centralizados, service/repository separados, configs agrupadas, OpenAPI por <feature>.docs.ts.

Progressive disclosure: manter este SKILL.md como índice enxuto; carregar *`reference/.md** só para o tópico em causa; copiar **templates TypeScript** da raiz desta skill apenas ao implementar. Alinha aos critérios de skills de equipa curadas (metadados curtos, corpo focado, detalhe sob demanda), na linha de repositórios como [VoltAgent/awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills) — secção *Skill Quality Standards* (sem caminhos absolutos de máquina; palavras-chave pesquisáveis na description`).

Mapa de recursos

Quando usar

• Novo serviço ou módulo; PR que mexe em bootstrap, plugins, módulos ou persistência.
• Sintomas: .use() fora de ordem, handler gordo, SQL no service, falta de modules.routes.ts, literais de status, throw new Error em rotas.

Quando não usar

• Stack ou estrutura de pastas do repositório contradiz este padrão — seguir a documentação do projeto.
• App sem HTTP ou sem Elysia.

Padrões centrais

• Bootstrap: error handler primeiro; depois cors → rate limit → helmet → swagger → activity log (se existir) → `modulesRoutes`; index.ts só agrega plugins + modulesRoutes (ver reference/01-stack-and-bootstrap.md).
• Feature folders: src/modules/<feature>/ com sufixos routes, service, repository, schema, types, docs, constants (ver reference/02-modules-and-plugins.md).
• SRP: rota orquestra; service com regras; repository com Drizzle; uma responsabilidade por ficheiro.
• Zod: validação nos handlers; schemas em *.schema.ts; docs OpenAPI em *.docs.ts com spread nas rotas.
• `HTTP_STATUS`: um ficheiro de constantes; set.status = HTTP_STATUS.CREATED (alias HttpStatusCode exportado para compat).
• Erros: onError({ as: "global" }); ZodError e HttpError via estratégias; módulos lançam exceções em src/exceptions/ (estender HttpError); evitar try/catch de fluxo (ver reference/03-errors-openapi.md e templates em templates/).
• Plugins: categorias core, auth, infra, docs; sem index.ts genérico — nomes explícitos (*.plugin.ts).
• Config: nunca process.env direto nos módulos — usar src/configs/*.config.ts.
• Auth: jwt plugin; rotas protegidas com guard de sessão; RBAC com permission guard depois do auth guard quando aplicável.

Estrutura alvo (resumo)

src/
  index.ts
  configs/
  database/
    connection.ts
    index.ts
    schema/
    migrations/
  exceptions/
  plugins/
    core/error-handler/   # ou espelhar templates desta skill
    auth/
    infra/
    docs/
  modules/
    <feature>/
      <feature>.routes.ts
      <feature>.service.ts
      <feature>.repository.ts
      <feature>.schema.ts
      <feature>.types.ts
      <feature>.docs.ts
      <feature>.constants.ts
    modules.routes.ts

Ficheiros desta skill (copiar para o repo)

Caminhos relativos ao repositório de código; sem paths absolutos de máquina.

Referência rápida

Erros comuns

• Esquecer que ordem dos plugins altera CORS, limite, segurança e documentação antes das rotas.
• activityLog com mapResponse global a interferir com testes — isolar dados ou esperas (ver referência de testes).
• Misturar detail OpenAPI à mão sem *.docs.ts por feature.
• permissionGuard sem authGuard quando a rota exige utilizador autenticado.

Exemplo mínimo (módulo + HTTP_STATUS + error plugin)

Caminhos relativos à pasta da skill; no repo, viver em src/modules/items/ e importar plugins por alias.

import { Elysia } from "elysia";
import { z } from "zod";
import { errorHandlerPlugin } from "./error-handler.plugin";
import { HTTP_STATUS } from "./http-status.constants";

const bodySchema = z.object({ name: z.string().min(1) });
const responseSchema = z.object({
  id: z.string().uuid(),
  name: z.string(),
});

export const itemsRoutes = new Elysia({ prefix: "/items" }).post(
  "",
  ({ body, set }) => {
    set.status = HTTP_STATUS.CREATED;
    return { id: crypto.randomUUID(), name: body.name };
  },
  {
    body: bodySchema,
    response: responseSchema,
  },
);

export const application = new Elysia()
  .use(errorHandlerPlugin)
  .use(itemsRoutes);

Racionalizações a ignorar

Violar bootstrap, agregação `modules.routes.ts`, camadas service/repository, exceções tipadas ou configs centralizadas reproduz dívida que esta skill existe para evitar.