Sonamu 소개 - 🌲 Sonamu

TypeScript는 강력한 타입 시스템을 가지고 있습니다. 하지만 많은 프레임워크들이 이 강점을 온전히 활용하지 못하고 있습니다. Sonamu는 TypeScript의 타입 시스템을 중심에 두고 설계되었습니다.

핵심 철학: 단일 진실 공급원

Entity 하나를 정의하면, 나머지는 TypeScript가 알아서 합니다.

🎬 Entity 생성 → Migration 실행 → 타입/스키마/API 자동 생성 → 프론트엔드 Service 생성까지 전체 플로우

Entity를 한 곳에 정의하면, 시스템 전체가 동기화됩니다. 수동으로 타입을 맞추거나, API 스펙을 문서화하거나, 프론트엔드 클라이언트를 작성할 필요가 없습니다.

백엔드와 프론트엔드의 타입 동기화

일반적으로 백엔드 API를 만들고 프론트엔드에서 사용할 때는 타입 동기화가 어렵습니다. Sonamu는 백엔드 변경이 즉시 프론트엔드에 반영되어 컴파일 타임에 에러를 감지합니다.

수동 작성 시
Sonamu 방식

// 백엔드 API
router.get('/api/users/:id', async (req, res) => {
  const user = await db.users.findById(req.params.id);
  res.json(user);
});

// 프론트엔드 클라이언트 (수동으로 작성)
async function getUser(id: number): Promise<any> {  // ← any!
  const res = await fetch(`/api/users/${id}`);
  return res.json();
}

const user = await getUser(123);
console.log(user.username);  // 런타임 에러 가능성

// 백엔드 Model
@api({ httpMethod: "GET", clients: ["axios", "tanstack-query"], resourceName: "User" })
async findById<T extends UserSubsetKey>(subset: T, id: number): Promise<UserSubsetMapping[T]> {
  return this.getPuri("r").table("users").where("id", id).first();
}

@api({ httpMethod: "POST", clients: ["axios", "tanstack-mutation"] })
async save(spa: UserSaveParams[]): Promise<number[]> {
  // ...
}

// 프론트엔드 Service (자동 생성)
export namespace UserService {
  // GET 요청 함수
  export async function getUser<T extends UserSubsetKey>(
    subset: T,
    id: number,
  ): Promise<UserSubsetMapping[T]> {
    return fetch({
      method: "GET",
      url: `/api/user/findById?${qs.stringify({ subset, id })}`
    });
  }

  // GET을 위한 React Query Hook
  export const useUser = <T extends UserSubsetKey>(
    subset: T,
    id: number,
    options?: { enabled?: boolean },
  ) => useQuery({ queryKey: ["User", "getUser", subset, id], queryFn: () => getUser(subset, id), ...options });

  // POST 요청 함수
  export async function save(spa: UserSaveParams[]): Promise<number[]> {
    return fetch({
      method: "POST",
      url: `/api/user/save`,
      data: { spa }
    });
  }

  // POST를 위한 React Query Hook
  export const useSaveMutation = () =>
    useMutation({ mutationFn: (params: { spa: UserSaveParams[] }) => save(params.spa) });
}

// 컴포넌트에서 사용
const user = await UserService.getUser("A", 123);      // 직접 호출
const { data: user } = UserService.useUser("A", 123);  // Hook으로 호출
console.log(user.username);    // ✅ 타입 체크됨
console.log(user.nonExistent); // ❌ 컴파일 에러

📸 Sonamu 방식에서 존재하지 않는 속성에 접근하면 컴파일 에러 표시

Frontend Integration

백엔드 API를 정의하면, 프론트엔드 Service와 TanStack Query Hook이 자동으로 생성됩니다.

🎬 백엔드 @api 메서드 작성 → 프론트엔드 Service 자동 생성 → useQuery 사용

// 백엔드: @api 데코레이터로 API 정의
@api({ httpMethod: "GET" })
async getProfile(userId: number): Promise<User> {
  return this.getPuri("r").table("users").where("id", userId).first();
}

