Rules Hub
Coding Rules Library
Rule priority, scope & exceptions
Use this to align rules with the senior-level structure (P0/P1/P2, scope, exceptions/tradeoffs).
Avoid synchronous I/O in web request paths
Sync APIs block the event loop and can stall all requests; use async APIs instead.
Bad example
| 1 | // routes.ts |
| 2 | import fs from "node:fs"; |
| 3 | import type { Request, Response } from "express"; |
| 4 |
|
| 5 | export function getReport(_req: Request, res: Response) { |
| 6 | // Blocks the event loop: other requests wait. |
| 7 | const file = fs.readFileSync("./report.json", "utf8"); |
| 8 | res.type("json").send(file); |
| 9 | } |
Explanation (EN)
Sync file reads block the single-threaded event loop, causing slow or stuck requests under load.
Objašnjenje (HR)
Sync čitanje datoteka blokira event loop (single-thread) i uzrokuje spore ili 'stuck' zahtjeve pod opterećenjem.
Good example
| 1 | // routes.ts |
| 2 | import { readFile } from "node:fs/promises"; |
| 3 | import type { Request, Response } from "express"; |
| 4 |
|
| 5 | export async function getReport(_req: Request, res: Response) { |
| 6 | const file = await readFile("./report.json", "utf8"); |
| 7 | res.type("json").send(file); |
| 8 | } |
Explanation (EN)
Async I/O keeps the event loop free to serve other requests, improving throughput and tail latency.
Objašnjenje (HR)
Async I/O drži event loop slobodnim za druge zahtjeve, pa dobivaš bolji throughput i manju tail latenciju.
Notes (EN)
Even during startup, aim for fast boot times to support log-exit-restart and autoscaling patterns.
Bilješke (HR)
Čak i tijekom startupa ciljaj na brzo podizanje kako bi log-exit-restart i autoscaling radili bolje.
Exceptions / Tradeoffs (EN)
Short-lived CLI scripts can use sync APIs when user experience is simpler and concurrency is not required.
Iznimke / Tradeoffi (HR)
Kratki CLI skripti mogu koristiti sync API-je kada je UX jednostavniji i ne trebaš konkurentnost.