@gravito/stream 1.0.0-alpha.2 → 1.0.0-alpha.6

package/README.md

@@ -1,26 +1,26 @@
 # @gravito/stream
 
-輕量、高效的隊列系統，借鑑 Laravel 架構但保持 Gravito 的核心價值（高效能、低耗、輕量、AI 友善）。支援多種儲存驅動、內嵌與獨立 Consumer 模式，以及多種 Job 序列化方式。
+Lightweight, high-performance queueing for Gravito. Supports multiple storage drivers, embedded and standalone workers, and flexible job serialization.
 
-> **狀態**：v0.1.0 - 核心功能已完成，支援 Memory、Database、Redis、Kafka、SQS 驅動
+**Status**: v0.1.0 - core features complete with Memory, Database, Redis, Kafka, and SQS drivers.
 
-## 特性
+## Features
 
-- **零運行時開銷**：純型別包裝，直接委派給驅動
-- **多驅動支援**：Memory、Database、Redis、Kafka、SQS 等
-- **完全模組化**：按需安裝驅動，核心包極小（< 50KB）
-- **內嵌與獨立模式**：開發時內嵌運行，生產環境可獨立部署
-- **AI 友善**：完整的型別推導、清晰的 JSDoc、直觀的 API
+- **Zero runtime overhead**: Thin wrappers that delegate to drivers
+- **Multi-driver support**: Memory, Database, Redis, Kafka, SQS
+- **Modular**: Install only the driver you need (core < 50KB)
+- **Embedded or standalone workers**: Run in-process during development or standalone in production
+- **AI-friendly**: Strong typing, clear JSDoc, and predictable APIs
 
-## 安裝
+## Installation
 
 ```bash
 bun add @gravito/stream
 ```
 
-## 快速開始
+## Quick Start
 
-### 1. 建立 Job
+### 1. Define a job
 
 ```typescript
 import { Job } from '@gravito/stream'
@@ -31,27 +31,23 @@ export class SendWelcomeEmail extends Job {
   }
 
   async handle(): Promise<void> {
-    // 處理邏輯
     const user = await User.find(this.userId)
     await mail.send(new WelcomeEmail(user))
   }
 }
 ```
 
-### 2. 推送 Job
+### 2. Enqueue a job
 
 ```typescript
-// 在 Controller 中
 const queue = c.get('queue')
 
 await queue.push(new SendWelcomeEmail(user.id))
   .onQueue('emails')
-  .delay(60) // 延遲 60 秒
+  .delay(60)
 ```
 
-### 3. 配置 OrbitStream
-
-#### 使用 Memory Driver（開發用）
+### 3. Configure OrbitStream (Memory driver)
 
 ```typescript
 import { OrbitStream } from '@gravito/stream'
@@ -72,7 +68,7 @@ const core = await PlanetCore.boot({
 })
 ```
 
-#### 使用 Database Driver
+## Database Driver Example
 
 ```typescript
 import { OrbitStream } from '@gravito/stream'
@@ -84,93 +80,9 @@ const core = await PlanetCore.boot({
     OrbitStream.configure({
       default: 'database',
       connections: {
-        database: { 
+        database: {
           driver: 'database',
-          table: 'jobs' // 可選，預設為 'jobs'
-          // dbService 會自動從 Context 取得（如果 OrbitDB 已安裝）
-        }
-      }
-    })
-  ]
-})
-```
-
-#### 使用 Redis Driver
-
-```typescript
-import { OrbitStream } from '@gravito/stream'
-import Redis from 'ioredis'
-
-const redis = new Redis('redis://localhost:6379')
-
-const core = await PlanetCore.boot({
-  orbits: [
-    OrbitStream.configure({
-      default: 'redis',
-      connections: {
-        redis: { 
-          driver: 'redis',
-          client: redis,
-          prefix: 'queue:' // 可選
-        }
-      }
-    })
-  ]
-})
-```
-
-#### 使用 Kafka Driver
-
-```typescript
-import { OrbitStream } from '@gravito/stream'
-import { Kafka } from 'kafkajs'
-
-const kafka = new Kafka({
-  brokers: ['localhost:9092'],
-  clientId: 'gravito-app'
-})
-
-const core = await PlanetCore.boot({
-  orbits: [
-    OrbitStream.configure({
-      default: 'kafka',
-      connections: {
-        kafka: { 
-          driver: 'kafka',
-          client: kafka,
-          consumerGroupId: 'gravito-workers'
-        }
-      }
-    })
-  ]
-})
-```
-
-#### 使用 SQS Driver
-
-```typescript
-import { OrbitStream } from '@gravito/stream'
-import { SQSClient } from '@aws-sdk/client-sqs'
-
-const sqs = new SQSClient({
-  region: 'us-east-1',
-  credentials: {
-    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-  }
-})
-
-const core = await PlanetCore.boot({
-  orbits: [
-    OrbitStream.configure({
-      default: 'sqs',
-      connections: {
-        sqs: { 
-          driver: 'sqs',
-          client: sqs,
-          queueUrlPrefix: 'https://sqs.us-east-1.amazonaws.com/123456789012', // 可選
-          visibilityTimeout: 30, // 可選
-          waitTimeSeconds: 20 // 可選，長輪詢
+          table: 'jobs'
         }
       }
     })
@@ -178,9 +90,7 @@ const core = await PlanetCore.boot({
 })
 ```
 
-## 資料庫 Schema
-
-如果使用 Database Driver，需要建立以下資料表：
+## Database Schema
 
 ```sql
 CREATE TABLE jobs (
@@ -197,29 +107,16 @@ CREATE INDEX idx_jobs_queue_available ON jobs(queue, available_at);
 CREATE INDEX idx_jobs_reserved ON jobs(reserved_at);
 ```
 