// 프론트엔드: 자동 생성된 Hook 사용
function UserProfile({ userId }: { userId: number }) {
  const { data: user, isLoading } = UserService.useUser("A", userId);

  if (isLoading) return <div>Loading...</div>;
  return <div>{user.username}</div>; // ✅ 완벽한 타입 안전성
}

Subset으로 최적화

필요한 필드만 조회하여 네트워크 비용을 줄이고 성능을 높입니다. 각 Subset마다 정확한 TypeScript 타입이 자동으로 생성됩니다.

// 목록 화면: 최소 정보만
const users = await UserService.findMany("A", { page: 1 });
// { id, email, username }

// 상세 화면: 전체 정보
const user = await UserService.findById("C", userId);
// { id, email, username, bio, createdAt, updatedAt, ... }

핵심 기능:

✅ 백엔드 변경 시 컴파일 에러로 즉시 감지
✅ Namespace 기반으로 깔끔한 구조
✅ TanStack Query 자동 통합 (캐싱, 재검증, 낙관적 업데이트)
✅ Subset별 정확한 타입 추론

Service 사용법

자동 생성된 Service 활용하기

TanStack Query

React Hook으로 데이터 페칭

Testing

Sonamu는 테스트를 위한 강력한 도구를 내장하고 있습니다.

Fixture 시스템

테스트 데이터를 쉽게 생성하고 재사용할 수 있습니다.

// Fixture 정의
export const UserFixtures = {
  admin: {
    email: "[email protected]",
    username: "admin",
    role: "admin",
  },
  user: {
    email: "[email protected]",
    username: "user",
    role: "user",
  },
};

// 테스트에서 사용
test("관리자는 모든 사용자를 볼 수 있다", async () => {
  const admin = await createUser(UserFixtures.admin);
  // ...
});

Naite: 테스트 데이터 추적 & 시각화

테스트 실행 중 모든 데이터 변화를 추적하고 시각화합니다. 디버깅이 훨씬 쉬워집니다.

📸 Naite Viewer 화면 - 테스트 실행 중 데이터베이스 변화를 시각적으로 보여주는 UI

test("사용자 생성 플로우", async () => {
  Naite.t("초기 상태", { userCount: 0 });

  const user = await UserModel.create({
    email: "[email protected]",
    username: "testuser",
  });

  Naite.t("사용자 생성 후", { userCount: 1, userId: user.id });

  await UserModel.delete(user.id);

  Naite.t("삭제 후", { userCount: 0 });
});

Transaction 자동 롤백

각 테스트는 독립된 Transaction에서 실행되고 자동으로 롤백됩니다. 테스트 간 격리가 보장되며 데이터 정리가 필요 없습니다.

test("사용자 생성", async () => {
  await UserModel.create({ email: "[email protected]", ... });
  // 테스트 종료 후 자동 롤백 → DB는 깨끗한 상태 유지
});

test("다음 테스트는 깨끗한 DB에서 시작", async () => {
  const users = await UserModel.findMany();
  expect(users).toHaveLength(0); // ✅ 이전 테스트 데이터 없음
});

Context 기반 권한 테스트

특정 사용자로 인증된 상태에서 테스트할 수 있습니다.

testAs(
  { id: 1, role: "admin" },
  "관리자는 모든 게시글을 삭제할 수 있다",
  async () => {
    await PostModel.delete(123);
    // Context.user가 admin으로 설정됨
  }
);

testAs(
  { id: 2, role: "user" },
  "일반 사용자는 자신의 게시글만 삭제할 수 있다",
  async () => {
    await expect(PostModel.delete(999)).rejects.toThrow("권한이 없습니다");
  }
);

핵심 기능:

✅ Fixture로 테스트 데이터 재사용
✅ Naite로 데이터 변화 시각화
✅ Transaction 자동 롤백으로 격리된 테스트
✅ testAs로 권한 테스트 간편화

Fixture 시스템

