Backend-এর গঠন — controller, service, repository আর dependency injection

১ · এক ফাইলের route কেন একদিন আর চলে না

পর্ব ২৫ থেকে পর্ব ২৮ পর্যন্ত আপনি Express-এর route, middleware, যাচাই আর error handling দেখেছেন। সব কোড এক ফাইলে রাখলেও প্রথম মাসে কোনো সমস্যা হয় না। বাজারঘরের POST /orders route-টি ত্রিশ-চল্লিশ লাইনের, আর পুরো ছবি এক পাতায় দেখা যায়।

তারপর দোকান চলতে শুরু করে। মালিক চান admin panel থেকেও অর্ডার বসাতে। হিসাব বিভাগ চান রাতে একটি নির্দিষ্ট সময়ে নিজে থেকে চলা cron job, যা বাকি অর্ডার মিলিয়ে দেখবে। ঈদের কুপন আসে, আসে নতুন delivery charge. আর একদিন কেউ জানতে চান, “১০০০ টাকার নিয়মটি ঠিক আছে তো?” এর উত্তর দিতে এখন একটি server চালু করতে হয়, database ভরতে হয়, আর HTTP request পাঠাতে হয়।

সমস্যাটি লাইনের সংখ্যা নয়। সমস্যা হলো তিন রকম জ্ঞান এক জায়গায় জড়িয়ে গেছে:

• HTTP-র জ্ঞান: req.body, status 409, JSON.
• দোকানের নিয়ম: stock-এর বেশি নয়, কুপনে ১০% ছাড়, ১০০০ টাকায় delivery ফ্রি।
• Data-র জ্ঞান: কোন table, কোন SQL, কোন column-এর নাম।

এই ভাগের ধারণা আপনি পর্ব ০৪-এ দেখেছেন। সেখানে একটি ছোট কার্ট দিয়ে “কেন” বোঝা হয়েছে। এই পর্বে আমরা একটি সত্যিকারের Express 5 আর TypeScript প্রজেক্টে “কীভাবে” করব: একটি পূর্ণ order route ভাঙব, জোড়া লাগাব, test করব, আর শেষে দামটিও হিসাব করব। পর্ব ০৪-এ separation of concerns-এর যে ভিত্তি আছে, সেটি আর পুনরাবৃত্তি করব না।

২ · চারটি স্তর — কোন কোড কোথায় যাবে

আমরা চারটি স্তর নেব। পর্ব ০৪-এর তিন স্তরের সাথে এখানে route আলাদা করে গোনা হলো, কারণ Express-এ ঠিকানার তালিকা আর HTTP-র কাজ আলাদা ফাইলে রাখা সুবিধার।

একটি লেখা কোন স্তরে যাবে, সেটি ঠিক করতে তিনটি সহজ প্রশ্ন করুন।

কিছু কাজ সীমানায় পড়ে, আর সেগুলো নিয়েই ভুল বেশি হয়:

এবার বাজারঘরের একটি অর্ডার চার স্তরের ভেতর দিয়ে যেতে দেখুন। ক্রেতা ২ প্যাকেট ৫ কেজির চাল নিচ্ছেন, কুপন EID10. চালের দাম ৪২,০০০ পয়সা, stock 3. টাকা সবসময় পূর্ণসংখ্যা পয়সায় রাখা হয়েছে। প্রতিটি ধাপে কোন স্তর কতটুকু জানে, সেটি খেয়াল করুন।

POST /orders
content-type: application/json

{"customerId":"c1",
 "items":[{"productId":"chal-5kg","qty":2}],
 "coupon":"EID10"}

app.use('/orders', createOrderRouter(controller));
router.post('/', controller.create);

const input = placeOrderSchema.parse(req.body);
// qty: 2 পূর্ণসংখ্যা, ঠিক আছে
const receipt = await service.place(input);

subtotal = 2 * 42000           = 84000
discount = floor(84000 / 10)   = 8400
after    = 84000 - 8400        = 75600
delivery = 75600 < 100000 তাই  = 6000
total    = 75600 + 6000        = 81600

UPDATE products SET stock = stock - ?
 WHERE id = ? AND stock >= ?
-- 2, 'chal-5kg', 2  →  stock 3 থেকে 1
INSERT INTO orders (customer_id, total_paisa, lines)
VALUES (?, ?, ?)
-- নতুন order id = 1

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{"id":1,"subtotal":84000,"discount":8400,
 "delivery":6000,"total":81600}

৩ · মোটা order route ভাঙা — ধাপে ধাপে

নিচে সেই আসল route. এটি আমাদের পরীক্ষার প্রজেক্টে সত্যিই চলেছে, আর SQL parameterized হওয়ায় নিরাপদও। তবে এটি একটি fat controller: এক ফাংশনে ইনপুট যাচাই, stock, ছাড়, delivery, SQL, SMS আর HTTP-র উত্তর।

