@junkawasaki/kawadb-orm

v0.1.0

Published

6 months ago

TypeScript ORM for KawaDB with KSQL support - works in Web and Electron environments

0High
0Medium
0Low

jun784

kawadb orm ksql typescript webassembly wasm database streaming event-sourcing web electron

KawaDB ORM

TypeScript ORM for KawaDB with KSQL support - works in Web and Electron environments

KawaDB ORM は、KawaDB の KSQL 操作を抽象化し、TypeScript でタイプセーフなデータベース操作を提供するORMライブラリです。WebブラウザとElectronの両方の環境で動作します。

✨ 特徴

🔗 完全TypeScript対応 - タイプセーフなAPI
🌐 クロスプラットフォーム - Web、Electron、Node.js対応
📊 KSQL統合 - ストリーミングSQL処理
🎯 デコレータベース - シンプルなエンティティ定義
⚡ 高性能 - WebAssembly バックエンド
🔄 イベントソーシング - 自動的なイベント追跡
💾 複数ストレージ - localStorage、IndexedDB、メモリ対応

📦 インストール

npm install kawadb-orm

🚀 クイックスタート

基本的な使用例

import { KawaORM, Entity, Column, Table } from 'kawadb-orm';

// エンティティを定義
@Table('users')
class User extends Entity {
  @Column({ type: 'string' })
  name: string;

  @Column({ type: 'string' })
  email: string;

  @Column({ type: 'number' })
  age: number;

  constructor(name: string, email: string, age: number) {
    super();
    this.name = name;
    this.email = email;
    this.age = age;
  }
}

// ORM を初期化
const orm = new KawaORM({
  storage: 'localStorage',
  enableKSQL: true,
  debugMode: true
});

async function main() {
  // データベースに接続
  await orm.connect();

  // リポジトリを取得
  const userRepo = orm.getRepository(User);

  // ユーザーを作成
  const user = new User('Alice', '[email protected]', 25);
  await userRepo.save(user);

  // ユーザーを検索
  const users = await userRepo.find({
    where: { age: 25 },
    order: { name: 'ASC' }
  });

  console.log('Found users:', users);
}

main().catch(console.error);

KSQL ストリーミング処理

import { KawaORM, KsqlDataType, KsqlDataFormat } from 'kawadb-orm';

const orm = new KawaORM({ enableKSQL: true });
await orm.connect();

const ksql = orm.getKsqlEngine();

// ストリームを作成
await ksql.createStream({
  name: 'user_events',
  columns: [
    { name: 'user_id', type: KsqlDataType.STRING, nullable: false },
    { name: 'event_type', type: KsqlDataType.STRING, nullable: false },
    { name: 'timestamp', type: KsqlDataType.TIMESTAMP, nullable: false }
  ],
  topic: 'events',
  format: KsqlDataFormat.JSON
});

// 継続的クエリを作成
const queryId = await ksql.createContinuousQuery(
  'user_activity_summary',
  `SELECT user_id, COUNT(*) as event_count
   FROM user_events 
   WINDOW TUMBLING (SIZE 1 MINUTE)
   GROUP BY user_id
   EMIT CHANGES`
);

// ストリーミングデータを追加
await ksql.addStreamingData('events', {
  user_id: 'user123',
  event_type: 'login',
  timestamp: new Date().toISOString()
});

// 結果を取得
const results = await ksql.getStreamingResults(queryId, 10);
console.log('Streaming results:', results);

🏗️ API リファレンス

KawaORM クラス

class KawaORM {
  constructor(config?: DatabaseConfig)
  
  // 接続管理
  async connect(options?: ConnectionOptions): Promise<void>
  async disconnect(): Promise<void>
  isConnected(): boolean
  
  // リポジトリ
  getRepository<T>(entityConstructor: EntityConstructor<T>): Repository<T>
  
  // KSQL
  getKsqlEngine(): KsqlEngine
  
  // ユーティリティ
  async query(sql: string, params?: any[]): Promise<any>
  async transaction<T>(callback: (orm: KawaORM) => Promise<T>): Promise<T>
  getEnvironmentInfo(): any
  async getStats(): Promise<any>
}

Repository クラス

class Repository<T extends Entity> {
  // CRUD操作
  async save(entity: T): Promise<T>
  async create(entity: T): Promise<T>
  async update(entity: T): Promise<T>
  
  // 検索
  async findById(id: EntityId): Promise<T | null>
  async find(options?: FindOptions<T>): Promise<T[]>
  async findOne(options?: FindOptions<T>): Promise<T | null>
  async count(options?: FindOptions<T>): Promise<number>
  async exists(id: EntityId): Promise<boolean>
  
