Type-safe API — tRPC, ভাগ করা schema আর code generation

১ · Frontend আর backend-এর মাঝের ফাঁক

পর্ব ০৬-এ দেখেছেন, TypeScript-এর type চলার সময় থাকে না। পর্ব ২১-এ একটি Zod schema দুই দিকে ব্যবহার করেছেন, আর পর্ব ২৭-এ server-এর দরজায় যাচাই বসিয়েছেন। কিন্তু একটি জায়গা এখনো খোলা। Server যা ফেরত পাঠায়, client সেটিকে কীভাবে চেনে? সাধারণত এভাবে:

type Product = { id: number; name: string; price: number }; // client-এর নিজের নকল

async function getProduct(id: number) {
  const res = await fetch(`/api/products/${id}`);
  return (await res.json()) as Product;                     // শুধু একটি প্রতিশ্রুতি
}

এখানে as Product কিছুই যাচাই করে না। এটি compiler-কে বলে, “আমাকে বিশ্বাস করুন।” Server বদলে গেলে প্রতিশ্রুতিটি মিথ্যা হয়ে যায়, আর compiler চুপ থাকে। এই অবস্থাকে বলে type drift: দুই পাশের ধারণা ধীরে ধীরে আলাদা হয়ে যাওয়া। ফলাফল এরকম হয়:

লক্ষ করুন, ভুলগুলো কোনোটিই বড় নয়। কিন্তু ধরা পড়ে দেরিতে। সবচেয়ে সস্তা জায়গা হলো compile-এর সময়, সবচেয়ে দামি জায়গা হলো ব্যবহারকারীর স্ক্রিন। এই পর্বের লক্ষ্য end-to-end type safety: একটি বদল করলে অন্য প্রান্তের ভাঙা লাইনটি compiler নিজেই দেখিয়ে দেবে।

২ · ফাঁক বন্ধের তিন পথ

রেস্তোরাঁয় ফিরে যাই। মেনুর সমস্যা তিনভাবে মেটানো যায়। শেফ আর ওয়েটার একটি অভিন্ন খাতা দেখে কাজ করতে পারেন। অথবা শেফের মূল তালিকা থেকে ছাপাখানা প্রতিবার নতুন মেনু ছাপতে পারে। অথবা দুজন একই দেয়ালের বোর্ড দেখতে পারেন, যেখানে শেফ লিখলেই ওয়েটার সঙ্গে সঙ্গে দেখেন। সফটওয়্যারের তিন পথও ঠিক এমন।

দ্বিতীয় পথটি একবার চালিয়ে দেখা যাক। চুক্তি লেখা আর openapi-typescript-এর বিস্তার পর্ব ৩৫-এর বিষয়। এখানে শুধু দেখব, নাম বদলালে কখন ধরা পড়ে। Spec-এ Product-এর price আছে, আর client লিখেছে data.price. এবার spec-এ নাম বদলে priceTaka করা হলো।

সত্যিকারের run · openapi-typescript 7.13.0, openapi-fetch 0.17.0, TypeScript 5.9.3 · ~/bazarghar-codegen

$ npx tsc -p .                               # spec বদলানোর পরে, generate করার আগে
$ echo $?
0
$ npx openapi-typescript openapi.yaml -o schema.ts
✨ openapi-typescript 7.13.0
🚀 openapi.yaml → schema.ts [19.3ms]
$ npx tsc -p .
client.ts(9,32): error TS2339: Property 'price' does not exist on type '{ id: number; name: string; priceTaka: number; }'.

দেখুন, প্রথম tsc কিছুই ধরেনি, কারণ পুরোনো schema.ts তখনো রয়ে গেছে। Code generation-এর ঝুঁকি ঠিক এখানে: generate করতে ভুলে গেলে সুরক্ষা নেই। তাই CI-তে একটি ধাপ রাখা হয়, যা আবার generate করে দেখে ফাইলটি বদলাল কি না। GraphQL-এ একই কাজ করে GraphQL Code Generator-এর মতো টুল (এখানে চালানো হয়নি; GraphQL-এর ভিত্তি পর্ব ৩৬-এ)।

৩ · Monorepo — এক ছাদের নিচে web, api আর shared

পথ যেটিই হোক, type ভাগ করতে হলে কোড এক জায়গায় থাকলে কাজ সহজ হয়। Monorepo মানে একটি repository-র ভেতরে কয়েকটি package. npm-এর workspace সুবিধা এদের পরস্পরের সঙ্গে জুড়ে দেয়, npm-এ প্রকাশ না করেই। পর্ব ০৫-এ ধারণাটি এসেছে, এবার সত্যিই বানাই।