app.post('/orders', (req, res) => {
  const { customerId, items, coupon } = req.body ?? {};
  if (typeof customerId !== 'string' || !customerId ||
      !Array.isArray(items) || items.length === 0) {
    return res.status(400).json({ error: 'BAD_INPUT' });
  }
  const lines = [];
  let subtotal = 0;
  for (const item of items) {
    if (!Number.isInteger(item?.qty) || item.qty < 1) {
      return res.status(400).json({ error: 'BAD_INPUT' });
    }
    const p: any = db.prepare('SELECT * FROM products WHERE id = ?').get(item.productId);
    if (!p) return res.status(404).json({ error: 'PRODUCT_NOT_FOUND' });
    if (item.qty > p.stock) return res.status(409).json({ error: 'OUT_OF_STOCK' });
    subtotal += item.qty * p.price_paisa;
    lines.push({ productId: p.id, qty: item.qty, unitPaisa: p.price_paisa });
  }
  if (coupon !== undefined && coupon !== 'EID10') {
    return res.status(422).json({ error: 'BAD_COUPON' });
  }
  const discount = coupon === 'EID10' ? Math.floor(subtotal / 10) : 0;
  const delivery = subtotal - discount >= 100000 ? 0 : 6000;
  const total = subtotal - discount + delivery;
  for (const l of lines) {
    db.prepare('UPDATE products SET stock = stock - ? WHERE id = ?').run(l.qty, l.productId);
  }
  const r = db.prepare('INSERT INTO orders (customer_id, total_paisa, lines) VALUES (?, ?, ?)')
    .run(customerId, total, JSON.stringify(lines));
  const id = Number(r.lastInsertRowid);
  sms('order ' + id + ' total ' + total);
  res.status(201).json({ id, subtotal, discount, delivery, total });
});

এখন ভাঙার পালা। Refactoring মানে বাইরের আচরণ না বদলে ভেতরের গঠন বদলানো। ঝুঁকি হলো, কিছু একটা চুপচাপ বদলে যেতে পারে। তাই প্রথম কাজ কোড সরানো নয়, প্রথম কাজ একটি জাল পাতা: characterization test. এই test বলে না কোডটি কেমন হওয়া উচিত। এটি শুধু লিখে রাখে কোডটি এখন কী করছে। Michael Feathers তাঁর ২০০৪ সালের Working Effectively with Legacy Code বইয়ে এই ধারণাটি জনপ্রিয় করেন। Code smell আর refactoring-এর সাধারণ তত্ত্ব আছে Code smell ও refactoring পর্বে।

আমাদের জালটি একটি ছোট script. সে একই ৭টি request মোটা route আর নতুন গঠন, দুই জায়গাতেই পাঠিয়ে উত্তর মেলায়। নিচের ধাপগুলোতে ব্যবসার একটি নিয়ম route থেকে service-এ সরতে দেখুন।

if (item.qty > p.stock)
  return res.status(409).json({ error: 'OUT_OF_STOCK' });

201 {"id":1,"subtotal":84000,...}
409 {"error":"OUT_OF_STOCK"}
404 {"error":"PRODUCT_NOT_FOUND"}
...
৭টি উত্তর লিখে রাখা হলো

if (item.qty > p.stock) throw new OrderError('OUT_OF_STOCK');

// error-handler.ts
const STATUS = { PRODUCT_NOT_FOUND: 404, OUT_OF_STOCK: 409,
                 BAD_COUPON: 422 };

const FREE_DELIVERY_FROM = 100000;
const DELIVERY_PAISA = 6000;
const delivery =
  subtotal - discount >= FREE_DELIVERY_FROM ? 0 : DELIVERY_PAISA;

same 409 {"error":"OUT_OF_STOCK"}
...
7/7 responses identical

পুরো কাজের ক্রমটি এমন: প্রথমে জাল, তারপর repository, তারপর service, তারপর controller, শেষে route আর startup-এ জোড়া। প্রতিটি ধাপের পরে জাল আবার চালানো হয়। নিচের ছোট সংস্করণটি নিজে চালিয়ে দেখুন। এখানে HTTP-র জায়গায় একটি সাধারণ object আছে, আর দুই গঠনে একই request যাচ্ছে।

const newDb = () => ({ stock: { "chal-5kg": 3 }, paisa: { "chal-5kg": 42000 }, orders: [] });
const fail = (status, error) => ({ status, json: { error } });
const off = (sub, c) => (c === "EID10" ? Math.floor(sub / 10) : 0);
const finalTotal = (s, c) => s - off(s, c) + (s - off(s, c) >= 100000 ? 0 : 6000);
// আগে: HTTP-র উত্তর, নিয়ম আর data এক ফাংশনে
function fatHandler(db, { id, qty, coupon }) {
  if (!(qty >= 1)) return fail(400, "BAD_INPUT");
  if (qty > db.stock[id]) return fail(409, "OUT_OF_STOCK");
  const total = finalTotal(qty * db.paisa[id], coupon);
  db.stock[id] -= qty; db.orders.push({ id, qty, total });
  return { status: 201, json: { total } };
}
// পরে: repository, service আর controller আলাদা
const makeRepo = (db) => ({
  stockOf: (id) => db.stock[id], paisaOf: (id) => db.paisa[id],
  take(id, qty) { db.stock[id] -= qty; }, save(o) { db.orders.push(o); },
});
function place(repo, { id, qty, coupon }) {         // service: HTTP চেনে না
  if (qty > repo.stockOf(id)) throw new Error("OUT_OF_STOCK");
  const total = finalTotal(qty * repo.paisaOf(id), coupon);
  repo.take(id, qty); repo.save({ id, qty, total });
  return { total };
}
function controller(repo, body) {                   // controller: শুধু HTTP
  if (!(body.qty >= 1)) return fail(400, "BAD_INPUT");
  try { return { status: 201, json: place(repo, body) }; }
  catch (e) { return fail(409, e.message); }
}
const a = newDb(), b = newDb(), repo = makeRepo(b), id = "chal-5kg";
for (const c of [{ id, qty: 2, coupon: "EID10" }, { id, qty: 2 }, { id, qty: 0 }]) {
  const x = JSON.stringify(fatHandler(a, c)), y = JSON.stringify(controller(repo, c));
  console.log(x === y ? "same" : "DIFF", y);
}
console.log("stock:", a.stock[id], b.stock[id], "orders:", a.orders.length, b.orders.length);

