@gftdcojp/ksqldb-orm/docs/README.md

ksqldb-orm - Server-Side TypeScript ORM for ksqlDB with enterprise security extensions

# ドキュメント

@gftdcojp/ksqldb-orm の詳細ドキュメント集です。

## 📚 ドキュメント一覧

### 🔗 [高レベルクエリビルダー](./query-builder.md)
**推奨レベル: 初心者〜中級者**

Supabaseライクな直感的なAPIでデータ操作を行う高レベルクライアント

**特徴:**
- メソッドチェーン形式のクエリ構築
- TypeScript型安全性
- 自動エラーハンドリング
- ksqlDBの知識なしでも使用可能

**こんな方におすすめ:**
- ksqlDBが初めての方
- 簡潔なコードを書きたい方
- Supabase/Prismaなどに慣れ親しんだ方
- フロントエンド開発者

### ⚡ [低レベルksqlDBクライアント](./ksqldb-client.md)
**推奨レベル: 中級者〜上級者**

ksqlDBの全機能に直接アクセスできる強力なAPI

**特徴:**
- 生SQL実行（DDL/DML）
- リアルタイムストリーミング
- 複雑な集約とウィンドウ関数
- 最大限のパフォーマンス最適化

**こんな方におすすめ:**
- ksqlDBの経験がある方
- 複雑なストリーム処理が必要な方
- パフォーマンスを重視する方
- バックエンド開発者・データエンジニア

## 🤔 どちらを選ぶべき？

### 高レベルAPI を選ぶべき場合

✅ **はじめてksqlDBを使う**  
✅ **シンプルなCRUD操作が中心**  
✅ **開発速度を重視する**  
✅ **型安全性が重要**  
✅ **エラーハンドリングを自動化したい**

```typescript
// 5行でデータ取得
const { data } = await dbClient
  .from('users')
  .eq('status', 'active')
  .limit(10)
  .execute();
```

### 低レベルAPI を選ぶべき場合

✅ **ksqlDBの高度な機能が必要**  
✅ **リアルタイムストリーミング処理**  
✅ **複雑な集約・ウィンドウ関数**  
✅ **パフォーマンスの最適化が重要**  
✅ **カスタムSQL文を実行したい**

```typescript
// リアルタイム異常検知
executePushQuery(
  `SELECT user_id, COUNT(*) as transaction_count
   FROM transactions WINDOW TUMBLING (SIZE 5 MINUTES)
   GROUP BY user_id HAVING COUNT(*) > 100`,
  (data) => triggerAlert(data)
);
```

## 📋 使い分けガイド

| 用途 | 高レベルAPI | 低レベルAPI | 備考 |
|------|:----------:|:----------:|------|
| 基本的なCRUD | ✅ | ✅ | 高レベルが簡単 |
| データ検索・フィルタリング | ✅ | ✅ | 高レベルが直感的 |
| ページネーション | ✅ | ✅ | 高レベルで自動化 |
| リアルタイムストリーミング | ❌ | ✅ | 低レベルのみ |
| 複雑なJOIN操作 | ❌ | ✅ | 低レベルのみ |
| ウィンドウ関数 | ❌ | ✅ | 低レベルのみ |
| 集約関数 | ❌ | ✅ | 低レベルのみ |
| スキーマ作成(DDL) | ❌ | ✅ | 低レベルのみ |
| 型安全性 | ✅ | ⚠️ | 高レベルが自動 |
| エラーハンドリング | ✅ | ⚠️ | 高レベルが自動 |

## 🔄 併用パターン

多くの実際のプロジェクトでは、両方のAPIを用途に応じて使い分けます：

```typescript
// 1. 低レベルAPIでスキーマ作成
await executeDDL(`
  CREATE STREAM user_events (...) 
  WITH (kafka_topic='events', value_format='JSON');
`);

// 2. 低レベルAPIでリアルタイム処理
executePushQuery(
  `SELECT * FROM user_events EMIT CHANGES;`,
  (data) => processEvent(data)
);

// 3. 高レベルAPIで通常のデータ操作
const { data } = await dbClient
  .from('users')
  .eq('id', userId)
  .single();
```

## 📖 学習パス

### 初心者向け
1. [高レベルクエリビルダー](./query-builder.md) - 基本操作を学ぶ
2. メインドキュメント - 環境設定と基本概念
3. [低レベルksqlDBクライアント](./ksqldb-client.md) - 高度な機能を学ぶ

### 経験者向け
1. [低レベルksqlDBクライアント](./ksqldb-client.md) - すぐに高度な機能を活用
2. [高レベルクエリビルダー](./query-builder.md) - 簡潔な書き方を学ぶ

## 🆘 サポート

### 一般的な質問
- GitHub Issues でお気軽にご質問ください
- コミュニティで情報交換しましょう

### パフォーマンス最適化
- [低レベルAPI](./ksqldb-client.md) の最適化セクションを参照
- 具体的な課題があれば Issue でご相談ください

### 型安全性
- [高レベルAPI](./query-builder.md) の型安全性セクションを参照
- TypeScript型生成機能の活用を検討してください