@gftdcojp/gftd-ksqldb-orm

@gftdcojp/gftd-ksqldb-orm

Enterprise-grade ksqlDB ORM with TypeScript support, schema registry integration, and advanced features.

Features

• 🚀 ksqlDB Client - Full-featured ksqlDB REST API client
• 🔄 Type Generation - Automatic TypeScript type generation from ksqlDB schemas
• 🗂️ Schema Registry - Confluent Schema Registry integration
• 🔒 Row Level Security - Advanced RLS policies for data access control
• 🌊 Streaming Support - Push and pull queries with real-time data streaming
• 🛠️ CLI Tools - Command-line interface for schema management
• 📊 HTTP Client - Optimized HTTP client for ksqlDB operations

Installation

pnpm add @gftdcojp/gftd-ksqldb-orm

Environment Support

This package supports both Browser and Server environments with optimized entry points:

Browser Environment (Next.js, React, etc.)

// Optimized for browser - excludes Node.js specific features
import { KsqlDbClientBrowser, executeQuery } from '@gftdcojp/gftd-ksqldb-orm/browser';

Server Environment (Node.js, API Routes, etc.)

// Full feature set including file operations and CLI tools
import { KsqlDbClientBrowser, TypeGenerator, AuditLogManager } from '@gftdcojp/gftd-ksqldb-orm/server';

Universal (Auto-detect)

// Automatically detects environment and provides safe features
import { KsqlDbClientBrowser, executeQuery } from '@gftdcojp/gftd-ksqldb-orm';

Testing

The package includes comprehensive tests for both browser and server environments:

# Run all tests
pnpm test

# Run with coverage
pnpm run test:coverage

# Run in watch mode
pnpm run test:watch

# Run Next.js specific tests
pnpm run test:nextjs-client
pnpm run test:nextjs-server

# Run integration tests
pnpm run test:integration

Test Structure

• Integration Tests: Verify module loading and environment detection
• Next.js Client Tests: Test browser-specific functionality with jsdom environment
• Next.js Server Tests: Test server-specific functionality including file operations
• Environment Detection Tests: Verify proper environment detection logic

Test Coverage

The current test suite achieves 44.47% code coverage, with comprehensive testing of:

• Environment detection utilities
• Module loading across different environments
• Next.js client and server-side compatibility
• Error handling and edge cases
• Core functionality components

Quick Start

import { createDatabaseClient } from '@gftdcojp/gftd-ksqldb-orm/client';

// データベースクライアントを作成
const dbClient = createDatabaseClient({
  ksql: {
    url: 'http://localhost:8088',
    apiKey: 'your-api-key',
    apiSecret: 'your-api-secret'
  }
});

await dbClient.initialize();

// Supabaseライクなクエリ（簡単・直感的）
const { data, error } = await dbClient
  .from('users')
  .eq('status', 'active')
  .limit(10)
  .execute();

if (error) {
  console.error('Query failed:', error);
} else {
  console.log('Users:', data);
}

// 単一レコード取得
const { data: user } = await dbClient
  .from('users')
  .eq('id', 1)
  .single();

// データ挿入
const { data: newUser } = await dbClient
  .from('users')
  .insert({
    name: 'John Doe',
    email: '[e-mail]',
    status: 'active'
  });

API Reference

Database Client

import { createDatabaseClient, DatabaseClient } from '@gftdcojp/gftd-ksqldb-orm/client';

// クライアント作成
const dbClient = createDatabaseClient({
  ksql: { url: 'http://localhost:8088' }
});

// データ取得
const { data } = await dbClient.from('users').execute();

// 条件付き検索（全ての演算子）
const { data } = await dbClient
  .from('users')
  .eq('status', 'active')           // 等価
  .neq('type', 'test')              // 不等価
  .gt('age', 18)                    // より大きい
  .between('score', 80, 100)        // 範囲
  .like('name', '%john%')           // パターンマッチ
  .in('department', ['eng', 'dev']) // 複数値
  .isNotNull('email')               // NOT NULL
  .order('created_at', false)
  .limit(25)
  .execute();

// データ操作
// 単一挿入
await dbClient.from('users').insert({ 
  name: 'John', 
  email: '[e-mail]' 
});

// バッチ挿入
await dbClient.from('users').insert([
  { name: 'Alice', email: '[e-mail]' },
  { name: 'Bob', email: '[e-mail]' },
  { name: 'Charlie', email: '[e-mail]' }
]);

// 複雑な条件での更新・削除
await dbClient.from('users').eq('id', 1).update({ name: 'Jane' });
await dbClient.from('users').lt('last_login', '2024-01-01').delete();

