Getting Started with Kyrin Framework

Overview

Kyrin Framework เป็น high-performance TypeScript web framework ที่ออกแบบมาสำหรับ Bun runtime โดยเฉพาะ เป้าหมายคือการมอบประสบการณ์การพัฒนาที่ดีที่สุด (Developer Experience) ควบคู่ไปกับประสิทธิภาพระดับสูงสุด

ทำไมต้อง Kyrin?

• ⚡ ความเร็วสูง (High Performance):

- ใช้ RadixTree-based routing ทำให้การค้นหา Route รวดเร็วมาก (Time Complexity เป็น O(k) โดย k คือความยาวของ path) และรองรับ Parametric/Wildcard routing แบบเต็มรูปแบบ

• 🎯 Type-Safe (มั่นใจได้ในทุกบรรทัด):

- มี Type Definition ที่ครบถ้วน ช่วยให้ IDE (เช่น VS Code) แนะนำโค้ด (IntelliSense) ได้อย่างแม่นยำ และลดข้อผิดพลาดตั้งแต่ตอนเขียนโค้ด

• 🔋 Battery Included (ครบจบในตัวเดียว):

- มี built-in modules สำหรับ Authentication (JWT, Session), Database (ORM adapters), Caching (Redis/Memory), WebSocket, GraphQL, และ Input Validation

• 🚀 Developer Experience (DX):

- ลด Boilerplate code ให้เหลือน้อยที่สุด

Prerequisites

ก่อนเริ่มต้นใช้งาน Kyrin Framework คุณควรมีความรู้และเครื่องมือดังต่อไปนี้:

ความรู้พื้นฐาน (Basics)

• TypeSript: เนื่องจาก Kyrin เน้น Type-safety ความรู้เรื่อง Interface, Generics, และ Types จะช่วยให้ใช้งานได้เต็มประสิทธิภาพ
• Modern JavaScript: เข้าใจ ES Modules (import/export), Async/Await, และ Arrow Functions
• HTTP & REST: เข้าใจ Concept ของ Request methods (GET, POST), Headers, และ Status Codes

เครื่องมือที่ต้องติดตั้ง (Software Requirements)

• Bun Runtime (แนะนำเวอร์ชันล่าสุด):

# ติดตั้ง Bun (Linux/macOS/WSL)
   curl -fsSL https://bun.sh/install | bash

   # หรือตรวจสอบเวอร์ชัน (ต้องใช้ v1.0 ขึ้นไป)
   bun --version

• TypeScript Compiler:

bun add -g typescript

• Code Editor:

- ESLint - Prettier - Bun for VS Code (Optional)

Installation

การสร้างโปรเจค Kyrin สามารถทำได้ 2 วิธีหลักๆ คือใช้ CLI (ง่ายและเร็ว) หรือติดตั้งเองทีละส่วน (สำหรับผู้ที่ต้องการปรับแต่งเอง)

วิธีที่ 1: ใช้ Kyrin CLI (แนะนำสำหรับโปรเจคใหม่)

วิธีนี้จะสร้าง Project Structure ที่พร้อมใช้งาน มี config ต่างๆ (tsconfig, eslint) มาให้ครบ

# 1. initialize โปรเจคใหม่
bunx kyrin init my-app
# "my-app" คือชื่อโฟลเดอร์โปรเจคที่จะสร้าง

# 2. เข้าไปในโฟลเดอร์
cd my-app

# 3. ติดตั้ง dependencies ทั้งหมด
bun install

# 4. เริ่มต้น Development Server
bun run dev

วิธีที่ 2: Manual Installation (ติดตั้งเอง)

สำหรับการเพิ่ม Kyrin เข้าไปในโปรเจค Bun ที่มีอยู่แล้ว หรือต้องการ setup เองตั้งแต่ศูนย์

# 1. สร้างโฟลเดอร์และ initialize bun project
mkdir my-app
cd my-app
bun init -y

# 2. ติดตั้ง Kyrin core package
bun add kyrin

# 3. ติดตั้ง Types สำหรับ development
bun add -d @types/bun typescript