테스트 데이터 관리

Naite 가이드

데이터 추적 & 시각화

AI Ready

Sonamu는 AI 시대에 맞는 기능들을 네이티브로 지원합니다.

Vector Search (pgvector)

AI 임베딩 검색을 Entity 필드로 정의하면 끝입니다. pgvector를 네이티브로 지원합니다.

🎬 Entity에 vector 필드 정의 → 마이그레이션 자동 생성 → 벡터 검색 API 구현

// Entity에 vector 필드 정의
{
  "name": "embedding",
  "type": "vector",
  "dimensions": 1536
}

// 벡터 검색 (raw SQL 사용)
const results = await DocumentModel.getPuri("r").raw(`
  SELECT
    id, title, content,
    1 - (embedding <=> ?) AS similarity
  FROM documents
  WHERE embedding IS NOT NULL
  ORDER BY embedding <=> ?
  LIMIT 10
`, [
  JSON.stringify(queryEmbedding),
  JSON.stringify(queryEmbedding)
]);

AI SDK 통합

Vercel AI SDK와 완벽하게 통합됩니다. 스트리밍 응답도 간단합니다.

@api({ httpMethod: "POST" })
async chat(message: string): Promise<StreamingResponse> {
  const result = await streamText({
    model: openai("gpt-4"),
    messages: [{ role: "user", content: message }],
  });

  return result.toTextStreamResponse();
}

SSE (Server-Sent Events)

실시간 스트리밍을 위한 SSE를 간편하게 사용할 수 있습니다.

import { Sonamu } from "sonamu";
import { z } from "zod";

@api({ httpMethod: "GET" })
async streamEvents() {
  const { createSSE } = Sonamu.getContext();

  const events = z.object({
    type: z.literal("message"),
    data: z.string(),
  });

  return createSSE(events)(async (emit) => {
    for (let i = 0; i < 10; i++) {
      await emit({ type: "message", data: `Event ${i}` });
      await sleep(1000);
    }
  });
}

AI Agent 통합

Sonamu UI의 AI 채팅으로 Entity를 자연어로 생성할 수 있습니다.

🎬 Sonamu UI에서 AI에게 '이커머스 주문 시스템 만들어줘' 입력 → Entity 4개 자동 생성

💬 "이커머스 주문 시스템을 만들어줘. 사용자, 상품, 주문, 주문 아이템 테이블이 필요해."

→ Entity 4개가 관계까지 포함해서 자동 생성됩니다.

핵심 기능:

✅ pgvector 네이티브 지원 (벡터 검색)
✅ AI SDK 완벽 통합 (스트리밍)
✅ SSE로 실시간 이벤트
✅ AI Agent로 Entity 자동 생성

Vector Search

임베딩 검색 구현하기

SSE 스트리밍

실시간 이벤트 전송

Production Ready

Sonamu는 프로덕션 환경을 위한 강력한 기능들을 내장하고 있습니다.

BentoCache: 다층 캐싱

메모리 + Redis 다층 캐싱을 간단하게 사용할 수 있습니다.

import { Sonamu } from "sonamu";

// L1 (메모리) + L2 (Redis) 캐싱
const user = await Sonamu.cache.getOrSet(
  `user:${userId}`,
  async () => {
    return await UserModel.findById("C", userId);
  },
  { ttl: "5m" } // 5분 캐싱
);

Cache-Control: 응답 캐싱

HTTP 응답 캐싱 전략을 데코레이터로 간단히 설정할 수 있습니다.

@api({
  httpMethod: "GET",
  cacheControl: { maxAge: 3600, sMaxAge: 7200 }
})
async getPublicData(): Promise<PublicData[]> {
  return await this.getPuri("r")
    .table("public_data")
    .where("public", true);
}

i18n: 타입 안전한 다국어 지원

Entity의 title, prop.desc, enumLabels가 자동으로 딕셔너리에 추출됩니다. 타입 안전한 SD() 함수로 번역을 관리하고, 존재하지 않는 키는 컴파일 타임에 에러로 잡아줍니다.