Type Generation

import { 
  generateTypesForTables,
  listAllTables,
  getTableSchema 
} from '@gftdcojp/gftd-ksqldb-orm/type-generator';

Schema Registry

import { 
  initializeSchemaRegistryClient,
  registerSchema,
  getLatestSchema 
} from '@gftdcojp/gftd-ksqldb-orm/schema-registry';

Row Level Security

import { 
  RLSManager,
  PolicyType 
} from '@gftdcojp/gftd-ksqldb-orm/row-level-security';

データベース操作

📖 詳細ドキュメント

📚 完全ドキュメント集 - 詳細なガイドと学習パス 🔗 高レベルクエリビルダー - 完全なAPIリファレンス

基本操作

データ取得

// 全データ取得
const { data } = await dbClient.from('users').execute();

// 様々な条件での検索
const { data } = await dbClient
  .from('users')
  .eq('status', 'active')           // 等価条件
  .neq('type', 'test')              // 不等価条件
  .gt('age', 18)                    // より大きい
  .between('score', 80, 100)        // 範囲条件
  .like('name', '%john%')           // パターンマッチ
  .in('department', ['eng', 'dev']) // 複数値検索
  .isNotNull('email')               // NOT NULL判定
  .order('created_at', false)
  .limit(10)
  .execute();

// 単一レコード取得
const { data: user } = await dbClient
  .from('users')
  .eq('id', 123)
  .single();

// NULL値の検索
const { data: usersWithoutEmail } = await dbClient
  .from('users')
  .isNull('email')
  .execute();

// NOT IN条件
const { data: nonTestUsers } = await dbClient
  .from('users')
  .notIn('status', ['test', 'deleted'])
  .execute();

データ操作

// 単一データ挿入
const { data } = await dbClient
  .from('users')
  .insert({
    name: 'John Doe',
    email: '[e-mail]',
    status: 'active'
  });

// バッチデータ挿入（複数レコード）
const { data } = await dbClient
  .from('users')
  .insert([
    { name: 'Alice', email: '[e-mail]', status: 'active' },
    { name: 'Bob', email: '[e-mail]', status: 'pending' },
    { name: 'Charlie', email: '[e-mail]', status: 'active' }
  ]);

// 複雑な条件でのデータ更新
const { data } = await dbClient
  .from('users')
  .between('created_at', '2024-01-01', '2024-01-31')
  .eq('status', 'pending')
  .update({ 
    status: 'verified',
    updated_at: new Date().toISOString()
  });

// 条件付きデータ削除
const { data } = await dbClient
  .from('users')
  .lt('last_login', '2023-01-01')
  .eq('status', 'inactive')
  .delete();

その他の機能

Row Level Security（RLS）

import { rls } from '@gftdcojp/gftd-ksqldb-orm/row-level-security';

// セキュリティポリシー作成
rls.createPolicy({
  tableName: 'users_table',
  condition: 'user_id = auth.user_id()',
  roles: ['authenticated']
});

TypeScript型生成

import { generateTypesForTables } from '@gftdcojp/gftd-ksqldb-orm/type-generator';

// 全テーブルの型定義を自動生成
const typeDefinitions = await generateTypesForTables();

スキーマレジストリ

import { registerSchema } from '@gftdcojp/gftd-ksqldb-orm/schema-registry';

// Avroスキーマ登録
await registerSchema('users-value', userSchema, 'AVRO');

CLI Usage

# Generate types for all tables
npx gftd-ksqldb-orm generate-all --output ./types

# Generate types for specific table
npx gftd-ksqldb-orm generate-types --table users_table --output ./types

# List all tables and streams
npx gftd-ksqldb-orm list

# Dry run (show what would be generated)
npx gftd-ksqldb-orm generate-all --dry --verbose

# Custom output format
npx gftd-ksqldb-orm generate-types --table orders --format ts --output ./src/types

Configuration

Environment Variables

GFTD_DB_URL=http://localhost:8088
GFTD_DB_API_KEY=your-api-key
GFTD_DB_API_SECRET=your-api-secret
GFTD_SCHEMA_REGISTRY_URL=http://localhost:8081

Client Configuration

import { KsqlDbConfig } from '@gftdcojp/gftd-ksqldb-orm';

const config: KsqlDbConfig = {
  url: 'http://localhost:8088',
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret',
  headers: {
    'Custom-Header': 'value'
  }
};

License

MIT License - see the LICENSE file for details.

Contributing

Please read our contributing guidelines before submitting pull requests.