TypeScript الأصلي في Node.js 26: أطلق واجهة API إنتاجية بلا خطوة بناء

node --version
# v26.0.0 أو أحدث

// scratch.ts
type Greeting = { name: string; formal: boolean };
 
function greet({ name, formal }: Greeting): string {
  return formal ? `Good evening, ${name}.` : `Hey ${name}!`;
}
 
console.log(greet({ name: "Amira", formal: true }));

node scratch.ts
# Good evening, Amira.

mkdir task-api && cd task-api
npm init -y
npm install --save-dev typescript @types/node

{
  "name": "task-api",
  "version": "1.0.0",
  "type": "module",
  "engines": {
    "node": ">=26.0.0"
  },
  "scripts": {
    "dev": "node --watch --env-file-if-exists=.env src/server.ts",
    "start": "node --env-file-if-exists=.env src/server.ts",
    "test": "node --test 'src/**/*.test.ts'",
    "typecheck": "tsc --noEmit"
  },
  "devDependencies": {
    "typescript": "^5.8.0",
    "@types/node": "^26.0.0"
  }
}

{
  "compilerOptions": {
    "target": "esnext",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "lib": ["esnext"],
    "types": ["node"],
 
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "rewriteRelativeImportExtensions": true,
    "allowImportingTsExtensions": true,
 
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noEmit": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*.ts"]
}

// مكسور — يرمي Node خطأ SyntaxError
enum Status {
  Pending = "pending",
  Done = "done"
}

// src/types.ts
export const Status = {
  Pending: "pending",
  Done: "done",
  Archived: "archived"
} as const;
 
export type Status = (typeof Status)[keyof typeof Status];
// type Status = "pending" | "done" | "archived"

import { createTaskStore } from "./store";     // مكسور
import { createTaskStore } from "./store.ts";  // صحيح

// مكسور في زمن التشغيل — يُصدر Node استيراداً حقيقياً لتصدير نوعي فقط
import { Task } from "./types.ts";
 
// صحيح
import type { Task } from "./types.ts";
 
// صحيح — استيراد مختلط مع علامة نوع مضمّنة
import { Status, type Task } from "./types.ts";

{
  "imports": {
    "#store/*": "./src/store/*"
  }
}

// مكسور — خاصية المُعامِل تولّد عملية إسناد
class TaskStore {
  constructor(private db: DatabaseSync) {}
}
 
// صحيح — اكتب الإسناد بنفسك
class TaskStore {
  readonly #db: DatabaseSync;
 
  constructor(db: DatabaseSync) {
    this.#db = db;
  }
}

export const Status = {
  Pending: "pending",
  Done: "done",
  Archived: "archived"
} as const;
 
export type Status = (typeof Status)[keyof typeof Status];
 
export interface Task {
  id: number;
  title: string;
  status: Status;
  createdAt: string;
}
 
export interface NewTask {
  title: string;
  status?: Status;
}

import { DatabaseSync } from "node:sqlite";
import type { Task, NewTask, Status } from "./types.ts";
 
export function createTaskStore(path: string) {
  const db = new DatabaseSync(path);
 
  // جداول STRICT ترفض عدم تطابق الأنواع بدل تحويلها صامتةً
  db.exec(`
    CREATE TABLE IF NOT EXISTS tasks (
      id        INTEGER PRIMARY KEY AUTOINCREMENT,
      title     TEXT NOT NULL,
      status    TEXT NOT NULL DEFAULT 'pending',
      createdAt TEXT NOT NULL
    ) STRICT
  `);
 
  // العبارات المُحضّرة تُترجم مرة واحدة ويُعاد استخدامها في كل نداء
  const insertStmt = db.prepare(
    `INSERT INTO tasks (title, status, createdAt)
     VALUES (:title, :status, :createdAt)`
  );
  const listStmt = db.prepare(`SELECT * FROM tasks ORDER BY id DESC`);
  const getStmt = db.prepare(`SELECT * FROM tasks WHERE id = :id`);
  const updateStmt = db.prepare(
    `UPDATE tasks SET status = :status WHERE id = :id`
  );
  const deleteStmt = db.prepare(`DELETE FROM tasks WHERE id = :id`);
 
  return {
    list(): Task[] {
      return listStmt.all() as unknown as Task[];
    },
 
    get(id: number): Task | undefined {
      return getStmt.get({ id }) as unknown as Task | undefined;
    },
 
    create(input: NewTask): Task {
      const createdAt = new Date().toISOString();
      const result = insertStmt.run({
        title: input.title,
        status: input.status ?? "pending",
        createdAt
      });
 
      return {
        id: Number(result.lastInsertRowid),
        title: input.title,
        status: input.status ?? "pending",
        createdAt
      };
    },
 
    updateStatus(id: number, status: Status): Task | undefined {
      const result = updateStmt.run({ id, status });
      if (result.changes === 0) return undefined;
      return this.get(id);
    },
 
    remove(id: number): boolean {
      return deleteStmt.run({ id }).changes > 0;
    },
 
    close(): void {
      db.close();
    }
  };
}
 