import { SD } from "../i18n/sd.generated";

SD("common.save")         // "저장" (ko) / "Save" (en)
SD("error.typo")          // ❌ 컴파일 에러: 키 없음

SD("entity.User")         // "사용자" - Entity title 자동 추출
SD("entity.User.email")   // "이메일" - prop.desc 자동 추출
SD.enumLabels("UserRole")["admin"]  // "관리자"

Workflow: 복잡한 비즈니스 로직 관리

여러 단계로 이루어진 복잡한 비즈니스 로직을 체계적으로 관리할 수 있습니다.

import { workflow } from "sonamu";

export const processOrder = workflow(
  {
    name: "process-order",
    version: "1.0",
  },
  async ({ input, step }) => {
    // Step 1: 검증
    await step
      .define({ name: "validate" }, async () => validateOrder(input))
      .run();

    // Step 2: 결제
    const payment = await step
      .define({ name: "charge" }, async () => chargePayment(input))
      .run();

    // Step 3: 주문 생성
    const order = await step
      .define({ name: "create-order" }, async () =>
        createOrderRecord(input, payment)
      )
      .run();

    // Step 4: 이메일 전송
    await step
      .define({ name: "send-email" }, async () => sendConfirmationEmail(order))
      .run();

    return order;
  }
);

// 실행
await Sonamu.workflows.run(processOrder, orderData);

성능 최적화 내장

N+1 문제 자동 해결, 쿼리 최적화, HMR(Hot Module Replacement)이 기본으로 제공됩니다.

// Relation 쿼리에서 N+1 자동 해결
const posts = await PostModel.findMany("A", {
  relations: ["author", "tags"], // DataLoader 패턴으로 최적화
});

핵심 기능:

✅ BentoCache로 다층 캐싱 (메모리 + Redis)
✅ Cache-Control로 HTTP 응답 캐싱
✅ i18n으로 타입 안전한 다국어 지원
✅ Workflow로 복잡한 비즈니스 로직 관리
✅ N+1 문제 자동 해결

BentoCache

다층 캐싱 전략

i18n

다국어 지원 시스템

간단한 예시

Entity를 정의하고 사용하기까지의 전체 플로우입니다.

참고: 자동 생성되는 파일들

api/src/application/sonamu.generated.ts - 모든 타입, 스키마, Enum

web/src/services/sonamu.generated.ts - 프론트엔드 타입 (동기화됨)

web/src/services/services.generated.ts - 모든 Service 메서드

web/src/services/{entity}/{entity}.types.ts - 커스텀 타입 (수동 작성)

1. Entity 정의

🎬 Sonamu UI에서 User Entity를 정의하는 화면

{
  "id": "User",
  "table": "users",
  "props": [
    { "name": "email", "type": "string", "length": 255 },
    { "name": "username", "type": "string", "length": 100 },
    { "name": "role", "type": "enum", "id": "UserRole" }
  ]
}

2. Migration 실행 및 동기화

Entity 저장 → Migration 실행 → pnpm sync: ✅ TypeScript 타입 (sonamu.generated.ts)
✅ Zod 스키마 (BaseSchema, BaseListParams)
✅ DB 마이그레이션
✅ 프론트엔드 Service (services.generated.ts)
✅ TanStack Query Hook

3. Model에서 비즈니스 로직 작성

@api({ httpMethod: "POST" })
@transactional()
async register(params: {
  email: string;
  username: string;
  password: string;
}): Promise<{ user: User }> {
  const wdb = this.getPuri("w");

  wdb.ubRegister("users", {
    email: params.email,
    username: params.username,
    password: await bcrypt.hash(params.password, 10),
    role: "user",
  });

  const [userId] = await wdb.ubUpsert("users");
  const user = await this.findById("C", userId);

  return { user };
}

4. React에서 즉시 사용

import { UserService } from "@/services/services.generated";

