TriadJS: Framework API TypeScript "tất cả trong một" từ nguồn dữ liệu duy nhất

TriadJS là một framework API ưu tiên TypeScript (TypeScript-first), được xây dựng dựa trên triết lý rằng đặc tả, triển khai, xác thực và kiểm thử của một API không bao giờ nên tách rời nhau. Với Triad, bạn chỉ cần viết định nghĩa TypeScript một lần bằng ngôn ngữ DSL (Domain Specific Language) khai báo của framework, và mọi thứ khác sẽ được tự động sinh ra.

Trạng thái CI của TriadJS

Một nguồn sự thật duy nhất

Triad giải quyết vấn đề "drift" (sự lệch pha) thường thấy trong phát triển phần mềm, nơi tài liệu OpenAPI, mã kiểm thử và schema cơ sở dữ liệu thường nhanh chóng trở nên lỗi thời so với mã nguồn thực tế. Khi sử dụng Triad, nhà phát triển nhận được một hệ sinh thái hoàn chỉnh được tạo ra từ cùng một nguồn dữ liệu gốc:

• Xác thực Runtime: Kiểm tra dữ liệu tại các điểm đầu vào (parse + reject với lỗi có cấu trúc).
• Kiểu dữ liệu tĩnh: Các kiểu TypeScript được suy ra trực tiếp từ schema (t.infer).
• Tài liệu: Tự động sinh tài liệu OpenAPI 3.1 cho các endpoint HTTP và AsyncAPI 3.0 cho các kênh WebSocket.
• Kiểm thử BDD: Các kịch bản BDD có thể thực thi chạy như bài kiểm thử (triad test).
• Kiểm thử đối kháng tự động: Tự động tạo các bài kiểm thử xung đột dựa trên các ràng buộc schema (scenario.auto()).
• Tệp Gherkin: Sinh ra các tệp .feature cho các bên liên quan không chuyên về kỹ thuật.
• Frontend Hooks: Tạo các hook đã định kiểu cho React Query, Solid Query, Vue Query, Svelte Query.
• Schema Cơ sở dữ liệu: Tạo schema cơ sở dữ liệu thông qua cầu nối Drizzle trung tính với phương ngữ (triad db generate).

Được xây dựng cho Con người và AI

Mục tiêu cốt lõi của Triad là đảm bảo một trợ lý lập trình AI có thể hiểu toàn bộ API chỉ bằng cách đọc một nơi duy nhất. Khi các schema, handlers, phản hồi và kiểm thử đều nằm trong các định nghĩa kiểu (typed definitions) giống nhau, các mô hình ngôn ngữ lớn (LLM) hoặc một kỹ sư mới không phải ghép nối ngữ cảnh từ nhiều tệp rời rạc như Zod, OpenAPI YAML hay README đã lỗi thời.

Triad cũng tích hợp sâu với Claude Code. Bạn có thể cài đặt plugin marketplace của Triad để Claude tự động dựng dự án (scaffolding), thêm endpoint, viết kịch bản kiểm thử và tạo tài liệu chỉ bằng các câu lệnh văn bản đơn giản.

Hương vị sử dụng

Đoạn mã dưới đây minh họa cách Triad hoạt động. Bạn định nghĩa mô hình Pet và endpoint createPet:

import { t, endpoint, scenario, createRouter } from '@triadjs/core';

const Pet = t.model('Pet', {
  id: t.string().format('uuid').identity(),
  name: t.string().minLength(1).example('Buddy'),
  species: t.enum('dog', 'cat', 'bird', 'fish'),
  age: t.int32().min(0).max(100),
});

const CreatePet = Pet.pick('name', 'species', 'age').named('CreatePet');

const createPet = endpoint({
  method: 'POST',
  path: '/pets',
  summary: 'Create a pet',
  body: CreatePet,
  responses: { 201: Pet, 400: ApiError },
  handler: async (ctx) => {
    const pet = await ctx.services.petRepo.create(ctx.body);
    return ctx.respond[201](pet);
  },
  behaviors: [
    scenario('creates a pet with valid input')
      .when('POST /pets', { body: { name: 'Rex', species: 'dog', age: 3 } })
      .then('status is 201')
      .and('response body matches { name: "Rex", species: "dog" }'),
    // Tự động sinh khoảng 20 bài kiểm thử biên từ các ràng buộc schema
    ...scenario.auto(),
  ],
});

Từ tệp duy nhất này, lệnh triad test sẽ chạy cả kịch bản do bạn viết và các bài kiểm thử biên tự động. Lệnh triad docs sẽ xuất ra tệp openapi.yaml. Đặc biệt, ctx.body được định kiểu đầy đủ, giúp tránh lỗi khi lập trình.

Hệ sinh thái và Tại sao chọn Triad?

Triad hỗ trợ đa dạng các công cụ và framework phổ biến hiện nay bao gồm Fastify, Express, Hono, AWS Lambda, Drizzle ORM và các thư viện query như TanStack Query.

Hầu hết các stack API TypeScript hiện nay thường phải ghép nối 4-5 thư viện khác nhau (Zod, zod-to-openapi, Cucumber, v.v.) để đạt được những gì Triad cung cấp trong một gói. Với Triad, một thay đổi trong schema là không thể bị quên cập nhật, vì không có gì để "lan truyền" sang cả — mọi thứ đều là hình chiếu xác định từ nguồn gốc.

Hiện tại, Triad đang ở giai đoạn pre-1.0 và đang được phát triển tích cực với đầy đủ tính năng cốt lõi.