  // 削除
  async delete(id: EntityId): Promise<boolean>
  async deleteMany(options: DeleteOptions<T>): Promise<number>
  async clear(): Promise<void>
}

KsqlEngine クラス

class KsqlEngine {
  // KSQL実行
  async executeKsql(ksql: string): Promise<KsqlResult>
  
  // ストリーム/テーブル管理
  async createStream(stream: KsqlStream): Promise<KsqlResult>
  async createTable(table: KsqlTable): Promise<KsqlResult>
  async dropStream(streamName: string): Promise<KsqlResult>
  async dropTable(tableName: string): Promise<KsqlResult>
  
  // 継続的クエリ
  async createContinuousQuery(name: string, ksql: string): Promise<string>
  async stopContinuousQuery(queryId: string): Promise<boolean>
  async listContinuousQueries(): Promise<ContinuousQuery[]>
  
  // ストリーミングデータ
  async addStreamingData(topic: string, data: any): Promise<void>
  async getStreamingResults(queryId: string, limit?: number): Promise<StreamingResult[]>
}

🔧 設定オプション

interface DatabaseConfig {
  storage?: 'localStorage' | 'indexedDB' | 'memory';
  maxEvents?: number;
  enableSync?: boolean;
  enableKSQL?: boolean;
  debugMode?: boolean;
  syncEndpoint?: string;
  wasmPath?: string;
}

🌐 環境別設定

Web ブラウザ

// WASMファイルのパスを指定
const orm = new KawaORM({
  storage: 'indexedDB',
  wasmPath: '/path/to/kawa-wasm/kawa_wasm.js'
});

Electron

// Electronではデフォルトパスが使用される
const orm = new KawaORM({
  storage: 'localStorage',
  debugMode: process.env.NODE_ENV === 'development'
});

Node.js

// Node.js環境では相対パスを使用
const orm = new KawaORM({
  storage: 'memory',
  wasmPath: '../kawa-wasm/pkg/kawa_wasm.js'
});

📊 デコレータ使用例

import { Entity, Table, Column, DataType } from 'kawadb-orm';

@Table('products')
class Product extends Entity {
  @Column({ 
    type: DataType.STRING, 
    nullable: false,
    unique: true 
  })
  name: string;

  @Column({ 
    type: DataType.NUMBER,
    defaultValue: 0 
  })
  price: number;

  @Column({ 
    type: DataType.JSON,
    nullable: true 
  })
  metadata?: any;

  @Column({ 
    type: DataType.BOOLEAN,
    defaultValue: true 
  })
  active: boolean = true;
}

🔄 リアルタイム分析例

// Eコマースのリアルタイム分析
const ksql = orm.getKsqlEngine();

// 購入イベントストリーム
await ksql.createStream({
  name: 'purchases',
  columns: [
    { name: 'user_id', type: KsqlDataType.STRING, nullable: false },
    { name: 'product_id', type: KsqlDataType.STRING, nullable: false },
    { name: 'amount', type: KsqlDataType.DOUBLE, nullable: false },
    { name: 'timestamp', type: KsqlDataType.TIMESTAMP, nullable: false }
  ],
  topic: 'purchase_events',
  format: KsqlDataFormat.JSON
});

// 売上集計クエリ
await ksql.createContinuousQuery(
  'sales_summary',
  `SELECT 
     user_id,
     COUNT(*) as purchase_count,
     SUM(amount) as total_amount,
     AVG(amount) as avg_amount
   FROM purchases
   WINDOW TUMBLING (SIZE 1 HOUR)
   GROUP BY user_id
   HAVING COUNT(*) > 5
   EMIT CHANGES`
);

// 商品別売上ランキング
await ksql.createContinuousQuery(
  'product_ranking',
  `SELECT 
     product_id,
     COUNT(*) as purchase_count,
     SUM(amount) as revenue
   FROM purchases
   WINDOW TUMBLING (SIZE 1 DAY)
   GROUP BY product_id
   ORDER BY revenue DESC
   LIMIT 10
   EMIT CHANGES`
);

🛠️ 開発

# 依存関係をインストール
npm install

# 開発モード
npm run dev

# ビルド
npm run build

# テスト
npm test

# リント
npm run lint

# フォーマット
npm run format

📖 ドキュメント

🤝 コントリビューション

フォークしてください
フィーチャーブランチを作成してください (git checkout -b feature/amazing-feature)
変更をコミットしてください (git commit -m 'Add amazing feature')
ブランチにプッシュしてください (git push origin feature/amazing-feature)
プルリクエストを作成してください

📄 ライセンス

MIT License - 詳細は LICENSE ファイルを参照してください。

🔗 関連リンク

KawaDB ORM - TypeScript でタイプセーフなストリーミングデータベース操作を提供 🚀