Application (app) API Reference

The app instance is the central application server created via createApp().

NOTE

Velociradix app method calls return the app instance, allowing fluent method chaining (app.use().get().post().listen()).

---

⚡ Server Lifecycle & Configuration

app.listen(port, host?, callback?)

Binds to network socket synchronously and starts the C++ multi-threaded event loop engine.

app.listen(3000, "127.0.0.1", () => {
  console.log("Server running on http://127.0.0.1:3000");
});

---

app.close()

Stops worker threads and closes open server listening sockets cleanly.

app.close();

---

app.printRoutes()

Prints an ASCII route table overview of all registered routes to terminal CLI.

app.printRoutes();

---

app.cluster(options?)

Scales server instances across CPU cores using multi-process cluster workers.

app.cluster({ workers: 4 });

---

app.autoScale(options?)

Dynamically scales C++ worker thread count based on memory and CPU load.

app.autoScale({ minWorkers: 2, maxWorkers: 8, intervalMs: 5000 });

---

🔀 Versioning & RPC

app.versioning(versionsMap, options?)

Multi-version API router supporting X-API-Version header and path prefixes (/v1, /v2):

app.versioning({
  v1: appV1,
  v2: appV2,
});

---

app.rpc(path, procedures)

Registers a JSON-RPC 2.0 endpoint for procedure calls:

app.rpc("/rpc", {
  multiply: ({ a, b }) => a * b,
});

---

📁 File-Based Routing & Mocking

app.autoRoute(dirPath, basePrefix?)

Automatically scans directory files and registers route handlers synchronously:

app.autoRoute("./routes");

---

app.autoRouteAsync(dirPath, basePrefix?)

Asynchronous file-system route loader that returns a Promise<App>:

await app.autoRouteAsync("./routes", "/api/v1");

---

app.mockServer(routesMap)

Registers mock API endpoints with simulated latency delay:

app.mockServer({
  "GET /api/users": { status: 200, delayMs: 100, body: [{ id: 1 }] },
});

---

🔌 WebSockets, GraphQL & Real-Time

app.ws()

Removed in 8.2.0. The previous helper was not a WebSocket (no 101, no frames, no Origin check). Use a dedicated WebSocket library.

---

app.graphql(path, schema, resolvers)

Experimental POST-only toy resolver (8 KiB query cap). Not a GraphQL server. Mutations via GET are rejected.

app.graphql("/graphql", `type Query { hello: String }`, {
  hello: () => "Hello GraphQL",
});

---

app.sseBroadcast(channel, data)

Broadcasts a Server-Sent Event (SSE) payload to all connected channel clients:

app.sseBroadcast("live-updates", { time: Date.now() });

---

📊 Benchmarking & Observability

app.bench(options?)

Runs an automated local benchmark test measuring RPS and total duration:

const stats = await app.bench({ iterations: 1000, path: "/api/users" });
console.log(`Throughput: ${stats.rps} req/sec`);

---

app.metricsUI(path?, opts?)

Mounts a live HTML & JSON metrics dashboard. Disabled in production unless { expose: true } (private network only).

app.metricsUI("/velociradix/metrics"); // local / NODE_ENV !== production
app.metricsUI("/velociradix/metrics", { expose: true }); // explicit, not for the public internet