same {"status":201,"json":{"total":81600}}
same {"status":409,"json":{"error":"OUT_OF_STOCK"}}
same {"status":400,"json":{"error":"BAD_INPUT"}}
stock: 1 1 orders: 1 1

এবার আসল Express প্রজেক্ট। পূর্ণ route ভেঙে একই ৭টি request দুই server-এ পাঠানো হলো। সত্যিকারের run. লেখার সময়ের সংস্করণ: Node 24.15.0, Express 5.3.0, TypeScript 7.0.2, tsx 4.23.15, Zod 4.6.7. Data রাখা হয়েছে Node-এর নিজস্ব node:sqlite module-এ, যাতে বাড়তি কিছু লাগে না। Prisma আসবে পর্ব ৩৯-এ।

~/bazarghar$ npx tsx scripts/compare.ts
same 201 {"id":1,"subtotal":84000,"discount":8400,"delivery":6000,"total":81600}
same 409 {"error":"OUT_OF_STOCK"}
same 201 {"id":2,"subtotal":109000,"discount":0,"delivery":0,"total":109000}
same 404 {"error":"PRODUCT_NOT_FOUND"}
same 400 {"error":"BAD_INPUT"}
same 422 {"error":"BAD_COUPON"}
same 400 {"error":"BAD_INPUT"}
7/7 responses identical

ভাঙার পরে route, controller আর service এমন দাঁড়াল। Controller-এ try/catch নেই, কারণ Express 5-এ async handler-এর rejected promise নিজে থেকেই error middleware-এ পৌঁছায়। Express-এর docs-এ এই আচরণ লেখা আছে।

export function createOrderRouter(controller: OrderController) {
  const router = Router();
  router.post('/', controller.create);
  return router;
}

export function createOrderController(service: OrderService) {
  return {
    async create(req: Request, res: Response) {
      const input = placeOrderSchema.parse(req.body);
      const receipt = await service.place(input);
      res.status(201).json(receipt);
    },
  };
}

export function createOrderService({ repo, notify }: OrderServiceDeps) {
  return {
    async place(input: PlaceOrderInput): Promise<Receipt> {
      const lines: OrderLine[] = [];
      let subtotal = 0;
      for (const item of input.items) {
        const p = await repo.findProduct(item.productId);
        if (!p) throw new OrderError('PRODUCT_NOT_FOUND');
        if (item.qty > p.stock) throw new OrderError('OUT_OF_STOCK');
        subtotal += item.qty * p.pricePaisa;
        lines.push({ productId: p.id, qty: item.qty, unitPaisa: p.pricePaisa });
      }
      // ... কুপন, ছাড় আর delivery-র হিসাব ...
      for (const l of lines) {
        if (!(await repo.reserveStock(l.productId, l.qty))) {
          throw new OrderError('OUT_OF_STOCK');
        }
      }
      const order = await repo.saveOrder({
        customerId: input.customerId, lines, totalPaisa: total,
      });
      await notify('order ' + order.id + ' total ' + total);
      return { id: order.id, subtotal, discount, delivery, total };
    },
  };
}

const STATUS: Record<OrderErrorCode, number> = {
  PRODUCT_NOT_FOUND: 404, OUT_OF_STOCK: 409, BAD_COUPON: 422,
};

export function errorHandler(err: unknown, _req: Request, res: Response, _next: NextFunction) {
  if (err instanceof ZodError) return res.status(400).json({ error: 'BAD_INPUT' });
  if (err instanceof OrderError) return res.status(STATUS[err.code]).json({ error: err.code });
  console.error(err);
  res.status(500).json({ error: 'INTERNAL' });
}

৪ · Folder আর নির্ভরতার দিক

পর্ব ০৪-এ আপনি layer অনুযায়ী আর feature অনুযায়ী folder-এর তুলনা দেখেছেন। প্রশ্নটি সহজ: একটি বদলের জন্য কয়টি folder ঘুরতে হয়? আমাদের প্রজেক্টের আসল গঠন এটি:

src/
  main.ts                 চালু করা
  compose.ts              সব জোড়া লাগানো
  app.ts                  Express অ্যাপ
  http/
    error-handler.ts
  db/
    sqlite.ts
  features/
    orders/
      order.routes.ts
      order.controller.ts
      order.schema.ts
      order.service.ts
      order.service.test.ts
      order.types.ts
      order.repository.ts          চুক্তি
      order.repository.sqlite.ts   আসল
      order.repository.memory.ts   test-এর জন্য

Feature folder আসলে modular monolith-এর ছোট রূপ। তবে দুই feature-এর সীমানায় নিয়ম মানতে হয়: cart সরাসরি order-এর repository ছোঁবে না, সে order-এর service ডাকবে। না হলে সীমানা শুধু folder-এর নামেই থাকে।

তীর কোন দিকে

Folder ঠিক করে ফাইল কোথায় থাকবে। আসল সিদ্ধান্তটি অন্য: কে কাকে import করবে। সাধারণ layered architecture-এ তীর নিচের দিকে যায়। ফলে service সরাসরি SQLite-এর কোড চেনে, আর database বদলালে service-ও ছুঁতে হয়।

আমরা একটি ছোট চালাকি করেছি। চুক্তিটি (OrderRepository interface) service-এর পাশে থাকে, আর আসল SQLite class সেই চুক্তি মেনে চলে। ফলে নিচের স্তরের তীর ওপরের দিকে ঘুরে যায়। এই নীতির নাম dependency inversion. ওপরের স্তর নিচের স্তরের খুঁটিনাটির ওপর নির্ভর করে না, দুজনেই একটি চুক্তির ওপর নির্ভর করে। পুরো তত্ত্ব আছে SOLID: LSP, ISP আর DIP পর্বে, আর সব design pattern-এর পরিচয় আছে Design pattern পর্বে।

এই দাবিটি চোখে না দেখে সত্যিই যাচাই করা যায়। সত্যিকারের run:

