ranuts/node — mini framework HTTP

Um pequeno conjunto de ferramentas HTTP para Node.js, sem dependências: um servidor HTTP, um roteador, um servidor WebSocket, middleware de corpo e de arquivos estáticos, e um punhado de auxiliares de terminal e de sistema de arquivos.

⚠️ Só Node. Este ponto de entrada puxa node:http, node:fs, node:child_process e companhia. Importe-o de ranuts/node, nunca de código de navegador.

Importar

import { Server, Router, staticMiddleware, body } from 'ranuts/node';

O middleware que interpreta o corpo é exportado como body (o nome interno dele é bodyMiddleware). Não existe exportação chamada bodyMiddleware.

Primeiros passos

import { Server, Router, staticMiddleware, body } from 'ranuts/node';

const app = new Server();
const router = new Router();

// As rotas casam por caminho exato. O manipulador recebe o Context da requisição.
router.get('/hello', (ctx) => {
  ctx.res.setHeader('Content-Type', 'application/json');
  ctx.res.end(JSON.stringify({ message: 'hello world' }));
});

// POST com corpo JSON: body() interpreta e deixa em ctx.request.body
router.post('/echo', (ctx) => {
  ctx.res.end(JSON.stringify({ youSent: ctx.request.body }));
});

// body() interpreta o corpo da requisição E preenche ctx.request (method / path / url / query),
// que é o que o roteador lê, então registre-o ANTES de router.routes().
app.use(body());
app.use(router.routes());
app.use(router.allowedMethods());

// Serve arquivos estáticos (para `/` recorre a ./public/index.html)
app.use(staticMiddleware({ pathname: './public' }));

const server = app.listen(3000, () => {
  console.log('Server running at http://localhost:3000');
});
// `server` é a instância de Server do node:http que está por baixo.

A ordem do middleware conta: o Router lê ctx.request.path e ctx.request.method, e quem preenche isso é o body(). Registre o body() primeiro. O body() que vem junto interpreta, por ora, corpos application/json e multipart/form-data.

API

Server

Exportação padrão. Um servidor mínimo ao estilo do Koa, montado sobre node:http.

Assinatura do middleware

type Next = () => Promise<void> | Promise<never>;
type MiddlewareFunction = (ctx: Context, next: Next) => void | Promise<void>;

Chame next() para passar o controle ao middleware seguinte. Os middlewares são despachados na ordem em que foram registrados; chamar next() duas vezes lança erro.

Formato do Context

Router

Exportação padrão. Registra manipuladores por método HTTP e caminho exato, e depois os oferece como middleware por meio de routes().

Assinatura do manipulador

type Handler = (ctx: Context, next: Next) => void;

Leia os dados da requisição em ctx.request (method, path, url, query, body) e responda por ctx.res. Os caminhos casam de forma exata: não há segmentos :param; para parâmetros de consulta use ctx.request.query.

Middleware

Opções de body(options)

Opções de staticMiddleware(option)

WebSocket

import { Server, WSS } from 'ranuts/node';

const app = new Server();
const server = app.listen(3000);
const wss = new WSS(server);

wss.on('connect', (client) => {
  client.on('message', (data) => client.send('echo: ' + data));
});
// wss.broadcast(data) envia a todos os clientes conectados; wss.clients é a lista.

Cada client oferece send(data, options?), ping(), pong(), close() e socket, além dos eventos message, close e error.

Utilitários

Veja também

Esse mesmo ponto de entrada ranuts/node traz ainda auxiliares de sistema de arquivos, documentados à parte:

• writeFile
• readFile
• appendFile
• readDir
• watchFile
• queryFileInfo