Category
Preparing references and filters for this topic. 이 주제의 레퍼런스와 필터를 준비하고 있습니다.
Category Reference
모듈, ESM/CJS, HTTP, fetch, Web Streams, worker threads, 패키지 배포, diagnostics까지 Node.js 런타임의 핵심 흐름을 카드형 레퍼런스로 정리합니다.
Search titles, summaries, tags, and subcategories.
Showing 38 cards.
Subcategory
6 cards
CommonJS와 ES 모듈 방식으로 모듈을 정의하고 `module.exports`/`export`를 관리하는 패턴을 정리합니다.
// math.js — CommonJS 모듈 정의
function add(a, b) { return a + b; }
function multiply(a, b) { return a * b; }
module.exports = { add, multiply };
// index.js — 불러오기 (같은 파일을 두 번 require해도 캐시에서 반환)
const math1 = require("./math");
const math2 = require("./math"); // 동일한 객체 참조
console.log(math1 === math2); // true
console.log(math1.add(2, 3)); // 5`package.json` 카드는 필드 나열보다 `팀이 무엇을 어떤 진입점으로 실행하게 할 것인가`를 정리하는 카드입니다. scripts와 npm 실행 흐름 중심으로 다시 봅니다.
{
"type": "module",
"scripts": {
"dev": "node --watch src/index.js",
"build": "tsc",
"test": "node --test"
}
}Node.js에서 ESM과 CommonJS를 섞어 쓸 때의 기본 규칙, `import()`, `createRequire()` 활용 기준을 정리합니다.
// ESM 파일에서 CJS 모듈 불러오기
import { createRequire } from "node:module";
const require = createRequire(import.meta.url);
const legacy = require("./legacy.cjs");
// CJS 파일에서 ESM 모듈 동적 로드
async function loadESM() {
const { helper } = await import("./helper.mjs");
return helper();
}`package.json`의 `exports`와 `imports` 필드, conditional exports가 패키지 공개 경계를 어떻게 정하는지 정리합니다.
{
"name": "my-lib",
"exports": {
".": {
"import": "./dist/index.mjs",
"require": "./dist/index.cjs",
"types": "./dist/index.d.ts"
},
"./utils": {
"import": "./dist/utils.mjs",
"require": "./dist/utils.cjs"
}
},
"imports": {
"#internal/*": "./src/internal/*.js"
}
}ESM에서 `import.meta`, file URL, `__dirname` 대체 패턴을 어떻게 다뤄야 하는지 정리합니다.
import { fileURLToPath } from "node:url";
import { dirname, join } from "node:path";
// ESM에서 __filename, __dirname 대체 패턴
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
// 현재 파일 기준으로 다른 파일 경로 구성
const configPath = join(__dirname, "config", "default.json");
// Node 20.11+ 에서는 간결하게
const dir = import.meta.dirname;
const file = import.meta.filename;Node.js 패키지를 재사용 가능한 라이브러리나 CLI로 배포할 때 `package.json`의 핵심 필드와 `bin` 구성을 어떻게 읽는지 정리합니다.
{
"name": "my-tool",
"version": "1.0.0",
"type": "module",
"bin": {
"my-tool": "./bin/cli.js"
},
"files": ["bin", "dist", "README.md"],
"exports": {
".": "./dist/index.js"
}
}9 cards
이벤트 루프 카드는 phase 이름 암기보다 `왜 이 콜백이 먼저 실행됐는가`를 설명할 수 있어야 합니다. microtask, timer, I/O 이후 순서를 다시 찾을 때 보는 기준 카드입니다.
console.log("A");
setTimeout(() => console.log("timeout"), 0);
Promise.resolve().then(() => console.log("promise"));
queueMicrotask(() => console.log("microtask"));
console.log("B");Node 타이머 카드는 API 이름보다 `반복 작업을 어떻게 안전하게 예약할까`를 먼저 답해야 합니다. `setTimeout`, `setInterval`, `setImmediate`, `queueMicrotask` 경계를 정리합니다.
setTimeout(runOnce, 1000);
setImmediate(flushAfterIo);
queueMicrotask(flushAfterSync);`EventEmitter` 카드는 API 사용법보다 `이 이벤트가 동기인가`, `누가 cleanup 책임을 지는가`, `error 이벤트를 누가 받는가`를 정리하는 카드입니다.
emitter.on("tick", () => {
console.log("listener");
});
emitter.emit("tick");
console.log("after");취소와 실패를 같은 에러로 다루면 흐름이 흐려집니다. `AbortController`, `AbortSignal.timeout`, `AbortSignal.any`를 `취소는 정상 흐름`이라는 관점에서 정리합니다.
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 3000);
try {
const response = await fetch(url, { signal: controller.signal });
} catch (err) {
if (err.name === "AbortError") {
return;
}
throw err;
} finally {
clearTimeout(timeoutId);
}Node.js `crypto` 모듈에서 해시와 난수 생성이 각각 어떤 용도에 맞는지 정리합니다.
import { createHash, createHmac, randomBytes, randomUUID } from "node:crypto";
const fileHash = createHash("sha256").update(fileBuffer).digest("hex");
const apiToken = randomBytes(32).toString("hex");
const requestId = randomUUID();
const signature = createHmac("sha256", secret).update(payload).digest("hex");`worker_threads` 카드는 멀티스레드 소개 카드가 아니라 `이 작업이 진짜 CPU 바운드인가`를 판단하는 카드입니다. 워커를 써야 하는 경우와 아닌 경우를 먼저 정리합니다.
const worker = new Worker(new URL("./worker.js", import.meta.url), {
workerData: { n: 5_000_000 },
});`worker_threads`를 실전에 붙일 때의 pool 전략, `MessageChannel`, transfer, shared memory 기준을 정리합니다.
import { Worker } from "node:worker_threads";
import os from "node:os";
const POOL_SIZE = os.availableParallelism();
const pool = Array.from({ length: POOL_SIZE }, () => new Worker("./compute-worker.js"));
let next = 0;
function dispatch(task) {
return new Promise((resolve, reject) => {
const worker = pool[next % POOL_SIZE];
next += 1;
worker.once("message", resolve);
worker.once("error", reject);
worker.postMessage(task);
});
}Node.js의 `diagnostics_channel`을 이용해 라이브러리와 애플리케이션 사이 관측성 신호를 느슨하게 연결하는 패턴을 정리합니다.
import diagnostics_channel from "node:diagnostics_channel";
const channel = diagnostics_channel.channel("myapp:http:request");
function publishRequest(message) {
if (channel.hasSubscribers) channel.publish(message);
}
diagnostics_channel.subscribe("myapp:http:request", (message) => {
console.log("[trace]", message.method, message.url, message.durationMs);
});Node의 async 에러 카드는 문법보다 `에러가 어디서 사라졌는가`를 추적하는 데 써야 합니다. await 누락, 체인 중간 catch, 최상위 rejection 처리 기준을 한 장에 모았습니다.
try {
await fetchData();
} catch (err) {
console.error(err);
}
main().catch((err) => {
console.error("main failed:", err);
process.exit(1);
});5 cards
`createServer`로 기본 요청/응답 흐름을 만들고, 라우팅 없이 바로 응답하는 간단한 HTTP 서버 패턴을 보여줍니다.
import { createServer } from "node:http";
const server = createServer(async (req, res) => {
const url = new URL(req.url ?? "/", "http://localhost");
if (req.method === "GET" && url.pathname === "/status") {
res.writeHead(200, { "Content-Type": "application/json" });
res.end(JSON.stringify({ ok: true }));
return;
}
if (req.method === "POST" && url.pathname === "/echo") {
let body = "";
for await (const chunk of req) body += chunk;
res.writeHead(200, { "Content-Type": "application/json" });
res.end(JSON.stringify({ received: body }));
return;
}
res.writeHead(404);
res.end("Not Found");
});
server.listen(3000, () => console.log("http://localhost:3000"));Node.js 18+의 내장 `fetch`로 외부 API를 호출하고 JSON 응답을 읽는 기본 패턴입니다.
// 타임아웃과 HTTP 오류 처리를 포함한 실전 패턴
async function fetchJson(url, timeoutMs = 5000) {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeoutMs);
try {
const response = await fetch(url, { signal: controller.signal });
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${response.statusText}`);
}
return await response.json();
} finally {
clearTimeout(timer);
}
}
const user = await fetchJson("https://api.example.com/users/1");
console.log(user.name);Node.js 기본 HTTP 서버에서 요청 본문을 읽고 JSON 응답을 보내는 가장 실전적인 패턴을 정리합니다.
import { createServer } from "node:http";
const MAX_BODY = 1_048_576; // 1MB
const server = createServer(async (req, res) => {
if (req.method !== "POST" || req.url !== "/users") {
res.writeHead(404);
res.end("Not Found");
return;
}
const contentType = req.headers["content-type"] ?? "";
if (!contentType.includes("application/json")) {
res.writeHead(415, { "Content-Type": "application/json" });
res.end(JSON.stringify({ error: "Unsupported Media Type" }));
return;
}
let body = "";
for await (const chunk of req) {
body += chunk;
if (body.length > MAX_BODY) {
res.writeHead(413, { "Content-Type": "application/json" });
res.end(JSON.stringify({ error: "Payload Too Large" }));
req.destroy();
return;
}
}
const payload = JSON.parse(body);
res.writeHead(201, { "Content-Type": "application/json" });
res.end(JSON.stringify({ ok: true, name: payload.name }));
});
server.listen(3000);현대 Node.js가 제공하는 `fetch`, `Request`, `Response`, `FormData`, `Headers` 같은 Web API 표면을 정리합니다.
import { readFile } from "node:fs/promises";
// 파일을 Blob으로 만들어 FormData에 첨부
const fileBuffer = await readFile("./photo.jpg");
const blob = new Blob([fileBuffer], { type: "image/jpeg" });
const form = new FormData();
form.append("name", "kero");
form.append("avatar", blob, "photo.jpg"); // 파일명도 함께 전달
// Content-Type은 직접 설정하지 않는다 — boundary가 자동 생성됨
const response = await fetch("https://api.example.com/users", {
method: "POST",
body: form,
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const result = await response.json();HTTP 서버가 단순히 요청을 받는 것을 넘어, timeout과 keep-alive를 어떻게 다루고 종료 시 어떤 순서로 정리해야 하는지 정리합니다.
import { createServer } from "node:http";
const server = createServer((req, res) => {
res.writeHead(200);
res.end("ok");
});
server.requestTimeout = 30_000; // 요청 전체 최대 시간
server.headersTimeout = 10_000; // 헤더 수신 제한
server.keepAliveTimeout = 5_000; // 유휴 연결 재사용 대기
server.listen(3000);
process.on("SIGTERM", () => {
server.close(() => process.exit(0)); // 새 연결 중단, 기존 요청 완료 대기
server.closeAllConnections(); // keep-alive 연결 즉시 해제 (Node 18.2+)
setTimeout(() => process.exit(1), 10_000); // 강제 종료 안전망
});9 cards
`process.env`와 `argv` 카드는 값 읽기 자체보다 `입력 경계`를 설계하는 카드입니다. 환경 변수 타입 변환과 CLI 인자 해석을 한 장에서 다시 정리합니다.
const port = Number(process.env.PORT ?? "3000");
const debug = process.env.DEBUG === "true";터미널 입력을 받아 간단한 CLI를 만드는 Node.js `readline` 기본 흐름을 정리합니다.
import readline from "node:readline/promises";
import { stdin as input, stdout as output } from "node:process";
const rl = readline.createInterface({ input, output });
try {
const name = await rl.question("이름을 입력하세요: ");
const confirm = await rl.question(`"${name}"으로 저장할까요? (y/n) `);
if (confirm.toLowerCase() === "y") {
await saveUser(name);
console.log("저장 완료");
}
} finally {
rl.close();
}외부 프로그램을 실행할 때 자주 비교하는 `spawn()`과 `exec()`의 차이를 정리합니다.
import { spawn, execFile } from "node:child_process";
const child = spawn("git", ["log", "--oneline", "-20"]);
child.stdout.on("data", (chunk) => process.stdout.write(chunk));
child.stderr.on("data", (chunk) => process.stderr.write(chunk));
const install = spawn("npm", ["install"], { stdio: "inherit" });
install.on("close", (code) => {
if (code !== 0) process.exit(code);
});
execFile("echo", ["safe input"], (err, stdout) => {
console.log(stdout);
});종료 카드는 `exit(1)` 문법보다 `무엇을 먼저 정리하고 언제 종료할 것인가`를 정하는 카드입니다. SIGTERM, SIGINT, graceful shutdown 기준을 중심으로 정리합니다.
process.on("SIGTERM", () => shutdown("SIGTERM"));
process.on("SIGINT", () => shutdown("SIGINT"));내장 테스트 러너 `node:test`로 작은 단위 테스트를 구성하는 기본 흐름을 정리합니다.
import { test, describe, it, mock } from "node:test";
import assert from "node:assert/strict";
describe("formatPrice", () => {
it("정수 금액을 천 단위로 포맷한다", () => {
assert.strictEqual(formatPrice(1000), "1,000원");
});
});
test("비동기 함수도 검증한다", async () => {
const result = await fetchUser(1);
assert.deepStrictEqual(result, { id: 1, name: "Alice" });
});실행 환경 정보를 얻는 `os` 모듈의 핵심 함수와 적절한 사용 범위를 정리합니다.
import os from "node:os";
const workerCount = Math.max(1, os.availableParallelism() - 1);
const totalMem = os.totalmem();
const freeMem = os.freemem();
console.log({
workerCount,
platform: os.platform(),
arch: os.arch(),
homedir: os.homedir(),
tmpdir: os.tmpdir(),
memoryUsagePercent: ((1 - freeMem / totalMem) * 100).toFixed(1),
});환경 변수와 env 파일을 어디까지 설정값으로 쓰고, 어떤 값은 별도 config 검증으로 올려야 하는지 정리합니다.
// Node.js 20.6+ — dotenv 없이 .env 직접 로드
// node --env-file=.env server.js
const port = Number(process.env.PORT ?? 3000);
const debug = process.env.DEBUG === "true";
const dbUrl = process.env.DATABASE_URL;
if (!dbUrl) throw new Error("DATABASE_URL is required");
if (!Number.isInteger(port)) throw new Error("PORT must be an integer");
export const config = { port, debug, dbUrl };Node.js cluster 모듈로 CPU 코어를 활용하는 방법, worker_threads와의 선택 기준, 프로세스 장애 복구 패턴을 정리합니다.
import cluster from "node:cluster";
import http from "node:http";
import { availableParallelism } from "node:os";
if (cluster.isPrimary) {
for (let i = 0; i < availableParallelism(); i++) {
cluster.fork();
}
cluster.on("exit", (worker) => {
if (!worker.exitedAfterDisconnect) cluster.fork();
});
} else {
http.createServer((req, res) => {
res.end(`worker ${process.pid}`);
}).listen(3000);
}Node.js 20+에서 도입되고 22.13+/23.5+에서 안정화된 Permission Model로 파일·네트워크·자식 프로세스 접근을 제한하는 방법, 보안 경계 설정 전략을 정리합니다.
node \
--permission \
--allow-fs-read="/app/config" \
--allow-fs-write="/app/tmp" \
--allow-net="api.example.com:443" \
server.js9 cards
비동기 파일 I/O 카드는 API 목록보다 `readFile로 끝낼까, stream으로 넘길까, Promise.all로 묶을까`를 판단하는 카드입니다. `fs/promises` 기준으로 다시 정리합니다.
import { readFile, writeFile, mkdir } from "node:fs/promises";Node에서 경로 문제는 `join vs resolve`, `경로 vs file URL`, `ESM의 import.meta.url` 세 갈래로 자주 다시 나옵니다. 이 셋을 한 장에서 빠르게 정리합니다.
path.join("src", "utils", "helper.js");
path.resolve("src", "utils", "helper.js");
const __dirname = dirname(fileURLToPath(import.meta.url));
const filePath = join(__dirname, "data.json");스트림 카드는 API 이름보다 `언제 readFile 대신 stream을 써야 하는가`를 먼저 답해야 합니다. Readable/Writable/Transform과 backpressure 감각을 한 장에 모았습니다.
import { createReadStream, createWriteStream } from "node:fs";
import { createGzip } from "node:zlib";
createReadStream("./big.log")
.pipe(createGzip())
.pipe(createWriteStream("./big.log.gz"));문자열이 아니라 바이트 단위 데이터를 다루는 Node.js `Buffer`의 기본 개념과 사용 흐름을 정리합니다.
const buf = Buffer.from("hello world", "utf8");
console.log(buf.length); // 11 bytes
console.log(buf.toString("hex")); // 68656c6c6f20776f726c64
console.log(buf.toString("base64")); // aGVsbG8gd29ybGQ=
const fixed = Buffer.alloc(8);
fixed.writeUInt32BE(0xdeadbeef, 0);
console.log(fixed.toString("hex")); // deadbeef00000000여러 스트림을 안전하게 연결하고 완료 여부를 확인할 때 쓰는 `pipeline()`과 `finished()` 패턴을 정리합니다.
import { createReadStream, createWriteStream } from "node:fs";
import { createGzip } from "node:zlib";
import { pipeline } from "node:stream/promises";
await pipeline(
createReadStream("./input.log"),
createGzip(),
createWriteStream("./output.log.gz"),
);파일 변경 감지용 `fs.watch()`와 개발 중 재실행용 `node --watch`를 어떻게 구분해 써야 하는지 정리합니다.
import { watch } from "node:fs";
let timer;
watch("./src", { recursive: true }, (eventType, filename) => {
clearTimeout(timer);
timer = setTimeout(() => {
console.log(`[changed] ${eventType}: ${filename}`);
rebuildIndex();
}, 100);
});Node.js `zlib`로 gzip/deflate/brotli 압축을 적용할 때 알고리즘 선택 기준, 스트림 기반 사용, HTTP 응답 압축 패턴을 정리합니다.
import { createReadStream, createWriteStream } from "node:fs";
import { createGzip } from "node:zlib";
import { pipeline } from "node:stream/promises";
// 스트림 기반 — 대용량 파일도 메모리 부담 없이 처리
await pipeline(
createReadStream("app.log"),
createGzip(), // 기본 압축 레벨 6
createWriteStream("app.log.gz"),
);현대 Node.js에서 공존하는 Web Streams와 전통적인 Node streams가 무엇이 다르고, 어느 경계에서 만나는지 정리합니다.
import { Readable } from "node:stream";
import { pipeline } from "node:stream/promises";
import { createWriteStream } from "node:fs";
const response = await fetch("https://example.com/large-file.bin");
const nodeStream = Readable.fromWeb(response.body);
await pipeline(nodeStream, createWriteStream("output.bin"));Node.js 22.5+에서 추가된 node:sqlite 모듈로 외부 패키지 없이 SQLite를 사용하는 방법, 동기 API 특성과 적합한 사용 시나리오를 정리합니다.
import { DatabaseSync } from "node:sqlite";
const db = new DatabaseSync("./data.db");
db.exec("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)");
const insert = db.prepare("INSERT INTO users (name) VALUES (?)");
insert.run("kero");
const rows = db.prepare("SELECT * FROM users").all();
console.log(rows);
db.close();