~/bazarghar$ grep -l "express" src/features/orders/*.ts
src/features/orders/order.controller.ts
src/features/orders/order.routes.ts

~/bazarghar$ grep -lE "SELECT|node:sqlite" src/features/orders/*.ts src/http/*.ts src/app.ts src/compose.ts
src/features/orders/order.repository.sqlite.ts

Order feature-এর ভেতরে Express আছে শুধু দুটি ফাইলে, আর SQL পুরো প্রজেক্টের এই তালিকায় শুধু একটিতে। order.service.ts দুই তালিকার কোনোটিতেই নেই। এই নিয়ম বড় প্রজেক্টে CI-তে একটি lint rule বা ছোট script দিয়ে পাহারা দেওয়া যায়। না হলে ব্যস্ত দিনে কেউ একটি import বসিয়ে দেবেন, আর সীমানা ভাঙবে। Circular dependency-ও এই একই তীরের ভুল থেকে আসে।

৫ · Dependency injection — শুধু function parameter

নামটি ভারী, কাজটি সরল। Dependency injection মানে একটি অংশ তার দরকারি জিনিস নিজে বানায় না, বাইরে থেকে পায়। তফাতটি একটি লাইনেই দেখা যায়:

// আগে: service নিজেই database বেছে নিয়েছে। test-এ বদলানোর পথ নেই।
import { db } from '../db';
export async function place(input) { db.prepare('...'); }

// পরে: যা লাগবে, parameter-এ চাইছে। কে দেবে, সেটি service জানে না।
export function createOrderService({ repo, notify }: OrderServiceDeps) { ... }

এখানে কোনো library নেই, কোনো decorator নেই। শুধু JavaScript-এর closure: createOrderService যে object ফেরত দেয়, তার ভেতরের ফাংশন repo-কে মনে রাখে। সব object কোথাও একবার বানাতে হয়। সেই এক জায়গার নাম composition root. আমাদের ক্ষেত্রে এটি compose.ts. নিচের ধাপগুলোতে server চালু হওয়ার মুহূর্তটি দেখুন।

1const db = openDb();2function compose(db, sms) {3  const repo = new SqliteOrderRepository(db);4  const service = createOrderService({ repo, notify });5  const orderController = createOrderController(service);6  return createApp({ orderController });7}8app.listen(4329, '127.0.0.1');

লক্ষ করুন, new আর create... সব এই একটি ফাইলে। বাকি কোডে কেউ কাউকে তৈরি করে না। নিচের block-এ একই service-এর নিচে দুটি ভিন্ন repository বসিয়ে দেখুন। একটি Map ব্যবহার করে, আরেকটি array.

// service একবারই লেখা; repository চেনে শুধু তিনটি method দিয়ে
function createService(repo) {
  return {
    place(id, qty) {
      const p = repo.find(id);
      if (!p || qty > p.stock) return "REJECTED";
      repo.setStock(id, p.stock - qty);
      return `OK total=${qty * p.paisa} left=${repo.find(id).stock}`;
    },
    report: () => repo.all().map((p) => `${p.id}:${p.stock}`).join(" "),
  };
}
const seed = [{ id: "chal", paisa: 42000, stock: 3 }, { id: "dal", paisa: 14000, stock: 10 }];

function mapRepo() {                  // Map: id দিয়ে সরাসরি খোঁজা
  const rows = new Map(seed.map((p) => [p.id, { ...p }]));
  return {
    find: (id) => rows.get(id) ?? null,
    setStock: (id, n) => { rows.get(id).stock = n; },
    all: () => [...rows.values()],
  };
}
function arrayRepo() {                // array: প্রতিবার সারি ধরে খোঁজা
  const rows = seed.map((p) => ({ ...p }));
  return {
    find: (id) => rows.find((p) => p.id === id) ?? null,
    setStock: (id, n) => { rows.find((p) => p.id === id).stock = n; },
    all: () => [...rows],
  };
}
for (const [name, make] of [["map", mapRepo], ["array", arrayRepo]]) {
  const s = createService(make());    // শুধু এখানেই ঠিক হয় কোন repository
  console.log(name, s.place("chal", 2), "|", s.place("chal", 2), "|", s.report());
}

map OK total=84000 left=1 | REJECTED | chal:1 dal:10
array OK total=84000 left=1 | REJECTED | chal:1 dal:10

~/bazarghar$ npx tsx scripts/swap.ts
memory {"id":1,"subtotal":84000,"discount":8400,"delivery":6000,"total":81600}
sqlite {"id":1,"subtotal":84000,"discount":8400,"delivery":6000,"total":81600}

DI শুধু database-এর জন্য নয়। যা কিছু বাইরের জগৎ ছোঁয় বা অনিশ্চিত, সেটি parameter-এ নেওয়ার যোগ্য: SMS gateway, ঘড়ি (now()), দৈব সংখ্যা, payment gateway. আমাদের service-এ notify ঠিক এমন একটি। তবে সবকিছু inject করবেন না। Math.floor বা একটি pure function নকল করার কোনো অর্থ নেই।

৬ · TypeScript interface — repository-র চুক্তি

JavaScript-এ repository বদলানোর সময় ভুল ধরা পড়ে চলতে গিয়ে। TypeScript-এর interface এই চুক্তিটি লিখিত করে দেয়। ভাষার মূল কথা আছে পর্ব ০৬-এ। আমাদের চুক্তিটি মাত্র নয় লাইনের ফাইল:

import type { NewOrder, Order, Product } from './order.types.ts';

// চুক্তি: service শুধু এটুকুই চেনে
export interface OrderRepository {
  findProduct(id: string): Promise<Product | null>;
  reserveStock(id: string, qty: number): Promise<boolean>;
  saveOrder(order: NewOrder): Promise<Order>;
  findOrder(id: number): Promise<Order | null>;
}

চারটি সিদ্ধান্ত খেয়াল করুন:

• সবকিছু Promise: SQLite-এর এই API synchronous, কিন্তু পরের database নাও হতে পারে। চুক্তি আসল প্রযুক্তির সীমা ফাঁস করে না।
• না পেলে null: Repository জানে না “না পাওয়া” 404 কি না। সেই সিদ্ধান্ত service-এর।
• ফেরত আসে দোকানের ভাষায়: pricePaisa, price_paisa নয়। Column-এর নাম repository-র বাইরে যায় না।
• নামগুলো কাজের নাম: reserveStock, updateRow নয়।

নিচের block-টি strict mode-এ চলে। Service একটি interface চেনে, class নয়। null যাচাইয়ের পরে TypeScript নিজেই বোঝে p আর null নয়, একে বলে narrowing. ফলাফল একটি discriminated union.

interface Product { id: string; pricePaisa: number; stock: number }

interface OrderRepository {
  findProduct(id: string): Promise<Product | null>;
  reserveStock(id: string, qty: number): Promise<boolean>;
}
class MapRepository implements OrderRepository {
  private rows = new Map<string, Product>();
  constructor(seed: Product[]) { seed.forEach((p) => this.rows.set(p.id, { ...p })); }
  async findProduct(id: string) { return this.rows.get(id) ?? null; }
  async reserveStock(id: string, qty: number) {
    const p = this.rows.get(id);
    if (!p || p.stock < qty) return false;
    p.stock -= qty;
    return true;
  }
}

type Result = { ok: true; totalPaisa: number } | { ok: false; code: "NOT_FOUND" | "OUT_OF_STOCK" };

// service চেনে শুধু interface, কোনো class নয়
async function place(repo: OrderRepository, id: string, qty: number): Promise<Result> {
  const p = await repo.findProduct(id);
  if (p === null) return { ok: false, code: "NOT_FOUND" };   // এরপর p আর null নয়
  if (!(await repo.reserveStock(id, qty))) return { ok: false, code: "OUT_OF_STOCK" };
  return { ok: true, totalPaisa: qty * p.pricePaisa };
}

async function main() {
  const repo = new MapRepository([{ id: "chal", pricePaisa: 42000, stock: 3 }]);
  for (const [id, qty] of [["chal", 2], ["chal", 2], ["tel", 1]] as const) {
    console.log(id, qty, JSON.stringify(await place(repo, id, qty)));
  }
}
main();

chal 2 {"ok":true,"totalPaisa":84000}
chal 2 {"ok":false,"code":"OUT_OF_STOCK"}
tel 1 {"ok":false,"code":"NOT_FOUND"}

এবার চুক্তি ভাঙলে কী হয়। একটি repository-তে findOrder লিখতে ভুলে গেলাম, আর আরেক জায়গায় service-কে আধখানা object দিলাম। npm run typecheck-এর সত্যিকারের দুটি ফল (TypeScript 7.0.2):

src/bad.ts(4,14): error TS2420: Class 'HalfRepository' incorrectly implements interface 'OrderRepository'.
  Property 'findOrder' is missing in type 'HalfRepository' but required in type 'OrderRepository'.

src/bad.ts(9,22): error TS2739: Type '{ findProduct: () => Promise<null>; }' is missing the following properties from type 'OrderRepository': reserveStock, saveOrder, findOrder

ভুলটি production-এ পৌঁছানোর আগেই ধরা পড়ল। তবে একটি সীমা মনে রাখুন। Interface শুধু আকার দেখে, আচরণ দেখে না। reserveStock সব সময় true ফেরত দিলেও type মিলবে। আচরণ মেলাতে দরকার contract test: একই test-গুলো দুটি repository-র ওপর চালানো।

const makers: [string, () => OrderRepository][] = [
  ['memory', () => new MemoryOrderRepository([/* chal-5kg, stock 3 */])],
  ['sqlite', () => new SqliteOrderRepository(openDb())],
];