bazarghar/
├── package.json          "workspaces": ["packages/*", "apps/*"]
├── tsconfig.base.json    strict, verbatimModuleSyntax
├── packages/
│   └── shared/           @bazarghar/shared  (Zod schema)
└── apps/
    ├── api/              @bazarghar/api     (Express + tRPC)
    └── web/              @bazarghar/web     (Vite + React)

import * as z from "zod";

export const productId = z.object({ id: z.number().int().positive() });

export const createOrderInput = z.object({
  productId: z.number().int().positive(),
  qty: z.number().int().min(1).max(10),
});

export type CreateOrderInput = z.infer<typeof createOrderInput>;

Package-এর package.json-এ "exports": { ".": "./src/index.ts" } লেখা। অর্থাৎ অন্য package সরাসরি TypeScript উৎস ফাইল পড়ে, কারণ tsx আর Vite দুটোই সেটি চালাতে পারে। Package বাইরে প্রকাশ করতে চাইলে আগে build করতে হতো। ইনস্টলের পরে যা হলো:

সত্যিকারের run · npm 11.12.1, Node.js 24.15 · ~/bazarghar · লম্বা অংশ ছাঁটা

$ npm install -w @bazarghar/api @trpc/server @trpc/client express superjson @bazarghar/shared@0.0.0
added 69 packages in 2s

$ npm ls --depth=0 --workspaces
+-- @bazarghar/api@0.0.0 -> ./apps/api
| +-- @bazarghar/shared@0.0.0 deduped -> ./packages/shared
| +-- @trpc/client@11.22.1
| +-- @trpc/server@11.22.1
| +-- express@5.3.0
| `-- superjson@2.2.6
+-- @bazarghar/shared@0.0.0 -> ./packages/shared
| `-- zod@4.6.7
`-- @bazarghar/web@0.0.0 -> ./apps/web
  +-- @bazarghar/api@0.0.0 deduped -> ./apps/api
  +-- @tanstack/react-query@5.105.1
  +-- @trpc/tanstack-react-query@11.22.1
  +-- react@19.3.1
  `-- vite@8.3.5
…

তীরচিহ্ন -> বলছে, এগুলো কপি নয়। node_modules/@bazarghar/shared আসলে packages/shared ফোল্ডারের একটি symlink. তাই shared-এ একটি লাইন বদলালে api আর web সঙ্গে সঙ্গে দেখে, কোনো publish লাগে না। pnpm-এ একই কাজের জন্য থাকে pnpm-workspace.yaml আর "workspace:*"; এই পর্বের run npm দিয়ে হয়েছে।

৪ · tRPC-র গঠন — router থেকে middleware

tRPC-র পুরো নাম TypeScript Remote Procedure Call. RPC মানে অন্য যন্ত্রের একটি function এমনভাবে ডাকা, যেন সেটি নিজের কোডের function. REST-এ আপনি ভাবেন resource আর URL নিয়ে। tRPC-তে ভাবেন function নিয়ে: product.byId, order.create. লেখার সময়ে npm-এর latest হলো 11.22.1; major version 11 এসেছে ২০২৫ সালের মার্চে।

প্রথমে ভিত্তি। এই ফাইল একবার লেখা হয়, পুরো backend এটি ব্যবহার করে।

import { initTRPC, TRPCError } from "@trpc/server";
import type { CreateExpressContextOptions } from "@trpc/server/adapters/express";
import superjson from "superjson";

type User = { id: number; name: string };

// শুধু demo: আসল অ্যাপে এখানে session বা JWT পড়া হয়
const tokens = new Map<string, User>([["example-token", { id: 7, name: "Rima" }]]);

export function createContext({ req }: CreateExpressContextOptions) {
  const token = req.headers.authorization?.replace("Bearer ", "");
  return { user: token ? (tokens.get(token) ?? null) : null };
}
type Context = Awaited<ReturnType<typeof createContext>>;

const t = initTRPC.context<Context>().create({ transformer: superjson });

export const router = t.router;

const timing = t.middleware(async ({ path, type, next }) => {
  const start = performance.now();
  const result = await next();
  const ms = (performance.now() - start).toFixed(1);
  console.log(`${type} ${path} ok=${result.ok} ${ms}ms`);
  return result;
});

export const publicProcedure = t.procedure.use(timing);

export const protectedProcedure = publicProcedure.use(({ ctx, next }) => {
  if (!ctx.user) throw new TRPCError({ code: "UNAUTHORIZED", message: "login required" });
  return next({ ctx: { user: ctx.user } }); // এখান থেকে user আর null নয়
});

এবার আসল API. লক্ষ করুন costPrice (কেনা দাম)। এটি ব্যবসার গোপন তথ্য, তাই toPublic সেটি বাদ দিয়ে উত্তর সাজায়।

import { TRPCError } from "@trpc/server";
import { createOrderInput, productId } from "@bazarghar/shared";
import { publicProcedure, protectedProcedure, router } from "./trpc.ts";