หลังจากติดตั้งเสร็จ ต้องสร้างไฟล์ tsconfig.json เพื่อกำหนด Environment ให้รองรับ Bun:

{
  "compilerOptions": {
    "target": "ES2022",        // ใช้ Feature ใหม่ๆ ของ JS ได้
    "module": "ES2022",
    "moduleResolution": "bundler", // Bun รองรับ module resolution แบบ bundler
    "types": ["bun-types"],    // โหลด Type definition ของ Bun
    "strict": true             // เปิด Strict mode เพื่อความปลอดภัย
  }
}

Local Development (Verdaccio)

> Section นี้สำหรับ Advanced User หรือ Contributor ที่ต้องการทดสอบ Kyrin package ที่ build เองในเครื่อง หรือจำลอง NPM Registry ภายในองค์กร

Verdaccio ช่วยให้คุณรัน Local NPM Registry ได้ ทำให้คุณสามารถ npm publish package ของคุณเองเพื่อทดสอบ locally ได้โดยไม่ต้องปล่อยขึ้น NPM จริง

1. Setup Verdaccio

# ติดตั้ง Verdaccio ทั่วทั้งเครื่อง
npm install -g verdaccio

# รัน Server (default port: 4873)
verdaccio

2. Publish Kyrin ไปยัง Local Registry

เมื่อแก้โค้ดใน Kyrin Core เสร็จแล้ว สามารถ publish เพื่อให้โปรเจคอื่นในเครื่องดึงไปใช้ได้

cd /path/to/kyrin-framework

# Login เข้า local registry (ทำครั้งแรกครั้งเดียว)
npm adduser --registry http://localhost:4873

# Build และ Publish
npm publish --registry http://localhost:4873

3. ใช้งานในโปรเจคอื่น

# สร้างโปรเจคใหม่โดยดึง template จาก local registry
bunx --registry http://localhost:4873 kyrin init test-app

# หรือติดตั้ง package ในโปรเจคเดิมจาก local router
npm install kyrin --registry http://localhost:4873

Your First Application

มาลองสร้าง HTTP Server ง่ายๆ เพื่อทำความเข้าใจการทำงานพื้นฐาน

1. Hello World Server

สร้างไฟล์ src/index.ts และเขียนโค้ดดังนี้:

import { Kyrin } from "kyrin";

// สร้าง instance ของ application
const app = new Kyrin();

// กำหนด Route: เมื่อมี GET Request มาที่ "/"
app.get("/", (ctx) => {
  // ส่ง JSON response กลับไป
  return ctx.json({ message: "Hello, Kyrin!" });
});

// เริ่มต้น Server ที่ port 3000
app.listen(3000);

คำอธิบาย:

• new Kyrin(): สร้าง HTTP Server instance
• app.get(path, handler): กำหนดว่าถ้า User เข้า path ไหน จะให้ทำงานฟังก์ชันอะไร
• ctx (Context): Object ที่รวมทั้ง Request (สิ่งที่ user ส่งมา) และ Response (สิ่งที่เราจะส่งกลับ) ไว้ในที่เดียว
• ctx.json(): Utility method สำหรับส่ง JSON response พร้อมเซ็ต Content-Type header ให้อัตโนมัติ

2. การรับส่งข้อมูล (Routes & Body)

การทำ REST API มักต้องมีการรับค่าจาก URL Parameter หรือ Body

// 1. URL Parameters (เช่น /users/123)
app.get("/users/:id", (ctx) => {
  const id = ctx.param("id"); // ดึงค่าจาก :id
  return ctx.json({ userId: id });
});

// 2. Request Body (เช่น POST JSON data)
app.post("/users", async (ctx) => {
  // ใช้ Generic <T> เพื่อระบุ Type ของข้อมูลที่จะได้รับ
  const body = await ctx.body<{ name: string; email: string }>();
  
  // logic การบันทึกข้อมูล...
  
  return ctx.json({ 
    message: "User created", 
    data: body 
  }, 201); // กำหนด Status Code 201 (Created)
});

3. การใช้ Middleware

