ranuts/node — kleines HTTP-Framework

Ein kleiner, abhängigkeitsfreier HTTP-Werkzeugkasten für Node.js: ein HTTP-Server, ein Router, ein WebSocket-Server, Middleware für Request-Bodys und statische Dateien sowie eine Handvoll Helfer für Kommandozeile und Dateisystem.

⚠️ Nur für Node. Dieser Einstiegspunkt zieht node:http, node:fs, node:child_process und dergleichen herein. Importiere ihn aus ranuts/node, niemals aus Browser-Code.

Import

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

Die Middleware, die den Request-Body liest, wird als body exportiert (intern heißt sie bodyMiddleware). Einen Export namens bodyMiddleware gibt es nicht.

Schnellstart

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

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

// Routen greifen nur bei exakt gleichem Pfad. Der Handler bekommt den Context der Anfrage.
router.get('/hello', (ctx) => {
  ctx.res.setHeader('Content-Type', 'application/json');
  ctx.res.end(JSON.stringify({ message: 'hello world' }));
});

// POST mit JSON-Body: body() liest ihn und legt ihn in ctx.request.body ab
router.post('/echo', (ctx) => {
  ctx.res.end(JSON.stringify({ youSent: ctx.request.body }));
});

// body() liest den Request-Body UND füllt ctx.request (method / path / url / query),
// woraus der Router liest – also VOR router.routes() registrieren.
app.use(body());
app.use(router.routes());
app.use(router.allowedMethods());

// Statische Dateien ausliefern (für `/` greift ./public/index.html)
app.use(staticMiddleware({ pathname: './public' }));

const server = app.listen(3000, () => {
  console.log('Server running at http://localhost:3000');
});
// `server` ist die darunterliegende Server-Instanz von node:http.

Die Reihenfolge der Middleware zählt: Der Router liest ctx.request.path und ctx.request.method, und gefüllt werden die von body(). Registriere body() zuerst. Das mitgelieferte body() liest derzeit Request-Bodys vom Typ application/json und multipart/form-data.

API

Server

Standardexport. Ein minimaler Server im Stil von Koa, aufgesetzt auf node:http.

Signatur der Middleware

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

Ruf next() auf, um die Kontrolle an die nächste Middleware weiterzugeben. Middleware werden in der Reihenfolge ihrer Registrierung abgearbeitet; ein zweiter Aufruf von next() wirft.

Aufbau des Context

Router

Standardexport. Registriert Handler je HTTP-Methode und exaktem Pfad und stellt sie über routes() als Middleware bereit.

Signatur des Handlers

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

Lies die Daten der Anfrage aus ctx.request (method, path, url, query, body) und antworte über ctx.res. Pfade greifen nur bei exakter Übereinstimmung: Segmente der Form :param gibt es nicht; für Abfrageparameter nimm ctx.request.query.

Middleware

Optionen von body(options)

Optionen von 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) schickt an jeden verbundenen Client; wss.clients ist die Liste.

Jeder client bietet send(data, options?), ping(), pong(), close() und socket sowie die Ereignisse message, close und error.

Hilfsmittel

Siehe auch

Derselbe Einstiegspunkt ranuts/node bringt außerdem Helfer fürs Dateisystem mit, die gesondert beschrieben sind:

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