// server-এর জিনিস: browser bundle-এ কখনো যাওয়া চলবে না
export const DB_URL = "postgres://app:example-secret@127.0.0.1/bazarghar";

const products = [
  { id: 1, name: "মিনিকেট চাল ৫ কেজি", price: 450, costPrice: 400, stock: 12 },
  { id: 2, name: "সয়াবিন তেল ১ লিটার", price: 180, costPrice: 160, stock: 3 },
];
type Row = (typeof products)[number];
const toPublic = ({ id, name, price, stock }: Row) => ({ id, name, price, stock });

export const appRouter = router({
  product: router({
    list: publicProcedure.query(() => products.map(toPublic)),
    byId: publicProcedure.input(productId).query(({ input }) => {
      const row = products.find((p) => p.id === input.id);
      if (!row) throw new TRPCError({ code: "NOT_FOUND", message: `product ${input.id} not found` });
      return toPublic(row);
    }),
  }),
  order: router({
    create: protectedProcedure.input(createOrderInput).mutation(({ input, ctx }) => {
      const row = products.find((p) => p.id === input.productId);
      if (!row) throw new TRPCError({ code: "NOT_FOUND", message: "no such product" });
      if (row.stock < input.qty)
        throw new TRPCError({ code: "CONFLICT", message: `only ${row.stock} left` });
      row.stock -= input.qty;
      return { orderId: 501, buyer: ctx.user.name, total: row.price * input.qty, createdAt: new Date() };
    }),
  }),
});

export type AppRouter = typeof appRouter;

শেষ সারিটি খেয়াল করুন। Express-এ req.user আছে কি না, type বলতে পারে না। এখানে protectedProcedure পার হলে ctx.user-এর type User | null থেকে User হয়ে যায়। তাই ctx.user.name লিখতে কোনো ! লাগেনি। এটি পর্ব ২৬-এর পাইপলাইন, শুধু type-সহ। Login-এর আসল ব্যবস্থা আসবে পর্ব ৪৫ আর ৪৬-এ; এখানকার token তালিকা শুধু শেখার জন্য।

৫ · Express আর React-এ জোড়া — সত্যিকারের run

Router কোনো নির্দিষ্ট server-এ বাঁধা নয়। Adapter তাকে Express-এর middleware বানিয়ে দেয়। তাই পুরোনো Express অ্যাপের ভেতরেও /trpc পথে tRPC বসানো যায়, পাশের REST route অক্ষত থাকে।

import express from "express";
import { createExpressMiddleware } from "@trpc/server/adapters/express";
import { appRouter } from "./router.ts";
import { createContext } from "./trpc.ts";

const app = express();
app.use("/trpc", createExpressMiddleware({
  router: appRouter,
  createContext,
  onError({ path, error }) {
    if (error.code === "INTERNAL_SERVER_ERROR") console.error(path, error);
  },
}));
app.listen(4537, "127.0.0.1", () => console.log("api on http://127.0.0.1:4537/trpc"));

এবার client. tRPC-র বর্তমান docs নতুন project-এর জন্য @trpc/tanstack-react-query সুপারিশ করে। এটি আলাদা hook বানায় না, বরং পর্ব ১৯-এর চেনা useQuery আর useMutation-এর জন্য option তৈরি করে।

import { createTRPCContext } from "@trpc/tanstack-react-query";
import type { AppRouter } from "@bazarghar/api/router"; // শুধু type, bundle-এ যাবে না

export const { TRPCProvider, useTRPC } = createTRPCContext<AppRouter>();

const queryClient = new QueryClient();

function App() {
  const [trpcClient] = useState(() =>
    createTRPCClient<AppRouter>({
      links: [httpBatchLink({
        url: "/trpc",
        transformer: superjson,
        headers: () => ({ authorization: "Bearer example-token" }),
      })],
    }),
  );
  return (
    <QueryClientProvider client={queryClient}>
      <TRPCProvider trpcClient={trpcClient} queryClient={queryClient}>
        <Shop />
      </TRPCProvider>
    </QueryClientProvider>
  );
}

export function Shop() {
  const trpc = useTRPC();
  const queryClient = useQueryClient();
  const list = useQuery(trpc.product.list.queryOptions());
  const one = useQuery(trpc.product.byId.queryOptions({ id: 2 }));
  const buy = useMutation(trpc.order.create.mutationOptions({
    onSuccess: () => queryClient.invalidateQueries({ queryKey: trpc.product.list.queryKey() }),
  }));
  // … list.data.map((p) => p.name, p.price) দিয়ে তালিকা,
  // আর বোতামে buy.mutate({ productId: p.id, qty: 1 })
}