Middleware คือฟังก์ชันที่คั่นกลาง request/response flow ใช้สำหรับงานที่ทำซ้ำๆ เช่น Logging, Authen, CORS

import { Kyrin, cors, createLogger } from "kyrin";

const app = new Kyrin();
const logger = createLogger();

// Global Middleware: ทำงานกับทุก Request
app.use(requestLogger(logger)); // เก็บ Log

app.use(cors({                  // จัดการ CORS
   origin: "*",                 // อนุญาตทุก domain
   methods: ["GET", "POST"]
}));

// Route ปกติ
app.get("/", (ctx) => ctx.json({ status: "ok" }));

Project Structure

การจัดโครงสร้างโปรเจคที่ดีช่วยให้โค้ดดูแลรักษาง่าย (Maintainable)

แบบ Basic (สำหรับโปรเจคเล็ก)

เหมาะกับ Microservice เล็กๆ หรือ POC

my-app/
├── src/
│   ├── index.ts          # จุดเริ่มต้นแอพ รวม routes ไว้ที่นี่ได้เลย
│   ├── middleware/       # Custom middleware
│   └── utils/            # ฟังก์ชันช่วยเหลือต่างๆ
├── package.json
└── tsconfig.json

แบบ Advanced (Scalable Architecture)

เหมาะกับโปรเจคจริงจัง แยกส่วนรับผิดชอบชัดเจน (Separation of Concerns)

my-app/
├── src/
│   ├── index.ts          # Entry point (Setup App & Middleware)
│   ├── config/           # ค่า Config (Env vars, Database connection)
│   ├── routes/           # ตัวกำหนด URL และ map เข้ากับ Controller
│   │   ├── api/
│   │   │   └── users.ts
│   │   └── index.ts
│   ├── middleware/       # Middleware กลาง (Auth, Validation)
│   ├── services/         # Business Logic (การคำนวณ, ติดต่อ DB)
│   │   └── user-service.ts
│   ├── models/           # Data Models / Interfaces
│   └── utils/            # Helper functions
├── tests/                # Unit & Integration Tests
└── package.json

Development Workflow

คำสั่งมาตรฐาน (Standard Scripts)

ใน package.json ที่ได้จาก CLI จะมี scripts พื้นฐาน:

• bun run dev: รัน Server แบบ Hot Reload (Monitor file changes). เมื่อแก้ไฟล์ระบบจะ restart server ให้ทันที เหมาะสำหรับตอนเขียนโค้ด
• bun run start: รัน Server แบบ Production. เร็วที่สุด ไม่มี file watcher เหมาะสำหรับ deploy ขึ้น server จริง
• bun test: รัน Unit Tests ทั้งหมดในโฟลเดอร์ tests/

การจัดการ Environment Variables (.env)

Bun สามารถอ่านไฟล์ .env ได้โดยตรง ไม่ต้องใช้ library dotenv เพิ่ม

• สร้างไฟล์ .env ที่ root project:

PORT=3000
   DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
   API_KEY=secret123

• เรียกใช้ในโค้ดผ่าน process.env:

const port = process.env.PORT || 3000;
   const dbUrl = process.env.DATABASE_URL;
   
   console.log(`Server starting on port ${port}...`);

Next Steps

หลังจากเข้าใจพื้นฐานแล้ว แนะนำให้ศึกษาหัวข้อเหล่านี้ต่อเพื่อสร้างแอพที่สมบูรณ์:

• Core System: เจาะลึกการทำงานของ Application Lifecycle
• Routing: การจัดการ Route แบบซับซ้อน (Group, Parameters)
• Database: การต่อฐานข้อมูล SQL/NoSQL ผ่าน Adapter
• Authentication: การทำระบบสมาชิกและ Login

> 💡 Tip: ลองดูโค้ดตัวอย่างจริงในโฟลเดอร์ /examples ใน Repository เพื่อเห็นภาพการใช้งานร่วมกันของ Features ต่างๆ

ขอให้สนุกกับการเขียนโค้ดด้วย Kyrin Framework! 🎉