export type TaskStore = ReturnType<typeof createTaskStore>;

import { Status } from "./types.ts";
import type { NewTask } from "./types.ts";
 
export type Validated<T> =
  | { ok: true; value: T }
  | { ok: false; errors: string[] };
 
const VALID_STATUSES = Object.values(Status) as string[];
 
export function validateNewTask(input: unknown): Validated<NewTask> {
  const errors: string[] = [];
 
  if (typeof input !== "object" || input === null) {
    return { ok: false, errors: ["body must be a JSON object"] };
  }
 
  const body = input as Record<string, unknown>;
 
  if (typeof body.title !== "string" || body.title.trim().length === 0) {
    errors.push("title is required and must be a non-empty string");
  } else if (body.title.length > 200) {
    errors.push("title must be 200 characters or fewer");
  }
 
  if (body.status !== undefined && !VALID_STATUSES.includes(String(body.status))) {
    errors.push(`status must be one of: ${VALID_STATUSES.join(", ")}`);
  }
 
  if (errors.length > 0) return { ok: false, errors };
 
  return {
    ok: true,
    value: {
      title: (body.title as string).trim(),
      status: body.status as NewTask["status"]
    }
  };
}
 
export function validateStatus(input: unknown): Validated<Status> {
  if (typeof input !== "object" || input === null) {
    return { ok: false, errors: ["body must be a JSON object"] };
  }
 
  const status = (input as Record<string, unknown>).status;
 
  if (!VALID_STATUSES.includes(String(status))) {
    return {
      ok: false,
      errors: [`status must be one of: ${VALID_STATUSES.join(", ")}`]
    };
  }
 
  return { ok: true, value: status as Status };
}

import type { IncomingMessage, ServerResponse } from "node:http";
import type { TaskStore } from "./store.ts";
import { validateNewTask, validateStatus } from "./validate.ts";
 
const MAX_BODY_BYTES = 64 * 1024;
 
async function readJsonBody(req: IncomingMessage): Promise<unknown> {
  const chunks: Buffer[] = [];
  let size = 0;
 
  for await (const chunk of req) {
    size += chunk.length;
    if (size > MAX_BODY_BYTES) {
      throw new Error("request body too large");
    }
    chunks.push(chunk as Buffer);
  }
 
  if (chunks.length === 0) return {};
 
  return JSON.parse(Buffer.concat(chunks).toString("utf8"));
}
 
function send(res: ServerResponse, status: number, payload: unknown): void {
  const body = JSON.stringify(payload);
  res.writeHead(status, {
    "content-type": "application/json; charset=utf-8",
    "content-length": Buffer.byteLength(body)
  });
  res.end(body);
}
 