Vite-এর build Edge browser-এ Playwright দিয়ে খুলে একটি “কিনুন” বোতাম চাপা হলো, আর সব network অনুরোধ ধরা হলো। পাশাপাশি একটি ছোট Node client দিয়ে ভুলের পথগুলো পরখ করা হলো।

সত্যিকারের run · tRPC 11.22.1, Express 5.3.0, TanStack Query 5.105.1, React 19.3.1, Vite 8.3.5, Zod 4.6.7 · Edge browser · ~/bazarghar

# browser-এর network (URL-decode করা, পড়ার জন্য ভাঙা)
GET /trpc/product.list,product.byId
    ?batch=1&input={"0":{"json":null,"meta":{"values":["undefined"],"v":1}},"1":{"json":{"id":2}}}
200 [{"result":{"data":{"json":[{"id":1,"name":"মিনিকেট চাল ৫ কেজি","price":450,"stock":9},…]}}},
     {"result":{"data":{"json":{"id":2,"name":"সয়াবিন তেল ১ লিটার","price":180,"stock":3}}}}]

# "কিনুন" চাপার পরে
POST /trpc/order.create?batch=1
GET  /trpc/product.list?batch=1&input=…

# পাতায় যা দেখা গেল
মিনিকেট চাল ৫ কেজি: 450 টাকা, স্টকে 8
সয়াবিন তেল ১ লিটার: 180 টাকা, স্টকে 3
অর্ডার 501: মোট 450, বছর 2026

# server-এর log, timing middleware থেকে
query product.list ok=true 0.3ms
query product.byId ok=true 0.4ms
mutation order.create ok=true 0.2ms
query product.list ok=true 0.0ms

তিনটি জিনিস খেয়াল করুন। প্রথমত, দুটি আলাদা useQuery একটিমাত্র HTTP অনুরোধে গেছে। এটি httpBatchLink-এর কাজ: কাছাকাছি সময়ের ডাকগুলো এক অনুরোধে জুড়ে দেওয়া, উত্তর আসে একই ক্রমের array-তে। দ্বিতীয়ত, mutation-এর পরে invalidateQueries তালিকা আবার এনেছে, তাই স্টক কমে পাতায় 8 হয়েছে। তৃতীয়ত, URL-এ input থাকায় অনেক বড় batch URL-এর সীমায় পড়তে পারে; এজন্য httpBatchLink-এ maxURLLength option আছে।

trpc.product.byId.queryOptions({ id: 2 })
// { id: "2" } লিখলে tsc এখানেই থামাত
// input-এর type এসেছে server-এর Zod schema থেকে

trpc.product.byId  →  path: ["product", "byId"]
input: { id: 2 }
// browser-এ কোনো procedure তালিকা নেই

GET /trpc/product.list,product.byId
    ?batch=1
    &input={"0":{…},
      "1":{"json":{"id":2}}}
authorization: Bearer example-token

createContext → { user: { id: 7, name: "Rima" } }
timing middleware শুরু
productId.parse({ id: 2 }) → ঠিক আছে
// { id: -5 } হলে এখানেই BAD_REQUEST 400

{"result":{"data":{"json":{"id":2,
 "name":"সয়াবিন তেল ১ লিটার","price":180,"stock":3}}}}
costPrice নেই, toPublic বাদ দিয়েছে
query product.byId ok=true 0.4ms

one.data?.name  →  সয়াবিন তেল ১ লিটার
one.data-এর type: { id, name, price, stock } | undefined

৬ · Type কীভাবে সীমানা পার হয় — নিজে বানিয়ে দেখুন

আসল tRPC পাতায় চালানো যায় না। কিন্তু তার মূল কৌশল মাত্র কয়েক লাইনের TypeScript. নিচের ব্লকগুলো শেখার জন্য বানানো মডেল, আসল tRPC নয়। প্রথম ব্লকে একটি router-এর মতো object আছে, আর server-এ নাম বদলে গেছে। চালিয়ে দেখুন।

// server-এর দিক: router-এর মতো একটি object (শেখার মডেল)
const router = {
  product: {
    byId: async (input: { id: number }) => ({
      id: input.id,
      name: "oil 1L",
      priceTaka: 180,            // আগে এর নাম ছিল price
    }),
  },
};
type AppRouter = typeof router;  // client পর্যন্ত যায় শুধু type

// client-এর দিক: কোড নয়, শুধু AppRouter জানে
type ById = AppRouter["product"]["byId"];
type Product = Awaited<ReturnType<ById>>;

function label(p: Product): string {
  return `${p.name}: ${p.price} taka`;
}

function ask(input: Parameters<ById>[0]) {
  return input.id;
}
ask({ id: "2" });

router.product.byId({ id: 2 }).then((p) => console.log(label(p)));

