@gravito/radiance 1.0.3 → 1.0.5

package/README.md

@@ -4,14 +4,29 @@ Lightweight, high-performance broadcasting for Gravito with multiple drivers (Pu
 
 **Status**: v0.1.0 - core features complete with multiple broadcast drivers.
 
-## Features
+## ✨ Features
 
-- **Zero runtime overhead**: Pure type wrappers that delegate to drivers
-- **Multi-driver support**: Pusher, Ably, Redis, WebSocket
-- **Modular**: Install only the driver you need
-- **Events integration**: Events can implement `ShouldBroadcast`
-- **Channel authorization**: Private and presence channels supported
-- **AI-friendly**: Strong typing, clear JSDoc, and predictable APIs
+- 🪐 **Galaxy-Ready Broadcasting**: Native integration with PlanetCore events for automatic real-time delivery.
+- 🔌 **Multi-Driver Support**: Seamlessly switch between **Pusher**, **Ably**, **Redis**, and native **WebSockets**.
+- 📡 **Cross-Satellite Sync**: Synchronize state across multiple isolated Satellite instances.
+- 🛡️ **Channel Authorization**: Built-in support for Private and Presence channels with granular auth logic.
+- 🚀 **Zero Runtime Overhead**: Pure type-safe wrappers designed for maximum performance on Bun.
+
+## 🌌 Role in Galaxy Architecture
+
+In the **Gravito Galaxy Architecture**, Radiance acts as the **Event Horizon Layer (State Synchronization)**.
+
+- **Real-time Interface**: Connects the internal events of the Galaxy to external observers (Clients) via persistent connections.
+- **Satellite Interconnect**: Allows Satellites to broadcast state changes that other Satellites' frontend components can react to instantly.
+- **Presence Core**: Manages the "Who is Online" state across the entire ecosystem, enabling collaborative features.
+
+```mermaid
+graph LR
+    S[Satellite] -->|Dispatch| E[Event]
+    E -->|implement ShouldBroadcast| Radiance{Radiance Orbit}
+    Radiance --> Driver[Driver: WS/Pusher]
+    Driver --> Client([Connected Clients])
+```
 
 ## Installation
 
@@ -216,6 +231,14 @@ OrbitRadiance.configure({
 })
 ```
 
+## 📚 Documentation
+
+Detailed guides and references for the Galaxy Architecture:
+
+- [🏗️ **Architecture Overview**](./README.md) — Multi-driver broadcasting.
+- [📡 **Real-time Sync**](./doc/REAL_TIME_SYNC.md) — **NEW**: Syncing state across Satellites and Clients.
+- [🛡️ **Channel Auth**](#channel-authorization) — Securing private and presence channels.
+
 ## API Reference
 
 ### BroadcastManager

package/README.zh-TW.md

@@ -1,14 +1,27 @@
 # @gravito/radiance
 
-> Gravito 的廣播模組，支援 Pusher、Ably、Redis、WebSocket 等驅動。
+輕量級、高效能的 Gravito 廣播系統，支援多種驅動（Pusher、Ably、Redis、WebSocket）。
 
-## 安裝
+**狀態**: v0.1.0 - 核心功能完整，支援多種廣播驅動。
+
+## ✨ 功能特色
+
+- **零運行時開銷**：純類型封裝，直接委派給驅動程式
+- **多驅動支援**：Pusher、Ably、Redis、WebSocket
+- **模組化設計**：僅需安裝您需要的驅動程式
+- **事件整合**：事件可實現 `ShouldBroadcast` 介面自動廣播
+- **通道授權**：完整支援私有（Private）與存在（Presence）通道
+- **AI 友善**：強型別、清晰的 JSDoc 與可預測的 API
+
+## 📦 安裝
 
 ```bash
 bun add @gravito/radiance
 ```
 
-## 快速開始
+## 🚀 快速開始
+
+### 1. 配置 OrbitRadiance
 
 ```typescript
 import { PlanetCore } from '@gravito/core'
@@ -24,7 +37,229 @@ const core = await PlanetCore.boot({
         secret: 'your-secret',
         cluster: 'mt1',
       },
+      // 錯誤處理選項 (v0.1.1+)
+      throwOnError: true,
+      
+      // 通道授權回調
+      authorizeChannel: async (channel, socketId, userId) => {
+        // 在此實作您的授權邏輯
+        return true
+      },
     }),
   ],
 })
 ```
+
+### 2. 建立可廣播事件
+
+```typescript
+import { Event, ShouldBroadcast } from '@gravito/core'
+import { PrivateChannel } from '@gravito/radiance'
+
+class OrderShipped extends Event implements ShouldBroadcast {
+  constructor(public order: Order) {
+    super()
+  }
+
+  // 定義廣播通道
+  broadcastOn(): PrivateChannel {
+    return new PrivateChannel(`user.${this.order.userId}`)
+  }
+
+  // 定義廣播資料 (可選)
+  broadcastWith(): Record<string, unknown> {
+    return {
+      order_id: this.order.id,
+      status: 'shipped',
+      tracking_number: this.order.trackingNumber,
+    }
+  }
+
+  // 定義事件名稱 (可選)
+  broadcastAs(): string {
+    return 'OrderShipped'
+  }
+}
+```
+
+### 3. 發送事件 (自動廣播)
+
+```typescript
+await core.events.dispatch(new OrderShipped(order))
+```
+
+### 4. 手動廣播
+
+```typescript
+const broadcast = c.get('broadcast') as BroadcastManager
+
+await broadcast.broadcast(
+  event,
+  { name: 'user.123', type: 'private' },
+  { message: 'Hello' },
+  'CustomEvent'
+)
+```
+
+## 🔌 驅動程式配置
+
+### Pusher
+
+```typescript
+OrbitRadiance.configure({
+  driver: 'pusher',
+  config: {
+    appId: 'your-app-id',
+    key: 'your-key',
+    secret: 'your-secret',
+    cluster: 'mt1',
+    useTLS: true,
+  },
+})
+```
+
+### Ably
+
+```typescript
+OrbitRadiance.configure({
+  driver: 'ably',
+  config: {
+    apiKey: 'your-api-key',
+  },
+})
+```
+
+### Redis
+
+適用於內部微服務通訊。
+
+```typescript
+import { RedisDriver } from '@gravito/radiance'
+
+// 若 Core Container 已有 'redis' 實例，會自動注入
+OrbitRadiance.configure({
+  driver: 'redis',
+  config: {
+    keyPrefix: 'gravito:broadcast:',
+  },
+})
+```
+
+### WebSocket
+
+適用於單節點開發或自定義 WebSocket 伺服器。
+
+```typescript
+OrbitRadiance.configure({
+  driver: 'websocket',
+  config: {
+    // 提供獲取所有連線的方法
+    getConnections: () => {
+      return Array.from(websocketConnections.values())
+    },
+    // 可選：自訂 Logger
+    logger: core.logger,
+  },
+})
+```
+
+## 📡 通道類型
+
+### 公開通道 (Public)
+
+任何人都可以訂閱。
+
+```typescript
+import { PublicChannel } from '@gravito/radiance'
+
+class PublicEvent extends Event implements ShouldBroadcast {
+  broadcastOn(): PublicChannel {
+    return new PublicChannel('public-channel')
+  }
+}
+```
+
+### 私有通道 (Private)
+
+需要授權才能訂閱。名稱以 `private-` 開頭。
+
+```typescript
+import { PrivateChannel } from '@gravito/radiance'
+
+class PrivateEvent extends Event implements ShouldBroadcast {
+  broadcastOn(): PrivateChannel {
+    return new PrivateChannel(`user.${this.userId}`)
+  }
+}
+```
+
+### 存在通道 (Presence)
+
+需要授權，並包含使用者資訊。名稱以 `presence-` 開頭。
+
+```typescript
+import { PresenceChannel } from '@gravito/radiance'
+
+class PresenceEvent extends Event implements ShouldBroadcast {
+  broadcastOn(): PresenceChannel {
+    return new PresenceChannel('presence-room')
+  }
+}
+```
+
+## 🔐 通道授權
+
+私有與存在通道需要授權回調。
+
+```typescript
+OrbitRadiance.configure({
+  driver: 'pusher',
+  config: { /* ... */ },
+  authorizeChannel: async (channel, socketId, userId) => {
+    if (channel.startsWith('private-user.')) {
+      const channelUserId = channel.replace('private-user.', '')
+      // 驗證當前使用者 ID 是否匹配
+      return userId?.toString() === channelUserId
+    }
+    return false
+  },
+})
+```
+
+## 📚 API 參考
+
+### BroadcastManager
+
+#### 方法
+
+- `broadcast(event, channel, data, eventName): Promise<void>` - 廣播事件
+- `authorizeChannel(channel, socketId, userId): Promise<{ auth, channel_data? } | null>` - 授權通道存取
+- `setDriver(driver: BroadcastDriver): void` - 設定廣播驅動
+- `setAuthCallback(callback): void` - 設定授權回調
+- `setThrowOnError(throwOnError: boolean): void` - 設定是否在錯誤時拋出異常
+
+### ShouldBroadcast 介面
+
+實作此介面的事件會被自動廣播：
+
+- `broadcastOn(): string | Channel` - 廣播通道（必須）
+- `broadcastWith?(): Record<string, unknown>` - 廣播資料（可選）
+- `broadcastAs?(): string` - 事件名稱（可選）
+
+## ❓ 疑難排解
+
+### 廣播失敗但不拋出錯誤？
+
+檢查 `throwOnError` 設定。預設為 `true`，若設為 `false` 則只會記錄錯誤日誌。
+
+### WebSocket 驅動沒有送出訊息？
+
+確認 `getConnections()` 回傳了正確的連線陣列，且連線狀態為 `OPEN`。WebSocket 驅動會自動忽略非開啟狀態的連線。
+
+### Redis 驅動報錯 "Redis client not set"？
+
+Redis 驅動需要一個 Redis 客戶端實例。請確保在 `OrbitRadiance.configure` 之前或通過依賴注入提供了 `redis` 實例。
+
+---
+
+MIT © Carl Lee

package/dist/core/src/Application.d.ts

@@ -0,0 +1,256 @@
+/**
+ * @fileoverview Application - Enterprise Application Container
+ *
+ * A high-level application class that orchestrates the entire framework.
+ * Provides a centralized entry point for enterprise applications with
+ * auto-discovery of providers, config loading, and lifecycle management.
+ *
+ * Phase 4 優化：Provider 預掃描 + 平行載入
+ * - Phase 1：預掃描所有 Provider 文件（語法驗證）
+ * - Phase 2：篩選有效 Provider（跳過無效的）
+ * - Phase 3：平行 import 所有有效 Provider
+ * - Phase 4：註冊到容器
+ *
+ * @module @gravito/core
+ * @since 2.0.0
+ */
+import { ConfigManager } from './ConfigManager';
+import { Container } from './Container';
+import type { EventManager } from './EventManager';
+import type { Logger } from './Logger';
+import { PlanetCore } from './PlanetCore';
+import type { ServiceProvider } from './ServiceProvider';
+/**
+ * Application Config options for the Application class.
+ * @public
+ */
+export interface ApplicationConfig {
+    /**
+     * Base path of the application
+     */
+    basePath: string;
+    /**
+     * Path to the config directory (relative to basePath)
+     * @default 'config'
+     */
+    configPath?: string;
+    /**
+     * Path to the providers directory (relative to basePath)
+     * @default 'src/Providers'
+     */
+    providersPath?: string;
+    /**
+     * Environment (development, production, testing)
+     */
+    env?: 'development' | 'production' | 'testing';
+    /**
+     * Logger instance
+     */
+    logger?: Logger;
+    /**
+     * Initial configuration values
+     */
+    config?: Record<string, unknown>;
+    /**
+     * Service providers to register
+     */
+    providers?: ServiceProvider[];
+    /**
+     * Whether to auto-discover providers from providersPath
+     * @default true
+     */
+    autoDiscoverProviders?: boolean;
+}
+/**
+ * Application - Enterprise-grade application container.
+ *
+ * Provides a higher-level abstraction over PlanetCore for building
+ * enterprise applications with convention-over-configuration patterns.
+ *
+ * @example
+ * ```typescript
+ * // Create application
+ * const app = new Application({
+ *   basePath: import.meta.dir,
+ *   env: process.env.NODE_ENV as 'development' | 'production',
+ * });
+ *
+ * // Boot the application
+ * await app.boot();
+ *
+ * // Access core
+ * export default app.core.liftoff();
+ * ```
+ */
+export declare class Application {
+    /**
+     * The underlying PlanetCore instance.
+     */
+    readonly core: PlanetCore;
+    /**
+     * The IoC container.
+     */
+    readonly container: Container;
+    /**
+     * The configuration manager.
+     */
+    readonly config: ConfigManager;
+    /**
+     * The event manager.
+     */
+    readonly events: EventManager;
+    /**
+     * The logger instance.
+     */
+    readonly logger: Logger;
+    /**
+     * Application base path.
+     */
+    readonly basePath: string;
+    /**
+     * Environment mode.
+     */
+    readonly env: 'development' | 'production' | 'testing';
+    /**
+     * Configuration options.
+     */
+    private readonly options;
+    /**
+     * Whether the application has been booted.
+     */
+    private booted;
+    constructor(options: ApplicationConfig);
+    /**
+     * Boot the application and its dependencies.
+     *
+     * This method orchestrates the full application lifecycle:
+     * 1. Configuration: Loads all config files from the config directory.
+     * 2. Discovery: Auto-discovers ServiceProviders from the providers directory.
+     * 3. Registration: Registers all discovered and explicit providers.
+     * 4. Bootstrapping: Triggers the PlanetCore bootstrap sequence.
+     *
+     * @returns Promise that resolves to the application instance for chaining.
+     *
+     * @example
+     * ```typescript
+     * const app = new Application({ basePath: import.meta.dir });
+     * await app.boot();
+     * ```
+     */
+    boot(): Promise<this>;
+    /**
+     * Load configuration files from the config directory.
+     *
+     * @internal
+     */
+    private loadConfiguration;
+    /**
+     * Discover and register providers from the providers directory.
+     *
+     * Phase 4 優化版本：採用 4-Phase 載入策略
+     * - Phase 1：預掃描所有候選 Provider 檔案（語法驗證）
+     * - Phase 2：篩選有效 Provider 檔案（跳過語法錯誤的）
+     * - Phase 3：平行 import 所有有效 Provider（從循序 → 並行）
+     * - Phase 4：逐一註冊到容器
+     *
+     * 效能改進：N 個 Provider 從 O(N * importTime) 降至 O(importTime + overhead)
+     *
+     * @internal
+     */
+    private discoverProviders;
+    /**
+     * Phase 1+2：預掃描 Provider 目錄中的所有候選檔案。
+     *
+     * 使用輕量語法驗證（嘗試讀取 + 基本結構檢查）篩選有效的 Provider 檔案，
+     * 讓語法錯誤在 import 之前被發現，提供更清晰的錯誤訊息。
+     *
+     * 策略：
+     * 1. 使用 Bun.Transpiler 進行 import 掃描（在 Bun 環境下）
+     * 2. Fallback 至基本檔案讀取驗證（在 Node/Deno 環境下）
+     *
+     * @param providersPath - Provider 目錄絕對路徑
+     * @returns 掃描結果陣列（含有效/無效標記）
+     * @internal
+     */
+    private prescribeProviders;
+    /**
+     * Phase 3：平行 import 所有有效的 Provider 檔案。
+     *
+     * 使用 Promise.all() 同時 import 所有通過預掃描的 Provider 檔案，
+     * 從循序載入（O(N)）改善為平行載入（O(1) 理論上），
+     * 實際效能受 I/O、CPU 和 V8 模組解析限制。
+     *
+     * @param validProviders - 通過預掃描的 Provider 掃描結果
+     * @returns 模組載入結果陣列
+     * @internal
+     */
+    private loadProvidersInParallel;
+    /**
+     * Resolve a service instance from the IoC container.
+     *
+     * This is a convenience wrapper around `container.make()`.
+     *
+     * @template T - The expected type of the service.
+     * @param key - The unique identifier or class name of the service.
+     * @returns The resolved service instance.
+     * @throws Error if the service is not bound in the container.
+     *
+     * @example
+     * ```typescript
+     * const db = app.make<Database>('db');
+     * ```
+     */
+    make<T>(key: string): T;
+    /**
+     * Check if a service is bound.
+     *
+     * @param key - The service key
+     * @returns True if bound
+     */
+    has(key: string): boolean;
+    /**
+     * Retrieve a configuration value using dot notation.
+     *
+     * @template T - The expected type of the configuration value.
+     * @param key - The configuration key (e.g., 'app.name', 'database.connections.mysql').
+     * @param defaultValue - Optional value to return if the key is not found.
+     * @returns The configuration value or the default value.
+     *
+     * @example
+     * ```typescript
+     * const port = app.getConfig<number>('app.port', 3000);
+     * ```
+     */
+    getConfig<T>(key: string, defaultValue?: T): T;
+    /**
+     * Resolve an absolute path relative to the application base path.
+     *
+     * @param segments - Path segments to join with the base path.
+     * @returns The absolute path string.
+     *
+     * @example
+     * ```typescript
+     * const storagePath = app.path('storage', 'logs');
+     * ```
+     */
+    path(...segments: string[]): string;
+    /**
+     * Get the config path.
+     *
+     * @param segments - Additional path segments
+     * @returns Absolute path to config directory
+     */
+    configPath(...segments: string[]): string;
+    /**
+     * Check if running in production.
+     */
+    isProduction(): boolean;
+    /**
+     * Check if running in development.
+     */
+    isDevelopment(): boolean;
+    /**
+     * Check if running in testing.
+     */
+    isTesting(): boolean;
+}

package/dist/core/src/CommandKernel.d.ts

@@ -0,0 +1,33 @@
+import type { Container } from './Container';
+/**
+ * CommandHandler type for custom CLI commands.
+ */
+export type CommandHandler = (args: string[], container: Container) => Promise<void> | void;
+/**
+ * CommandKernel - Structured CLI Command handling.
+ *
+ * Manages registration and execution of custom CLI commands that can
+ * reuse the application container and providers.
+ *
+ * @example
+ * ```typescript
+ * const kernel = new CommandKernel(container);
+ * kernel.register('greet', (args) => console.log('Hello', args[0]));
+ * await kernel.handle(['greet', 'Universe']);
+ * ```
+ */
+export declare class CommandKernel {
+    private container;
+    private commands;
+    constructor(container: Container);
+    /**
+     * Register a new command handler.
+     */
+    register(name: string, handler: CommandHandler): void;
+    /**
+     * Handle an incoming CLI command.
+     *
+     * @param argv - Array of command line arguments (e.g. process.argv.slice(2))
+     */
+    handle(argv: string[]): Promise<void>;
+}

package/dist/core/src/ConfigManager.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Configuration manager (ConfigManager)
+ *
+ * Unifies environment variables and application configuration access.
+ */
+import type { ZodSchema } from 'zod';
+/**
+ * ConfigManager - Central configuration store.
+ * Supports loading from environment variables and initial objects.
+ * @public
+ */
+export declare class ConfigManager {
+    private config;
+    private schema;
+    constructor(initialConfig?: Record<string, unknown>);
+    /**
+     * Load all environment variables from the active runtime.
+     */
+    private loadEnv;
+    /**
+     * Get a configuration value (generic return type supported).
+     * Supports dot notation for deep access (e.g. 'app.name').
+     */
+    get<T = unknown>(key: string, defaultValue?: T): T;
+    /**
+     * Set a configuration value.
+     */
+    set(key: string, value: unknown): void;
+    /**
+     * Check whether a key exists.
+     */
+    has(key: string): boolean;
+    /**
+     * Define a Zod schema for configuration validation.
+     *
+     * @param schema - Zod schema for validation
+     *
+     * @example
+     * ```typescript
+     * config.defineSchema(z.object({
+     *   DATABASE_URL: z.string().url(),
+     *   PORT: z.number().default(3000),
+     * }))
+     * ```
+     */
+    defineSchema(schema: ZodSchema): void;
+    /**
+     * Validate configuration against the defined schema.
+     *
+     * Should be called during bootstrap to catch configuration errors early.
+     *
+     * @throws Error if validation fails with details about missing/invalid fields
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   config.validate()
+     * } catch (error) {
+     *   console.error('Config validation failed:', error.message)
+     *   process.exit(1)
+     * }
+     * ```
+     */
+    validate(): void;
+}