describe.each(makers)('OrderRepository contract: %s', (_name, make) => {
  it('reserves stock only when enough is left', async () => {
    const repo = make();
    expect(await repo.reserveStock('chal-5kg', 2)).toBe(true);
    expect(await repo.reserveStock('chal-5kg', 2)).toBe(false);
    expect((await repo.findProduct('chal-5kg'))?.stock).toBe(1);
  });
});

এখন নকল repository আসলের মতো আচরণ করে, এই দাবিটি আর বিশ্বাসের বিষয় নয়। প্রতিবার test চালালেই সেটি যাচাই হয়। একটি কথা: সব table-এর জন্য একটি generic Repository<T> বানানো জনপ্রিয় অভ্যাস, কিন্তু order আর product-এর কাজ এক নয়। সাধারণত কাজের নামে লেখা ছোট interface-ই বেশি পরিষ্কার। আমাদের ছোট প্রজেক্টে একটি interface-এই পণ্য আর অর্ডার রাখা হয়েছে। বড় হলে এটি দুটি ভাগ হওয়া স্বাভাবিক।

৭ · নকল repository দিয়ে service test

পুরো পরিশ্রমের সবচেয়ে বড় ফল এখানে। মোটা route-এ “৮৪,০০০ পয়সায় ছাড় কত” যাচাই করতে server আর database লাগত। এখন service-কে একটি নকল repository দিলেই হয়। এমন বদলি জিনিসের সাধারণ নাম test double. এর নানা রূপ (stub, spy, mock, fake) নিয়ে তত্ত্ব আছে Test double পর্বে। আগে হাতে একটি বানিয়ে দেখুন, কোনো test library ছাড়াই।

const assert = require("node:assert/strict");
function createOrderService({ repo, notify }) {
  return {
    async place({ productId, qty, coupon }) {
      const p = await repo.findProduct(productId);
      if (qty > p.stock) throw new Error("OUT_OF_STOCK");
      const subtotal = qty * p.pricePaisa;
      const discount = coupon === "EID10" ? Math.floor(subtotal / 10) : 0;
      const delivery = subtotal - discount >= 100000 ? 0 : 6000;
      const total = subtotal - discount + delivery;
      await repo.reserveStock(productId, qty);
      const order = await repo.saveOrder({ productId, qty, total });
      await notify(`order ${order.id} total ${total}`);
      return { id: order.id, subtotal, discount, delivery, total };
    },
  };
}
// নকল repository: database নেই, শুধু কে কী ডাকল তার হিসাব
function fakeRepo(stock) {
  const calls = [];
  return { calls,
    findProduct: async () => ({ pricePaisa: 42000, stock }),
    reserveStock: async (id, qty) => { calls.push(`reserve ${qty}`); stock -= qty; return true; },
    saveOrder: async (o) => { calls.push("save"); return { id: 7, ...o }; },
  };
}
(async () => {
  const repo = fakeRepo(3), sms = [];
  const s = createOrderService({ repo, notify: async (m) => { sms.push(m); } });
  const r = await s.place({ productId: "chal-5kg", qty: 2, coupon: "EID10" });
  assert.deepEqual(r, { id: 7, subtotal: 84000, discount: 8400, delivery: 6000, total: 81600 });
  await assert.rejects(s.place({ productId: "chal-5kg", qty: 2 }), /OUT_OF_STOCK/);
  assert.deepEqual(repo.calls, ["reserve 2", "save"]);
  console.log("3 checks passed; calls:", repo.calls, "sms:", sms);
})();

3 checks passed; calls: [ 'reserve 2', 'save' ] sms: [ 'order 7 total 81600' ]

