@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 { 
  initializeKsqlDbClient, 
  executePullQuery, 
  executeQuery 
} from '@gftdcojp/gftd-ksqldb-orm';

// Initialize ksqlDB client
initializeKsqlDbClient({
  url: 'http://localhost:8088',
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret'
});

// Execute a pull query
const result = await executePullQuery(
  'SELECT * FROM users_table WHERE id = 1;'
);

// Execute a DDL statement
await executeQuery(
  'CREATE STREAM users_stream (id INT, name VARCHAR) WITH (kafka_topic=\'users\', value_format=\'JSON\');'
);

API Reference

ksqlDB Client

import { 
  initializeKsqlDbClient,
  executeQuery,
  executePullQuery,
  executePushQuery,
  executeDDL
} from '@gftdcojp/gftd-ksqldb-orm';

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';

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

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

SEE LICENSE IN LICENSE

Contributing

Please read our contributing guidelines before submitting pull requests.