TypeScript و runtime boundaries: الـ types بتختفي، والـ schemas لأ

// boundaries.js: الـ runtime boundaries: الـ env، والـ requests، والـ JSON، والـ events، والـ DB rows، والـ responses، والـ upstream APIs. كل حاجة جاية من برّه تتشيك بـ zod
// lab.js و test.js بيعملوا import من هنا. والـ types في types.ts بتطلع من نفس الـ schemas بـ z.infer
import { z } from "zod";
import express from "express";

// ———— 1) الـ env ————
export class ConfigError extends Error {
  constructor(issues) {
    super(`Invalid config:\n${issues.join("\n")}`);
    this.issues = issues;
  }
}

export const Env = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
  PORT: z.coerce.number().int().min(1).max(65535).default(3000),
  DATABASE_URL: z.url({ protocol: /^postgres(ql)?$/ }),
  FEATURE_NEW_CHECKOUT: z.stringbool().default(false), // "false" ← false. مش Boolean("false") اللي بيطلع true
  LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
});

export function loadEnv(source = process.env) {
  const r = Env.safeParse(source);
  if (!r.success) throw new ConfigError(formatIssues(r.error).map((i) => `${i.path}: ${i.message}`));
  return Object.freeze(r.data);
}

// ———— 2) الـ schemas ————
export const Email = z.string().trim().toLowerCase().pipe(z.email()).brand("Email");
export const UserId = z.uuid().brand("UserId");
export const Cents = z.number().int().nonnegative().max(1_000_000_000);

export const CreateOrder = z.strictObject({
  items: z.array(z.strictObject({
    sku: z.string().regex(/^[A-Z0-9-]{3,20}$/),
    qty: z.number().int().min(1).max(99),
  })).min(1).max(50),
  couponCode: z.string().trim().toUpperCase().max(20).optional(),
  currency: z.enum(["EGP", "USD"]).default("EGP"),
  email: Email,
});

// الـ query string كله strings، فهنا بس الـ coerce
export const ListQuery = z.object({
  limit: z.coerce.number().int().min(1).max(100).default(20),
  status: z.enum(["pending", "paid", "cancelled"]).optional(),
  cursor: z.string().max(200).optional(),
});

export function formatIssues(error) {
  return error.issues.map((i) => ({ path: i.path.length ? i.path.join(".") : "(root)", code: i.code, message: i.message }));
}

export function parseJson(text, schema) {
  let value;
  try { value = JSON.parse(text); } catch (e) { return { ok: false, issues: [{ path: "(root)", code: "invalid_json", message: e.message }] }; }
  const r = schema.safeParse(value);
  return r.success ? { ok: true, data: r.data } : { ok: false, issues: formatIssues(r.error) };
}

// ———— 3) الـ events: discriminated union و exhaustive switch ————
export const PaymentEvent = z.discriminatedUnion("type", [
  z.object({ type: z.literal("payment.succeeded"), id: z.string().min(1), amountCents: Cents, currency: z.enum(["EGP", "USD"]) }),
  z.object({ type: z.literal("payment.failed"), id: z.string().min(1), reason: z.string() }),
  z.object({ type: z.literal("refund.created"), id: z.string().min(1), paymentId: z.string().min(1), amountCents: Cents }),
]);

export function assertNever(x) {
  throw new Er
…

$ node lab.js
— 1) الـ env —
  من غير: { port: NaN, newCheckout: true }
  معاها: الـ app ما قامش: [ 'PORT: Invalid input: expected number, received NaN' ]
  مظبوط: {
  NODE_ENV: 'development',
  PORT: 8000,
  DATABASE_URL: 'postgres://app:pw@db/shop',
  FEATURE_NEW_CHECKOUT: false,
  LOG_LEVEL: 'info'
}

— 2) body من client —
  من غير: totalQty = "021"
  معاها: [ 'items.0.qty invalid_type', '(root) unrecognized_keys' ]