আসল প্রজেক্টে এই কাজটি করে Vitest. Vitest-এর পুরো ব্যবহার আসবে পর্ব ৭৩-এ, আর test কৌশল পর্ব ৭২-এ। এখানে শুধু কাঠামোটি দেখুন। notify হিসেবে দেওয়া হয়েছে vi.fn, যা মনে রাখে তাকে কীভাবে ডাকা হলো।

function setup() {
  const repo = new MemoryOrderRepository(seed);
  const notify = vi.fn(async (_m: string) => {});
  return { repo, notify, service: createOrderService({ repo, notify }) };
}

it('out of stock: nothing saved, no sms', async () => {
  const { service, repo, notify } = setup();
  await expect(service.place({ customerId: 'c1', items: [chal(4)] }))
    .rejects.toMatchObject({ code: 'OUT_OF_STOCK' });
  expect(await repo.findOrder(1)).toBeNull();
  expect(notify).not.toHaveBeenCalled();
});

সত্যিকারের run (Vitest 5.0.5, Node 24.15.0). সময়গুলো এক কম্পিউটারের একবারের মাপ, কোনো সাধারণ ফল নয়:

~/bazarghar$ npx vitest run --reporter=verbose
 ✓ ...contract.test.ts > OrderRepository contract: memory > finds a product, or null 1ms
 ✓ ...contract.test.ts > OrderRepository contract: memory > reserves stock only when enough is left 0ms
 ✓ ...contract.test.ts > OrderRepository contract: memory > saves and reads an order 0ms
 ✓ ...contract.test.ts > OrderRepository contract: sqlite > finds a product, or null 1ms
 ✓ ...contract.test.ts > OrderRepository contract: sqlite > reserves stock only when enough is left 0ms
 ✓ ...contract.test.ts > OrderRepository contract: sqlite > saves and reads an order 0ms
 ✓ ...service.test.ts > order service > coupon: 10% discount, then delivery 2ms
 ✓ ...service.test.ts > order service > free delivery from 1000 taka after discount 0ms
 ✓ ...service.test.ts > order service > out of stock: nothing saved, no sms 1ms
 ✓ ...service.test.ts > order service > unknown coupon is rejected 0ms
 ✓ ...service.test.ts > order service > sends one sms after saving 0ms
 ✓ ...service.test.ts > order service > KNOWN GAP: save fails after stock is reserved 1ms

 Test Files  2 passed (2)
      Tests  12 passed (12)
   Duration  124ms

সবুজ test তখনই অর্থবহ, যখন ভুল হলে সে লাল হয়। তাই ইচ্ছা করে নিয়মটি নষ্ট করলাম: subtotal / 10-কে subtotal / 20 করলাম। সত্যিকারের ফল:

 FAIL  src/features/orders/order.service.test.ts > order service > coupon: 10% discount, then delivery
AssertionError: expected { id: 1, subtotal: 84000, …(3) } to deeply equal { id: 1, subtotal: 84000, …(3) }

- Expected
+ Received

  {
    "delivery": 6000,
-   "discount": 8400,
+   "discount": 4200,
    "id": 1,
    "subtotal": 84000,
-   "total": 81600,
+   "total": 85800,
  }
…
      Tests  1 failed | 5 passed (6)

Test ঠিক জায়গায় ধরল, আর পার্থক্যটি পয়সার হিসাবে দেখাল। তবে সীমাটিও সৎভাবে বলা দরকার। এই test দিয়ে প্রমাণ হয় না যে HTTP route ঠিকমতো জোড়া আছে, বা SQL সত্যিই চলে। সেই কাজ compare.ts আর contract test-এর, আর পূর্ণ integration test আসবে পর্ব ৭৫-এ। নকলের ওপর ভরসা মানে আসলকে ভুলে যাওয়া নয়।

৮ · দুটি সীমা — container আর transaction

Container কখন লাগে

compose.ts-এর চারটি লাইন আমরা হাতে লিখেছি। Object-এর সংখ্যা দুইশো হলে এই ফাইল বিরক্তিকর হয়ে ওঠে। তখন কাজে আসে DI container: একটি library, যাকে আপনি বলে দেন কোন জিনিসের কী লাগে, আর সে সঠিক ক্রমে সব বানিয়ে দেয়। Node-এর জগতে এর পরিচিত উদাহরণ NestJS. এই কোর্সে NestJS-এর আলাদা পর্ব নেই, তাই ছোট একটি সত্যিকারের run এখানেই দেখুন (NestJS 12.3.2):

const ORDER_REPOSITORY = Symbol('ORDER_REPOSITORY');

@Injectable()
class OrderService {
  constructor(@Inject(ORDER_REPOSITORY) private readonly repo: OrderRepository) {}
  total(id: string, qty: number) { return this.repo.findPrice(id) * qty; }
}

@Module({
  providers: [OrderService, { provide: ORDER_REPOSITORY, useClass: MemoryOrderRepository }],
})
class AppModule {}

async function main() {
  const app = await NestFactory.createApplicationContext(AppModule, { logger: false });
  console.log(app.get(OrderService).total('chal-5kg', 2));   // ছাপল 84000
  await app.close();
}
main();