এবার client বানাই। সমস্যা হলো, type চলার সময় থাকে না। তাহলে api.product.byId(…) চলবে কীভাবে? উত্তর দুই ভাগে। Type-এর ভাগে একটি mapped type router-এর আকৃতি নকল করে। চলার সময়ের ভাগে একটি JavaScript Proxy যেকোনো property পড়া ধরে ফেলে, আর শেষে ডাক পড়লে path-সহ অনুরোধ পাঠায়।

// ছোট typed RPC client: tRPC-র ধারণার শেখার মডেল, আসল tRPC নয়
const router = {
  product: { byId: async (input: { id: number }) => ({ id: input.id, name: "oil 1L", price: 180 }) },
  order: {
    create: async (input: { productId: number; qty: number }) => ({ orderId: 501, total: 180 * input.qty }),
  },
};
type AppRouter = typeof router;

// function হলে যেমন আছে তেমনই, object হলে আবার ভেতরে
type Client<R> = { [K in keyof R]: R[K] extends (i: any) => any ? R[K] : Client<R[K]> };
type Send = (path: string, input: unknown) => Promise<unknown>;

function createClient<R>(send: Send, path: string[] = []): Client<R> {
  return new Proxy(() => {}, {
    get: (_t, key) => createClient(send, [...path, String(key)]),
    apply: (_t, _self, args) => send(path.join("."), args[0]),
  }) as unknown as Client<R>;
}

// "network": client জানে শুধু path আর JSON
const send: Send = async (path, input) => {
  console.log("send", path, JSON.stringify(input));
  const [group, name] = path.split(".") as ["order", "create"];
  return router[group][name](input as { productId: number; qty: number });
};

const api = createClient<AppRouter>(send);

async function main() {
  const p = await api.product.byId({ id: 2 });   // p-র পুরো type জানা
  const o = await api.order.create({ productId: p.id, qty: 3 });
  console.log(p.name, p.price + 20, o.total.toFixed(2));
}
main();

send product.byId {"id":2}
send order.create {"productId":2,"qty":3}
oil 1L 200 540.00

এবার নকল network বাদ দিই। নিচের ব্লকে Node-এর একটি আসল HTTP server চলে, আর Proxy client fetch দিয়ে তাকে ডাকে। Type নেই বলে ভুল নাম এখানে compile-এর সময় ধরা পড়ে না। তফাতটি দেখুন।

const http = require("node:http");
const procedures = {
  "product.byId": ({ id }) => ({ id, name: "oil 1L", price: 180 }),
  "product.stock": ({ id }) => ({ id, stock: 3 }),
};
const server = http.createServer((req, res) => {
  const url = new URL(req.url, "http://x");
  const fn = procedures[url.pathname.slice(1)];
  res.setHeader("content-type", "application/json");
  if (!fn) { res.statusCode = 404; return res.end('{"error":"NOT_FOUND"}'); }
  console.log("server got", req.method, req.url);
  res.end(JSON.stringify(fn(JSON.parse(url.searchParams.get("input")))));
});

// client: procedure-এর তালিকা কোথাও নেই, Proxy শুধু path জমায়
function client(base, path = []) {
  return new Proxy(() => {}, {
    get: (_t, key) => client(base, [...path, key]),
    apply: async (_t, _self, [input]) => {
      const q = encodeURIComponent(JSON.stringify(input));
      const res = await fetch(`${base}/${path.join(".")}?input=${q}`);
      if (!res.ok) throw new Error(`${res.status} ${path.join(".")}`);
      return res.json();
    },
  });
}

server.listen(0, "127.0.0.1", async () => {
  const api = client(`http://127.0.0.1:${server.address().port}`);
  console.log(await api.product.byId({ id: 2 }));
  console.log(await api.product.stock({ id: 2 }));
  await api.product.price({ id: 2 }).catch((e) => console.log("caught", e.message));
  server.close();
});

server got GET /product.byId?input=%7B%22id%22%3A2%7D
{ id: 2, name: 'oil 1L', price: 180 }
server got GET /product.stock?input=%7B%22id%22%3A2%7D
{ id: 2, stock: 3 }
caught 404 product.price

৭ · নাম বদলালে কী হয় — আর bundle-এ server কোড আছে কি

আসল project-এ ফিরি। ধরুন দাম টাকায় না পয়সায়, এই নিয়ে বিভ্রান্তি কাটাতে price হবে priceTaka. নিচের ধাপগুলো বাজারঘরে সত্যিই চালানো হয়েছে।

const toPublic = ({ id, name, price, stock }: Row) =>
  ({ id, name, priceTaka: price, stock });

$ npx tsc -p apps/api --noEmit
$ echo $?
0

$ npx tsc -p apps/web --noEmit
apps/web/src/Shop.tsx(21,26): error TS2339:
Property 'price' does not exist on type
'{ id: number; name: string; priceTaka: number; stock: number; }'.
$ echo $?
1