export function createRouter(store: TaskStore) {
  return async function handle(
    req: IncomingMessage,
    res: ServerResponse
  ): Promise<void> {
    const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
    const segments = url.pathname.split("/").filter(Boolean);
    const method = req.method ?? "GET";
 
    // GET /health
    if (method === "GET" && url.pathname === "/health") {
      return send(res, 200, { status: "ok", uptime: process.uptime() });
    }
 
    if (segments[0] !== "tasks") {
      return send(res, 404, { error: "not found" });
    }
 
    // GET /tasks
    if (method === "GET" && segments.length === 1) {
      return send(res, 200, { tasks: store.list() });
    }
 
    // POST /tasks
    if (method === "POST" && segments.length === 1) {
      const body = await readJsonBody(req);
      const result = validateNewTask(body);
 
      if (!result.ok) {
        return send(res, 422, { errors: result.errors });
      }
 
      return send(res, 201, { task: store.create(result.value) });
    }
 
    // كل ما يلي يحتاج معرّفاً رقمياً
    const id = Number(segments[1]);
    if (segments.length !== 2 || !Number.isInteger(id) || id < 1) {
      return send(res, 400, { error: "invalid task id" });
    }
 
    // GET /tasks/:id
    if (method === "GET") {
      const task = store.get(id);
      return task
        ? send(res, 200, { task })
        : send(res, 404, { error: "task not found" });
    }
 
    // PATCH /tasks/:id
    if (method === "PATCH") {
      const result = validateStatus(await readJsonBody(req));
 
      if (!result.ok) {
        return send(res, 422, { errors: result.errors });
      }
 
      const task = store.updateStatus(id, result.value);
      return task
        ? send(res, 200, { task })
        : send(res, 404, { error: "task not found" });
    }
 
    // DELETE /tasks/:id
    if (method === "DELETE") {
      return store.remove(id)
        ? send(res, 204, {})
        : send(res, 404, { error: "task not found" });
    }
 
    return send(res, 405, { error: "method not allowed" });
  };
}

import { createServer } from "node:http";
import { createTaskStore } from "./store.ts";
import { createRouter } from "./router.ts";
 
const PORT = Number(process.env.PORT ?? 3000);
const DB_PATH = process.env.DB_PATH ?? "./tasks.db";
 
const store = createTaskStore(DB_PATH);
const handle = createRouter(store);
 
const server = createServer((req, res) => {
  handle(req, res).catch((error: unknown) => {
    const message = error instanceof Error ? error.message : "unknown error";
    console.error("[request-error]", message);
 
    if (!res.headersSent) {
      res.writeHead(500, { "content-type": "application/json" });
      res.end(JSON.stringify({ error: "internal server error" }));
    }
  });
});
 
server.listen(PORT, () => {
  console.log(`[startup] listening on http://localhost:${PORT}`);
});
 
// إيقاف رشيق — ترسل الحاويات SIGTERM قبل SIGKILL
function shutdown(signal: string): void {
  console.log(`[shutdown] received ${signal}, closing`);
  server.close(() => {
    store.close();
    process.exit(0);
  });
 
  // خروج قسري إن رفضت الاتصالات الانتهاء
  setTimeout(() => process.exit(1), 10_000).unref();
}
 
process.on("SIGTERM", () => shutdown("SIGTERM"));
process.on("SIGINT", () => shutdown("SIGINT"));

npm run dev
# [startup] listening on http://localhost:3000

# .env
PORT=3000
DB_PATH=./tasks.db

{
  "scripts": {
    "start": "node --env-file-if-exists=.env src/server.ts"
  }
}

// حمّل ملف .env في التطوير فقط، وتجاهله إن كان غائباً
if (process.env.NODE_ENV !== "production") {
  try {
    process.loadEnvFile(".env");
  } catch {
    console.warn("[config] no .env file found, using process environment");
  }
}

// src/config.ts
function requireEnv(key: string): string {
  const value = process.env[key];
  if (!value) {
    console.error(`[config] missing required env var: ${key}`);
    process.exit(1);
  }
  return value;
}
 
export const config = {
  port: Number(process.env.PORT ?? 3000),
  dbPath: process.env.DB_PATH ?? "./tasks.db",
  nodeEnv: process.env.NODE_ENV ?? "development"
} as const;

import { test, describe, beforeEach } from "node:test";
import assert from "node:assert/strict";
import { createTaskStore, type TaskStore } from "./store.ts";
 