এখানে কেউ new OrderService(...) লেখেনি। Decorator (@Injectable) দেখে container নিজে constructor-এর দরকার বুঝে নিয়েছে। Interface চলার সময় থাকে না, তাই ORDER_REPOSITORY নামের একটি আলাদা token লাগল। এটি inversion of control-এর একটি রূপ। Laravel-এর service container (পর্ব ৭০), Spring Boot (পর্ব ৭১) আর Angular-ও (পর্ব ৬৭) dependency injection-এর চিন্তা ব্যবহার করে।

এখানে সম্প্রদায় একমত নয়। অনেকে Node-এ হাতের জোড়াকেই যথেষ্ট মনে করেন, আবার বড় দল container-এর একই ধাঁচ পছন্দ করে। সৎ পরামর্শ: Express-এর ছোট বা মাঝারি প্রজেক্টে parameter দিয়ে শুরু করুন। যে framework container নিয়েই আসে, সেখানে তার পথেই চলুন।

Transaction কোথায় আটকায়

আমাদের service-এ একটি সত্যিকারের ফাঁক আছে, আর সেটি আমরা ইচ্ছা করে test-এ লিখে রেখেছি। Stock কমানো আর অর্ডার লেখা দুটি আলাদা repository ডাক। মাঝখানে কিছু ভাঙলে?

it('KNOWN GAP: save fails after stock is reserved', async () => {
  // ... saveOrder ইচ্ছা করে 'disk full' ছোড়ে ...
  await expect(s.place({ customerId: 'c1', items: [chal(2)] })).rejects.toThrow('disk full');
  expect((await repo.findProduct('chal-5kg'))?.stock).toBe(1); // ২টি হারিয়ে গেল
});

এই test পাস করেছে, আর সেটিই খারাপ খবর। Stock 3 থেকে 1 হয়েছে, কিন্তু কোনো অর্ডার নেই। ২ প্যাকেট চাল হিসাব থেকে উধাও। সমাধান হলো transaction: দুটি কাজ হয় একসাথে হবে, নয়তো একটিও না। ACID-এর তত্ত্ব আছে Transaction ও ACID পর্বে।

কিন্তু এখানেই স্তরের নকশায় একটি আসল টানাপোড়েন। Transaction শুরু করে database, অথচ “কোন কাজগুলো একসাথে” সেটি জানে service. আর দুটি service একই transaction-এ থাকতে হলে সমস্যা আরও বাড়ে, যেমন order service আর payment service. সাধারণ পথ দুটি: repository-তে একটি বড় placeOrder method রাখা, অথবা service-কে একটি withTransaction ধরনের সুবিধা inject করা। বাস্তব Prisma কোড আর race condition-এর পূর্ণ হিসাব আসবে পর্ব ৪৩-এ। আজ শুধু মনে রাখুন, স্তর ভাগ করলে এই সমস্যা নিজে থেকে যায় না, বরং চোখে পড়ে।

৯ · কখন তিন স্তর বাড়াবাড়ি

এবার দামের হিসাব। আমাদের প্রজেক্টের সত্যিকারের wc -l থেকে, test আর memory repository বাদ দিয়ে:

লাভটি লাইন কমানো নয়। লাভ হলো নিয়ম আলাদা test করা, repository বদলানো, আর এক জায়গায় কম বদল। অ্যাপে সেই লাভের দরকার না থাকলে এই ৪ গুণ শুধুই খরচ। পর্ব ৩৯-এর Prisma-র ওপরে আবার একটি repository বসানো নিয়েও বিতর্ক আছে, আর সে কথা ভাবনার প্রশ্নে আছে।

এই ধাপে ধাপে বাড়ার চিন্তার একটি পরিচিত নাম আছে YAGNI: যা এখন লাগছে না, সেটি এখন বানাবেন না। PoEAA বইয়ের Transaction Script ঠিক এই মোটা route-এর পরিপাটি রূপ: প্রতিটি কাজের জন্য একটি সোজা procedure. কম নিয়মের অ্যাপে এটি ভুল নয়, বরং সঠিক নকশা।

১০ · AI-এর যুগে — backend-এর গঠন যাচাই

AI-কে “একটি Express API বানাও” বললে সে প্রায়ই সুন্দর folder-এর গাছ বানিয়ে দেয়। Folder দেখে নকশা বিচার করা যায় না। তীর আর দায়িত্ব দেখতে হয়।

AI-এর লেখা গঠন হাতে পেলে — যাচাইয়ের চেকলিস্ট

• Service-এর ফাইলে Express আর SQL নেই, সেটি grep দিয়ে দেখেছি
• আগের আর পরের উত্তর একই request-এ মিলিয়েছি, ভুল ইনপুটসহ
• নিয়ম ইচ্ছা করে নষ্ট করে দেখেছি, test লাল হয়েছে
• package.json-এর diff পড়েছি, অপ্রয়োজনীয় package নেই, আর যা আছে সেটি সত্যিই npm-এ আছে
• Authorization আর validation প্রতিটি পথেই চলে, শুধু একটি route-এ নয়
• প্রতিটি স্তরের দাম বলতে পারি: এটি না থাকলে কী হারাত?