$ npx vite build
dist/assets/index-BgFbkS4w.js  293.78 kB │ gzip: 90.77 kB
✓ built in 104ms

পাতায়, Edge browser-এ:
মিনিকেট চাল ৫ কেজি: টাকা, স্টকে 12
দাম নেই, কোনো error-ও নেই

$ npm run build     # typecheck && vite build
> tsc -p apps/api --noEmit && tsc -p apps/web --noEmit
apps/web/src/Shop.tsx(21,26): error TS2339: …
exit 1              # vite build চলেইনি

একই সুরক্ষা উল্টো দিকেও আছে। Client-এ buy.mutate({ productId: p.id, quantity: 1 }) লিখলে আসল run-এ এল: error TS2353: Object literal may only specify known properties, and 'quantity' does not exist in type '{ productId: number; qty: number; }'.

Client কি server কোড পেল? Bundle খুলে দেখি

“Client server-কে import করছে” শুনলে ভয় লাগা স্বাভাবিক। router.ts-এ DB_URL আর costPrice আছে। উত্তর আছে import type-এ। এটি TypeScript-কে বলে, এই import শুধু type-এর জন্য, build-এ পুরো লাইনটি মুছে ফেলুন। কথায় বিশ্বাস না করে আমরা তৈরি JavaScript ফাইলে গোপন শব্দগুলো খুঁজলাম, আর ইচ্ছা করে ভুল import-ও করলাম।

সত্যিকারের run · Vite 8.3.5 · আকার একটি স্থানীয় build-এর, আপনার project-এ ভিন্ন হবে