describe("TaskStore", () => {
  let store: TaskStore;
 
  beforeEach(() => {
    // ":memory:" يمنح كل اختبار قاعدة بيانات نظيفة وسريعة ومعزولة
    store = createTaskStore(":memory:");
  });
 
  test("creates a task with a default status", () => {
    const task = store.create({ title: "Write the tutorial" });
 
    assert.equal(task.title, "Write the tutorial");
    assert.equal(task.status, "pending");
    assert.ok(task.id > 0);
  });
 
  test("lists tasks newest first", () => {
    store.create({ title: "first" });
    store.create({ title: "second" });
 
    const tasks = store.list();
    assert.equal(tasks.length, 2);
    assert.equal(tasks[0]?.title, "second");
  });
 
  test("updates status and returns the updated row", () => {
    const created = store.create({ title: "ship it" });
    const updated = store.updateStatus(created.id, "done");
 
    assert.equal(updated?.status, "done");
  });
 
  test("returns undefined when updating a missing task", () => {
    assert.equal(store.updateStatus(9999, "done"), undefined);
  });
 
  test("removes a task exactly once", () => {
    const created = store.create({ title: "temporary" });
 
    assert.equal(store.remove(created.id), true);
    assert.equal(store.remove(created.id), false);
  });
});

import { test, describe } from "node:test";
import assert from "node:assert/strict";
import { validateNewTask } from "./validate.ts";
 
describe("validateNewTask", () => {
  test("accepts a valid payload and trims the title", () => {
    const result = validateNewTask({ title: "  padded  " });
 
    assert.equal(result.ok, true);
    if (result.ok) {
      assert.equal(result.value.title, "padded");
    }
  });
 
  test("rejects an empty title", () => {
    const result = validateNewTask({ title: "   " });
    assert.equal(result.ok, false);
  });
 
  test("rejects an unknown status", () => {
    const result = validateNewTask({ title: "ok", status: "nonsense" });
 
    assert.equal(result.ok, false);
    if (!result.ok) {
      assert.match(result.errors[0] ?? "", /status must be one of/);
    }
  });
 
  test("rejects a non-object body", () => {
    assert.equal(validateNewTask("a string").ok, false);
    assert.equal(validateNewTask(null).ok, false);
  });
});

npm test

node --test --watch 'src/**/*.test.ts'                  # إعادة التشغيل عند الحفظ
node --test --experimental-test-coverage 'src/**/*.test.ts'  # تقرير التغطية
node --test --test-name-pattern="status" 'src/**/*.test.ts'  # تصفية بالاسم

npm run typecheck

# .github/workflows/ci.yml
name: CI
 
on:
  push:
    branches: [main]
  pull_request:
 
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/setup-node@v4
        with:
          node-version: "26"
          cache: "npm"
 
      - run: npm ci
 
      # غير قابل للتفاوض: لا شيء آخر يفحص الأنواع
      - name: Type check
        run: npm run typecheck
 
      - name: Test
        run: npm test

# .git/hooks/pre-commit
#!/bin/sh
npm run typecheck || {
  echo "Type check failed — commit aborted."
  exit 1
}

FROM node:26-slim
 
WORKDIR /app
 
# ثبّت اعتماديات الإنتاج فقط — وTypeScript ليست منها
COPY package*.json ./
RUN npm ci --omit=dev
 
# انسخ مصدر TypeScript؛ فهو نفسه المُخرَج القابل للنشر
COPY src ./src
 
ENV NODE_ENV=production
ENV PORT=3000
EXPOSE 3000
 
# شغّل بمستخدم غير جذري
USER node
 
CMD ["node", "src/server.ts"]

docker build -t task-api .
docker run -p 3000:3000 task-api

# فحص الصحة
curl -s localhost:3000/health
 
# إنشاء مهمة
curl -s -X POST localhost:3000/tasks \
  -H 'content-type: application/json' \
  -d '{"title":"Migrate the build pipeline"}'
# {"task":{"id":1,"title":"Migrate the build pipeline","status":"pending",...}}
 
# سرد المهام
curl -s localhost:3000/tasks
 
# تحديث الحالة
curl -s -X PATCH localhost:3000/tasks/1 \
  -H 'content-type: application/json' \
  -d '{"status":"done"}'
 
# التحقّق يرفض المدخل السيّئ برمز 422
curl -s -X POST localhost:3000/tasks \
  -H 'content-type: application/json' \
  -d '{"title":""}'
# {"errors":["title is required and must be a non-empty string"]}
 
# الحذف
curl -s -i -X DELETE localhost:3000/tasks/1
# HTTP/1.1 204 No Content

const task = store.create({ title: 42 });  // رقم لا نص