— 3) row من pg —
  من غير: total + 1 = "19991"
  معاها: totalCents + 1 = 2000 ، و createdAt: 2026-03-01T10:00:00.000Z

— 4) events من الـ queue —
  {"type":"payment.succeeded","id" ← paid:e1:15000EGP
  {"type":"payment.disputed","id": ← rejected: type invalid_union
  {"type":"payment.succeeded","id" ← rejected: amountCents invalid_type , currency invalid_value
  <html>                           ← rejected: invalid_json

— 5) الـ response —
  من غير: {"id":"u1","email":"[email protected]","name":"سارة","passwordHash":"$argon2id$v=19$...","mfaSecret":"JBSWY3DP"}
  معاها: {"id":"u1","email":"[email protected]","name":"سارة"}

— 6) HTTP —
  POST سليم: 201 {"order":{"items":[{"sku":"MUG-1","qty":2}],"currency":"EGP","email":"[email protected]","totalQty":2}}
  POST بايز: 400 {"error":"VALIDAT
…

// orders.naive.ts: TypeScript، و strict، والـ compiler مبسوط. وفي الإنتاج؟
type CreateOrder = { items: { sku: string; qty: number }[]; email: string; currency: "EGP" | "USD" };
type Order = { id: string; totalCents: number; createdAt: Date };
type PaymentEvent = { type: "payment.succeeded"; amountCents: number } | { type: "payment.failed"; reason: string };

const PORT = Number(process.env.PORT);                       // "abc" ← NaN، والـ server بيسمع على port عشوائي
const NEW_CHECKOUT = Boolean(process.env.FEATURE_NEW_CHECKOUT); // "false" ← true

app.post("/orders", async (req, res) => {
  const body = req.body as CreateOrder;     // "as" مش بيشيك أي حاجة. ده وعد، والـ client مش ملزوم بيه
  const total = body.items.reduce((s, i) => s + i.qty, 0); // qty جت "2" ← "02"، و items مش موجودة ← crash
  const { rows } = await db.query("select id, total_cents, created_at from orders where id = $1", [req.params.id]);
  const order = rows[0] as Order;           // total_cents bigint ← pg بيرجّعه string، و totalCents مش موجود أصلًا
  res.json(await db.users.find(body.email)); // والـ passwordHash طالع مع الـ user
});

queue.on("message", (text: string) => {
  const e = JSON.parse(text) as PaymentEvent; // JSON.parse بيرجّع any، و type جديد من الـ provider ← ولا حاجة بتحصل
  if (e.type === "payment.succeeded") credit(e.amountCents);
});

// types.ts: الـ types بتطلع من الـ schemas، فمفيش حاجتين تتكتبوا وتختلفوا
import { z } from "zod";
import { CreateOrder, Email, UserId, PaymentEvent, OrderRow, Env } from "./boundaries.js";

export type CreateOrderInput = z.input<typeof CreateOrder>;  // اللي الـ client بيبعته: currency اختياري
export type CreateOrder = z.output<typeof CreateOrder>;      // بعد الـ parse: currency موجود دايمًا
export type Email = z.infer<typeof Email>;                   // string & { [z.$brand]: "Email" }
export type UserId = z.infer<typeof UserId>;
export type PaymentEvent = z.infer<typeof PaymentEvent>;     // union، والـ type هو الـ discriminator
export type Order = z.output<typeof OrderRow>;               // { id, totalCents: number, status, createdAt: Date }
export type Config = Readonly<z.infer<typeof Env>>;

// branded: الـ compiler مش هيقبل string عادي مكان Email، لازم يعدّي على Email.parse
declare function sendReceipt(to: Email, user: UserId): void;
// sendReceipt("[email protected]", id)          ← error وقت الـ compile
// sendReceipt(Email.parse(input), id)   ← تمام

// exhaustive: لو حد زوّد type جديد في الـ union، الـ switch اللي ما غطّاهوش مش هيعمل compile
export function assertNever(x: never): never {
  throw new Error(`Unexpected: ${JSON.stringify(x)}`);
}

// lab.js: نفس الـ data البايزة، مرة من غير boundaries ومرة معاها
import { loadEnv, CreateOrder, formatIssues, parseJson, handleEvent, rowToOrder, toPublicUser, createApp } from "./boundaries.js";

console.log("— 1) الـ env —");
const raw = { PORT: "80O0", DATABASE_URL: "postgres://app:pw@db/shop", FEATURE_NEW_CHECKOUT: "false" };
console.log("  من غير:", { port: Number(raw.PORT), newCheckout: Boolean(raw.FEATURE_NEW_CHECKOUT) });
try { loadEnv(raw); } catch (e) { console.log("  معاها: الـ app ما قامش:", e.issues); }
console.log("  مظبوط:", loadEnv({ ...raw, PORT: "8000" }));

console.log("\n— 2) body من client —");
const body = { items: [{ sku: "MUG-1", qty: "2" }, { sku: "TSHIRT-M", qty: 1 }], email: "[email protected]", isAdmin: true };
console.log("  من غير: totalQty =", JSON.stringify(body.items.reduce((s, i) => s + i.qty, 0)));
console.log("  معاها:", formatIssues(CreateOrder.safeParse(body).error).map((i) => `${i.path} ${i.code}`));

console.log("\n— 3) row من pg —");
const row = { id: "7f1c1a52-8a3e-4c39-9b55-0d3c6d6c5a11", total_cents: "1999", status: "paid", created_at: "2026-03-01T10:00:00Z" };
console.log("  من غير: total + 1 =", JSON.stringify(row.total_cents + 1));
const o = rowToOrder(row);
console.log("  معاها: totalCents + 1 =", o.totalCents + 1, "، و createdAt:", o.createdAt.toISOString());

console.log("\n— 4) events من الـ queue —");
for (const text of ['{"type":"payment.succeeded","id":"e1","amountCents":15000,"currency":"EGP"}', '{"type":"payment.disputed","id":"e2"}', '{"type":"payment.succeeded","id":"e3","amountCents":"15000"}', "<html>"]) {
  const p = parseJson(text, { safeParse: (v) => ({ success: true, data: v }) });
  console.log(" ", text.slice(0, 32).padEnd(32), "←", p.ok ? ((r) => (r.status === "ok" ? r.result : `rejected: ${r.issues.map((i) => `${i.path} ${i.code}`).join(" , ")}`))(handleEvent(p.data)) : `rejected: ${p.issues[0].code}`);
}

console.log("\n— 5) الـ response —");
const user = { id: "u1", email: "[email protected]", name: "سارة", passwordHash: "$argon2id$v=19$...", mfaSecret: "JBSWY3DP" };
console.log("  من غير:", JSON.stringify(user));
console.log("  معاها:", JSON.stringify(toPublicUser(user)));

console.log("\n— 6) HTTP —");
const server = createApp().listen(0);
await new Promise((r) => server.once("listening", r));
const url = `http://127.0.0.1:${server.address().port}`;
const send = async (path, init) => { const r = await fetch(url + path, init); return `${r.status} ${JSON.stringify(await r.json()).slice(0, 150)}`; };
const json = (b) => ({ method: "POST", headers: { "content-type": "application/json" }, body: typeof b === "string" ? b : JSON.stringify(b) });
console.log("  POST سليم:", await send("/orders", json({ items: [{ sku: "MUG-1", qty: 2 }], email: "[email protected]" })));
console.log("  POST بايز:", await send("/orders", json(body)));
console.log("  JSON مكسور:", await send("/orders", json('{"items": [')));
console.log("  GET limit=5:", await send("/orders?limit=5"));
console.log("  GET limit=1000:", await s
…