$ cat dist/assets/*.js | grep -c "example-secret"
0
$ cat dist/assets/*.js | grep -c "costPrice"
0

# ভুল import, আর কোডে DB_URL-এর ব্যবহার:
# import { appRouter, DB_URL } from "@bazarghar/api/router";
$ npx tsc -p apps/web --noEmit ; echo $?
0                                        # tsc-এর কোনো আপত্তি নেই
$ npx vite build
✓ 195 modules transformed.               # আগে ছিল 97
dist/assets/index-DWIhlz4B.js  373.30 kB │ gzip: 114.18 kB
$ cat dist/assets/*.js | grep -c "example-secret"
1
$ cat dist/assets/*.js | grep -c "costPrice"
1

হিসাবটি করি। Zod নিলে বাড়ে ৩৬১.০৮ − ২৯৩.৭৮ = ৬৭.৩০ kB, আর gzip-এ ১১০.১১ − ৯০.৭৭ = ১৯.৩৪ kB, অর্থাৎ প্রায় ২১.৩%. ধরুন ব্যবহারকারীর গতি ১ Mbps (অনুমান)। তাহলে বাড়তি ১৯.৩৪ × ৮ ÷ ১০০০ ≈ ০.১৫ সেকেন্ড শুধু নামাতে। এটি খারাপ নয়, বিনিময়ে client-এ তাৎক্ষণিক যাচাই পাওয়া যায়। কিন্তু সিদ্ধান্তটি সচেতন হওয়া দরকার। Bundle নিয়ে বিস্তারিত পর্ব ৭৯-এ।

আমাদের tsconfig-এ verbatimModuleSyntax চালু। এটি থাকলে import { AppRouter } (type ছাড়া) লিখলে tsc সরাসরি TS1484 error দেয়, আর Vite-এও build ব্যর্থ হয় MISSING_EXPORT বলে। Option বন্ধ করে দেখা গেল, এই একই লাইন build-এ চুপচাপ মুছে গেছে, আর bundle 293.78 kB-ই রয়েছে। তাহলে option কেন? কারণ এটি ইচ্ছাকে স্পষ্ট করে, কোন import চলার সময়ের আর কোনটি নয়, ভাগ্যের ওপর ছাড়ে না।

৮ · Date, superjson আর TRPCError

JSON-এ Date নেই। Server new Date() পাঠালে তারে যায় string, আর ওপারে সেটি string-ই থাকে। Map, Set, BigInt-এরও একই দশা। superjson-এর মতো transformer এই সমস্যার সমাধান করে। ধারণাটি সহজ: ডেটার পাশে একটি চিরকুট যায়, “এই ঘরটি আসলে Date.” নিজে বানিয়ে দেখা যাক।

const order = { orderId: 501, createdAt: new Date("2026-11-01T10:30:00Z") };

// ১. সাধারণ JSON: Date পথে string হয়ে যায়
const plain = JSON.parse(JSON.stringify(order));
console.log("plain:", typeof plain.createdAt, plain.createdAt instanceof Date);
try {
  console.log(plain.createdAt.getUTCFullYear());
} catch (e) {
  console.log("crash:", e.message);
}

// ২. ছোট transformer: ডেটার পাশে চিরকুট (superjson-এর ধারণা)
function serialize(obj) {
  const json = {}, meta = {};
  for (const [k, v] of Object.entries(obj)) {
    if (v instanceof Date) { json[k] = v.toISOString(); meta[k] = "Date"; }
    else json[k] = v;
  }
  return JSON.stringify({ json, meta });
}
function deserialize(text) {
  const { json, meta } = JSON.parse(text);
  for (const [k, kind] of Object.entries(meta)) {
    if (kind === "Date") json[k] = new Date(json[k]);
  }
  return json;
}

const wire = serialize(order);
console.log("wire:", wire);
const back = deserialize(wire);
console.log("back:", back.createdAt instanceof Date, back.createdAt.getUTCFullYear());
console.log("bytes:", JSON.stringify(order).length, "vs", wire.length);

plain: string false
crash: plain.createdAt.getUTCFullYear is not a function
wire: {"json":{"orderId":501,"createdAt":"2026-11-01T10:30:00.000Z"},"meta":{"createdAt":"Date"}}
back: true 2026
bytes: 54 vs 91

সত্যিকারের run · superjson 2.2.6 · order.create-এর উত্তর · curl

{"result":{"data":{"json":{"orderId":501,"buyer":"Rima","total":450,"createdAt":"2026-11-01T17:16:24.704Z"},"meta":{"values":{"createdAt":["Date"]},"v":1}}}}

Transformer দুই প্রান্তে লাগে: server-এ initTRPC…create({ transformer: superjson }), client-এ httpBatchLink({ transformer: superjson }). আর tRPC-র inference এখানে সত্যি কথা বলে। Transformer সরিয়ে দিলে createdAt-এর type আর Date থাকে না, string হয়ে যায়:

সত্যিকারের run · TypeScript 7.0.2 · ~/bazarghar

# শুধু server থেকে superjson সরালে
apps/web/src/Shop.tsx(26,106): error TS2339: Property 'getFullYear' does not exist on type 'string'.
apps/web/src/main.tsx(17,9): error TS2322: Type 'typeof SuperJSON' is not assignable to type 'TypeError<"You must define a transformer on your your `initTRPC`-object first">'.

সাধারণ fetch-এ এই ভুল চলার সময়ের crash. এখানে compile error. আর transformer যদি লাগাতেই না চান, API থেকে ISO string পাঠানো একটি পুরোপুরি বৈধ নকশা।

ভুল জানানো: TRPCError

TRPCError-এর code নিজেই HTTP status-এ মিলে যায়, তাই পর্ব ২৮-এর মতো status হাতে বসাতে হয় না। Node client দিয়ে সব পথ পরখ করা হলো:

সত্যিকারের run · apps/api/src/client-demo.ts, npx tsx দিয়ে · ~/bazarghar

byId 1 -> { id: 1, name: 'মিনিকেট চাল ৫ কেজি', price: 450, stock: 12 }
byId 99 -> ERROR NOT_FOUND 404
guest order -> ERROR UNAUTHORIZED 401
qty 50 -> ERROR BAD_REQUEST 400
qty 5 of oil -> ERROR CONFLICT 409
order {
  orderId: 501,
  buyer: 'Rima',
  total: 900,
  createdAt: 2026-11-01T17:16:24.627Z
} | is Date: true

qty 50 Zod-এ আটকেছে (সীমা ১ থেকে ১০)। qty 5 of oil Zod পেরিয়ে স্টকের নিয়মে আটকেছে (স্টকে ৩)। দুটি আলাদা স্তর: আকৃতির যাচাই আর ব্যবসার নিয়ম। আর শেষ লাইনের is Date: true দেখাচ্ছে transformer কাজ করেছে।

৯ · সীমা আর সিদ্ধান্ত — কখন কোন পথ

tRPC খুব আরামদায়ক, তাই সীমাগুলো সততার সঙ্গে জানা দরকার।

• দুই প্রান্তে TypeScript লাগে। Kotlin, Swift বা Dart client typeof appRouter পড়তে পারে না। মোবাইল অ্যাপ React Native না হলে সে সাধারণ HTTP দিয়ে tRPC-র নিজস্ব wire format নকল করতে পারে বটে, কিন্তু সব type-সুবিধা হারায়।
• Public API-র জন্য নয়। বাইরের partner চান স্থির URL, docs আর চুক্তি। tRPC-র URL আর batch format তার ভেতরের বিষয়। tRPC v10 থেকে v11-এ HTTP-র কিছু আচরণ বদলেছে বলে community-তে জানানো হয়েছে; এমন বদল বাইরের ব্যবহারকারীকে ভাঙবে।
• শক্ত বাঁধন। Coupling এখানে ইচ্ছাকৃত। Backend-এর function-এর নাম বদলালেই frontend ভাঙে। এক দলে এটি উপহার, আলাদা দলে এটি ঝামেলা।
• Versioning নেই। tRPC ধরে নেয় client আর server একসাথে deploy হয়। কিন্তু খোলা browser tab-এ পুরোনো কোড চলতে থাকে। এই version skew compiler দেখে না। আমাদের run-এ পুরোনো build নতুন server-এর সঙ্গে চলেছে, দাম ফাঁকা। নিরাপদ পথ হলো expand-contract: আগে নতুন field যোগ করুন, পুরোনোটি রাখুন, client ছড়িয়ে পড়লে তারপর পুরোনোটি মুছুন। Versioning-এর বিস্তার পর্ব ৩৫-এ।
• বড় router-এ compile সময়। সব কিছু inference হওয়ায় অনেক procedure-এ editor ধীর হতে পারে। আমাদের ছোট project-এ দুটি tsc মিলিয়ে ০.৬ সেকেন্ডের কম লেগেছে (একটি স্থানীয় run), তবে বড় project-এর ইঙ্গিত এটি থেকে পাওয়া যায় না।

ডেলিভারি partner-এর Java সিস্টেম,
মোবাইল অ্যাপ (Kotlin)
→ REST + OpenAPI
ভাষা-নিরপেক্ষ চুক্তি, docs, version

বাজারঘরের admin panel:
React + Express, একই monorepo
→ tRPC
generate ধাপ নেই, নাম বদল সঙ্গে সঙ্গে ধরা

ওয়েব, মোবাইল, TV:
প্রতিটি screen ভিন্ন field চায়
→ GraphQL
client ঠিক করে কী লাগবে; দাম জটিলতা

দুই দল, দুই repo, TypeScript
→ Versioned schema package
অথবা OpenAPI codegen

admin panel ─ tRPC ──┐
                     ├─ service layer
partner API ─ REST ──┘
         (দুটিই একই database)

এই বিষয়ে community-তে মতভেদ আছে। অনেকে বলেন শুরুতে tRPC, দরকার হলে পরে REST. অনেকে বলেন প্রথম দিন থেকে চুক্তি। দুই পক্ষের যুক্তিই ঠিক; পার্থক্য আপনার দলের আকার আর ক্রেতার ধরনে।

পাশের দুই-তিনটি পথ

• Next.js Server Actions: Next.js-এ tRPC-র কিছু কাজ এখন framework নিজেই করে। Server-এর একটি function client থেকে ডাকা যায়, type-সহ। পর্ব ৫৪-এ পুরোটা আসবে।
• Hono RPC: Hono framework-এ route-এর type export করে hc<AppType>() client পাওয়া যায়, URL থাকে REST-এর মতোই। Docs অনুযায়ী দুই প্রান্তে strict লাগে। এখানে চালানো হয়নি।
• ts-rest: REST route-এর জন্য একটি ভাগ করা contract, যার থেকে OpenAPI-ও তৈরি করা যেত। সতর্কতা: লেখার সময়ে ts-rest.com জানায় প্রকল্পটি আর রক্ষণাবেক্ষণ হচ্ছে না। নতুন project-এ নেওয়ার আগে বর্তমান অবস্থা দেখে নিন। এখানে চালানো হয়নি।
• tRPC-তে ফাইল: v11 থেকে FormData আর বাইনারি পাঠানো যায়, তবে docs অনুযায়ী httpBatchLink-এর সঙ্গে splitLink লাগে। বড় upload-এর জন্য পর্ব ৩০-এর পথ এখনো সরল।

১০ · AI-এর যুগে type-safe API

tRPC-র major version কয়েকবার বদলেছে, তাই AI প্রায়ই পুরোনো কোড দেয়। সুখবর হলো, এখানে compiler নিজেই AI-এর বড় পরীক্ষক। কিন্তু compiler যা দেখে না, সেটি আপনাকেই দেখতে হবে।

AI-এর tRPC কোড যাচাইয়ের চেকলিস্ট

• package.json-এ tRPC-র version দেখে সেই version-এর docs মিলিয়েছি
• npm run typecheck চালিয়েছি, আর as any বা @ts-ignore যোগ হয়নি
• প্রতিটি লেখার procedure protectedProcedure-এ, আর মালিকানাও যাচাই হচ্ছে
• প্রতিটি input-এ Zod আছে, সীমাসহ
• curl দিয়ে আসল উত্তর পড়েছি, কোনো গোপন field নেই
• Build-এর পরে bundle-এ secret বা server কোড খুঁজেছি
• নতুন package থাকলে সেটি npm-এ সত্যিই আছে আর দরকারি, তা দেখেছি