VenanJS — Documentação

Introdução

VenanJS
Um micro-framework Node.js minimalista pensado para quem quer um setup mais rápido para APIs, views e WebSocket. O foco é produtividade e simplicidade para iniciantes.

Instalação & Quickstart

Instalação no projeto:

npm install venanjs

Exemplo mínimo (app.js):

import { Venan } from "venanjs";
const app = new Venan();
const PORT = 3001;

app.serveStatic("public");       // arquivos estáticos
app.venanSwagger({ apis: ["./src/routes/*.js"] }); // opcional
app.serveDocs(PORT); // Documentação local em /docs
app.start(PORT);

Dica: O comando CLI (ex.: npx venan g:crud User) gera controllers, routes e atualiza a estrutura para ti.

Estrutura de Pastas (recomendada)

my-app/
├─ app.js
├─ package.json
└─ src/
   ├─ controllers/
   ├─ models/
   └─ routes/
      └─ main.routes.js

O ficheiro main.routes.js faz o auto-registro de rotas (ver secção Autoregisto).

Venan (API principal)

A classe Venan encapsula o Express e fornece helpers: serveStatic, venanSwagger, serveDocs, use, e start.

import { Venan } from "venanjs";
const app = new Venan();

// usar rotas
import mainRouter from "./src/routes/main.routes.js";
app.use(mainRouter);

app.start(3001);

Nota: app.use() aceita middlewares, express.Router e instâncias do Router do VenanJS.

Roteamento

Cria as rotas com a API do Router do VenanJS (wrapper sobre Express):

import { Router } from "venanjs";
const router = new Router();

router.get("/ping", (req, res) => res.json({ ok: true }));
export default router;

O gerador CLI cria ficheiros *.routes.js automaticamente ao usar npx venan g:crud <Name>.

Controllers

Controllers são classes ou objetos com métodos que tratam a lógica:

export class UserController {
  async findAll(req, res) { res.json([]); }
  async create(req, res) { res.status(201).json(req.body); }
}

Middlewares

Podes usar middlewares globais ou por rota. Exemplos incluídos no VenanJS: logger, rateLimit, jwtAuth (opcionais).

// global
app.use(logger());

// por rota
router.get("/private", jwtAuth.authenticate(), controller.private);

Views (Handlebars)

Configurar:

app.setTemplateEngine(handlebarsEngine);
res.render("home", { title: "Olá" });

Base de Dados & ORM

Suporte para Prisma, Sequelize e TypeORM. Configura em database.config.json.

Exemplo:

{
  "database": {
    "orm":"prisma",
    "name":"mydb",
    "user":"root",
    "password":"",
    "host":"localhost",
    "port":3306,
    "dialect":"mysql"
  }
}

Depois podes correr:

npx venan init:db

CLI & Geradores

Comandos úteis (exemplos):

npx venan g:crud User    # gera controller, route, model, integra no mainRouter
npx venan init:db        # prepara ORM escolhido

Autoregisto de Rotas

Coloca teus ficheiros *.routes.js em src/routes/. O main.routes.js faz o auto-scan e regista automaticamente todas as rotas.

Exemplo de src/routes/main.routes.js:

import { Router } from "venanjs";
import fs from "fs";
import path from "path";

const mainRouter = new Router();
const routesPath = path.join(__dirname);

fs.readdirSync(routesPath).forEach(async file => {
  if (file.endsWith(".routes.js") && file !== "main.routes.js") {
    const mod = await import(path.join(routesPath, file));
    if (mod.default) mainRouter.applyRoutes(mod.default);
  }
});

export default mainRouter;

Depois de adicionares um ficheiro user.routes.js ele será carregado automaticamente na próxima inicialização da aplicação.

Arquiteturas (venan:arch / venan-arch)

O VenanJS inclui um gerador de arquiteturas que cria a estrutura inicial do projeto com base numa arquitetura escolhida.

npm run venan:arch

Opções disponíveis

• MVC — Estrutura tradicional (controllers, models, views).
• REST API — Estrutura optimizada para APIs.
• Event-Driven — Estrutura para aplicações orientadas a eventos.
• Clean Code — Organização mais estrita (controllers, use-cases, repositories, entities).

Gestão de Erros

O VenanJS inclui um error handler padrão que retorna JSON em APIs. Podes sobrescrever:

app.setErrorHandler((err, req, res, next) => {
  res.status(500).json({ error: err.message });
});

Exemplo Rápido

src/routes/ping.routes.js:

import { Router } from "venanjs";
const r = new Router();
r.get("/ping", (req, res) => res.json({ pong: true }));
export default r;

No browser: GET http://localhost:3001/api/ping

FAQ

• Como uso JWT?
  Existe middleware pronto em venanjs/lib/middlewares/jwtAuth.js — usa jwtAuth.generateToken() e jwtAuth.authenticate().

• Como adicionar docs?
  O Swagger já é integrado via app.venanSwagger({ apis: ["./src/routes/*.js"] }) e podes servir a documentação estática com app.serveDocs().

Footer

VenanJS — documentação minimalista. Para dúvidas ou contribuições, abre uma issue no repositório.