-## 獨立 Consumer（微服務模式）
+## Standalone Worker
 
 ```bash
-# 使用 Database
 bun run packages/orbit-queue/cli/queue-worker.ts \
   --connection=database \
   --queues=default,emails \
   --workers=4
-
-# 使用 Kafka
-bun run packages/orbit-queue/cli/queue-worker.ts \
-  --connection=kafka \
-  --queues=default,emails \
-  --consumer-group=gravito-workers
-
-# 使用 SQS
-bun run packages/orbit-queue/cli/queue-worker.ts \
-  --connection=sqs \
-  --queues=default,emails \
-  --region=us-east-1
 ```
 
-## API 參考
+## API Reference
 
 ### Job
 
@@ -227,7 +124,7 @@ bun run packages/orbit-queue/cli/queue-worker.ts \
 abstract class Job implements Queueable {
   abstract handle(): Promise<void>
   async failed(error: Error): Promise<void>
-  
+
   onQueue(queue: string): this
   onConnection(connection: string): this
   delay(seconds: number): this
@@ -247,73 +144,14 @@ class QueueManager {
 }
 ```
 
-## 設計原則
-
-- **高效能**：零運行時開銷，直接委派給驅動，支援批量操作
-- **低耗**：最小化依賴，重用現有連接（DatabaseDriver 重用 orbit-db）
-- **輕量**：核心包極小（< 50KB），驅動完全模組化，按需載入
-- **AI 友善**：完整的型別推導，清晰的 JSDoc，直觀的 API
-
-## 已實作的驅動
-
-### 基礎驅動
-
-- ✅ **MemoryDriver** - 記憶體驅動（開發用，零配置）
-- ✅ **DatabaseDriver** - 資料庫驅動（PostgreSQL、MySQL、SQLite）
-- ✅ **RedisDriver** - Redis 驅動（支援延遲執行）
-
-### 企業級 Broker 驅動
-
-- ✅ **KafkaDriver** - Apache Kafka 驅動（支援 Topic、Consumer Groups）
-- ✅ **SQSDriver** - AWS SQS 驅動（支援標準/FIFO 隊列、長輪詢）
-
-## 未來規劃
-
-以下 broker 驅動計劃在後續版本中實作：
-
-### 計劃中的驅動
-
-- 🔜 **RabbitMQDriver** - RabbitMQ 驅動
-  - 支援 Exchange 和 Queue 管理
-  - 支援多種 Exchange 類型（direct、topic、fanout、headers）
-  - 支援持久化隊列
-  - 支援確認機制
-
-- 🔜 **NATSDriver** - NATS 驅動
-  - 支援 JetStream（持久化消息）
-  - 支援訂閱模式
-  - 支援請求/回應模式
-
-- 🔜 **GooglePubSubDriver** - Google Cloud Pub/Sub 驅動
-  - 支援 Topic 和 Subscription 管理
-  - 支援批量操作
-  - 支援死信主題（Dead Letter Topic）
-
-- 🔜 **AzureServiceBusDriver** - Azure Service Bus 驅動
-  - 支援 Queue 和 Topic 管理
-  - 支援會話（Sessions）
-  - 支援死信隊列
-
-- 🔜 **BeanstalkdDriver** - Beanstalkd 驅動
-  - 輕量級消息隊列
-  - 支援優先級和延遲
-  - 支援 TTR（Time To Run）
-
-### 貢獻指南
-
-如果您想為 Gravito Queue 添加新的 broker 驅動，請：
-
-1. 實作 `QueueDriver` 介面
-2. 確保符合核心原則（高效能、低耗、輕量、AI 友善）
-3. 添加完整的 JSDoc 註解
-4. 添加單元測試
-5. 更新 README 文件
-
-## 相關文件
+## Implemented Drivers
 
-- [ROADMAP.md](./ROADMAP.md) - 詳細的路線圖和計劃
-- [MIGRATION.md](./MIGRATION.md) - 資料庫遷移腳本
+- **MemoryDriver** - in-memory (development)
+- **DatabaseDriver** - PostgreSQL/MySQL/SQLite
+- **RedisDriver** - delayed jobs supported
+- **KafkaDriver** - topics and consumer groups
+- **SQSDriver** - standard/FIFO queues and long polling
 
-## 授權
+## License
 
 MIT

package/README.zh-TW.md

@@ -0,0 +1,34 @@
+# @gravito/stream
+
+> Gravito 的佇列模組，支援多種驅動與獨立 Worker。
+
+## 安裝
+
+```bash
+bun add @gravito/stream
+```
+
+## 快速開始
+
+```typescript
+import { Job } from '@gravito/stream'
+
+export class SendWelcomeEmail extends Job {
+  constructor(private userId: string) {
+    super()
+  }
+
+  async handle(): Promise<void> {
+    const user = await User.find(this.userId)
+    await mail.send(new WelcomeEmail(user))
+  }
+}
+```
+
+```typescript
+const queue = c.get('queue')
+
+await queue.push(new SendWelcomeEmail(user.id))
+  .onQueue('emails')
+  .delay(60)
+```

package/dist/index.cjs

@@ -32069,6 +32069,7 @@ class OrbitStream {
       }
       c3.set("queue", this.queueManager);
       await next();
+      return;
     });
     core.logger.info("[OrbitStream] Installed");
     if (this.options.autoStartWorker && true && this.options.workerOptions) {
@@ -32098,4 +32099,4 @@ class OrbitStream {
 }
 })
 
-//# debugId=0D545FB97BC32D9464756E2164756E21
+//# debugId=4594FD32F9CC842B64756E2164756E21