function RegisterForm() {
  const registerMutation = useMutation({
    mutationFn: UserService.register,
  });

  const handleSubmit = async (e: React.FormEvent) => {
    const { user } = await registerMutation.mutateAsync({
      email: formData.get("email") as string,
      username: formData.get("username") as string,
      password: formData.get("password") as string,
    });

    console.log("Registered:", user.username); // ✅ 타입 안전
  };

  return <form onSubmit={handleSubmit}>...</form>;
}

🎬 Entity 정의 → Migration → Model 작성 → React에서 사용까지 전체 플로우

누구를 위한 프레임워크인가

생산성을 중시하는 개발자

반복 작업에 시간을 낭비하지 않고, 비즈니스 로직에 집중하고 싶은 분

타입 안전성을 신뢰하는 팀

런타임 에러보다 컴파일 에러를 선호하고, IDE의 도움을 최대한 활용하는 팀

프론트엔드와 협업하는 백엔드

API 스펙 문서화와 클라이언트 작성의 이중 작업에서 벗어나고 싶은 분

빠른 프로토타이핑이 필요한 스타트업

MVP를 빠르게 만들면서도 기술 부채를 최소화하고 싶은 팀

시작하기

3분이면 충분합니다.

# 프로젝트 생성
pnpm create sonamu my-project

# 개발 서버 시작
cd my-project/api
pnpm dev

# Sonamu UI 열기
open http://localhost:1028/sonamu-ui

Quick Start

5분 만에 첫 API 만들기

Installation

자세한 설치 가이드

Core Concepts

Sonamu 작동 원리 이해하기

Development Workflow

개발 워크플로우 알아보기

커뮤니티

GitHub

이슈 리포트와 기여

Sonamu와 함께라면, TypeScript로 개발하는 것이 즐거워집니다.

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

​핵심 철학: 단일 진실 공급원

​백엔드와 프론트엔드의 타입 동기화

​Frontend Integration

​Subset으로 최적화

Service 사용법

TanStack Query

​Testing

​Fixture 시스템

​Naite: 테스트 데이터 추적 & 시각화

​Transaction 자동 롤백

​Context 기반 권한 테스트

Fixture 시스템

Naite 가이드

​AI Ready

​Vector Search (pgvector)

​AI SDK 통합

​SSE (Server-Sent Events)

​AI Agent 통합

Vector Search

SSE 스트리밍

​Production Ready

​BentoCache: 다층 캐싱

​Cache-Control: 응답 캐싱

​i18n: 타입 안전한 다국어 지원

​Workflow: 복잡한 비즈니스 로직 관리

​성능 최적화 내장

BentoCache

i18n

​간단한 예시

​1. Entity 정의

​2. Migration 실행 및 동기화

​3. Model에서 비즈니스 로직 작성

​4. React에서 즉시 사용

​누구를 위한 프레임워크인가

생산성을 중시하는 개발자

타입 안전성을 신뢰하는 팀

프론트엔드와 협업하는 백엔드

빠른 프로토타이핑이 필요한 스타트업

​시작하기

Quick Start

Installation

Core Concepts

Development Workflow

​커뮤니티

GitHub

핵심 철학: 단일 진실 공급원

백엔드와 프론트엔드의 타입 동기화

Frontend Integration

Subset으로 최적화

Testing

Fixture 시스템

Naite: 테스트 데이터 추적 & 시각화

Transaction 자동 롤백

Context 기반 권한 테스트

AI Ready

Vector Search (pgvector)

AI SDK 통합

SSE (Server-Sent Events)

AI Agent 통합

Production Ready

BentoCache: 다층 캐싱

Cache-Control: 응답 캐싱

i18n: 타입 안전한 다국어 지원

Workflow: 복잡한 비즈니스 로직 관리

성능 최적화 내장

간단한 예시

1. Entity 정의

2. Migration 실행 및 동기화

3. Model에서 비즈니스 로직 작성

4. React에서 즉시 사용

누구를 위한 프레임워크인가

시작하기

커뮤니티