open-index/open-npm huggingface dataset:
npm package: @gravito/luminosity-adapter-photon
Description: Luminosity adapter for Photon-based environments
Author: Carl Lee
Latest version: 1.0.3

# @gravito/luminosity-adapter-photon

> Gravito SmartMap (Luminosity) 引擎的 Photon 適配器。

為您的 Photon 應用程式輕鬆整合自動化網站地圖 (Sitemap) 與 Robots.txt 生成功能。此適配器提供了一個輕量級的中間件 (Middleware)，利用強大的 Luminosity 引擎來處理 SEO 相關請求。

## ✨ 特性

- 🪐 **無縫整合** - 適用於任何 Photon 應用程式的簡單中間件。
- 🤖 **自動化 Robots.txt** - 根據您的配置動態生成 robots.txt。
- 🗺️ **智能網站地圖引擎** - 全面支援 `sitemap.xml`，包括索引檔案與分頁地圖 (例如 `sitemap_page_1.xml`)。
- ⚡ **延遲初始化** - SEO 引擎僅在收到第一個相關請求時才進行初始化，節省啟動時的資源。
- 🛡️ **I/O 優化** - 自動設置正確的 `Content-Type` 標頭 (`application/xml` 或 `text/plain`)。
- 🧪 **易於測試** - 內建依賴注入支援，方便進行單元測試。

## 📦 安裝

```bash
bun add @gravito/luminosity-adapter-photon @gravito/luminosity
```

## 🚀 快速上手

```typescript
import { Photon } from '@gravito/photon';
import { gravitoSeo } from '@gravito/luminosity-adapter-photon';

const app = new Photon();

// 中間件整合
app.use('*', gravitoSeo({
  hostname: 'https://example.com',
  // 請參閱 @gravito/luminosity 以獲取完整配置選項
  sitemap: true,
  robots: true
}));

app.get('/', (c) => c.text('Hello Galaxy!'));

export default app;
```

## 📖 API 參考

### `gravitoSeo(config, deps?)`

建立一個 Photon 中間件處理器。

- **`config`**: 來自 `@gravito/luminosity` 的 `SeoConfig` 物件。
- **`deps`**: (選填) `GravitoSeoDeps` 用於覆蓋內部實作 (主要用於測試)。
    - `SeoEngine`: 自定義的 `SeoEngine` 類別實作。

### 處理的路徑

此中間件會自動攔截並處理以下路徑：
- `/robots.txt`
- `/sitemap.xml`
- `/sitemap_page_{n}.xml`
- 任何包含 `sitemap` 且以 `.xml` 結尾的路徑。

它會明確忽略 `/docs/` 下的任何路徑，以避免與文件路由產生衝突。

## 🤝 貢獻

歡迎提交貢獻、問題與功能請求！
請隨時查看 [Issues 頁面](https://github.com/gravito-framework/gravito/issues)。

## 📝 授權

MIT © [Carl Lee](https://github.com/gravito-framework/gravito)
npm package: @gravito/luminosity-cli
Description: CLI tool for Gravito SmartMap Engine
Author: Carl Lee
Latest version: 1.0.2

# @gravito/luminosity-cli 🛠️

> Gravito SmartMap Engine 的命令列工具 (CLI)。

`@gravito/luminosity-cli` 是 `@gravito/luminosity` 的配套工具，讓您能夠直接在終端機中初始化 SEO 配置、手動產生 sitemap，以及管理增量日誌 (incremental logs)。

## 📦 安裝

```bash
bun add @gravito/luminosity-cli
```

或者使用 `bunx` 直接執行：

```bash
bunx gravito-seo --help
```

## 🚀 指令說明

### `init`
在專案中初始化新的 Gravito SEO 配置檔案。

```bash
gravito-seo init
```
此指令會啟動引導程式，協助您建立 `gravito.seo.config.ts` 檔案。

### `generate`
根據您的配置手動產生 `sitemap.xml` 檔案。

```bash
# 基本產生指令
gravito-seo generate

# 指定自定義配置檔案與輸出路徑
gravito-seo generate --config ./configs/seo.ts --out ./dist/sitemap.xml
```

**選項：**
- `-c, --config <path>`: 配置檔案的路徑。
- `-o, --out <path>`: 輸出路徑 (例如：`./public/sitemap.xml`)。

### `compact`
強制執行增量日誌的壓縮 (Compaction)。當使用 `incremental` 模式時，此指令能將分散的日誌紀錄合併，提升效能。

```bash
gravito-seo compact
```

**選項：**
- `-c, --config <path>`: 配置檔案的路徑。

## 🔧 全域選項

- `-v, --version`: 顯示目前版本。
- `-h, --help`: 顯示指令說明。

## 📄 開源授權

MIT © Carl Lee
npm package: @gravito/mass
Description: TypeBox-based validation for Gravito - High-performance schema validation with full TypeScript support
Author: Carl Lee
Latest version: 3.0.3

# @gravito/mass ⚖️

> 基於 TypeBox 的高效能 Schema 驗證工具，專為 Gravito Galaxy 架構設計。

`@gravito/mass` 為您的 Gravito 應用程式提供數據完整性的「重量」。基於 **TypeBox** 構建，它提供了極快的執行期驗證速度與完整的 TypeScript 類型推導，並與 **Photon** HTTP 引擎無縫整合。

## 🌟 核心特性

- **🚀 效能優先**：利用 TypeBox 的編譯期驗證器生成技術，實現近乎零負擔的執行期效能。
- **🛡️ 完整類型安全**：自動進行 TypeScript 類型推導 —— 無需分別維護 Interface 與 Schema。
- **🔌 Photon 深度整合**：提供原生中間件，支援驗證 JSON、Query、URL 參數及表單數據。
- **🛠️ Schema 實用工具**：提供如 `partial()` 等進階輔助函式，輕鬆建立 PATCH 接口所需的 Schema。
- **🪝 靈活的 Hook 機制**：可攔截驗證結果，自定義錯誤回應格式或紀錄日誌。
- **📦 Galaxy 架構相容**：遵循 Gravito 的模組化哲學，保持依賴精簡且高效。

## 📦 安裝

```bash
bun add @gravito/mass
```

## 🚀 快速上手

### 基礎 JSON 驗證

使用 `Schema` 定義數據結構，並透過 `validate` 中間件應用於路由。

```typescript
import { Photon } from '@gravito/photon'
import { Schema, validate } from '@gravito/mass'

const app = new Photon()

const CreateUserSchema = Schema.Object({
  username: Schema.String({ minLength: 3 }),
  email: Schema.String({ format: 'email' }),
  age: Schema.Number({ minimum: 18 })
})

app.post('/users', 
  validate('json', CreateUserSchema), 
  (c) => {
    // 數據已自動推導類型為 { username: string; email: string; age: number }
    const user = c.req.valid('json')
    return c.json({ success: true, data: user })
  }
)
```

### 驗證不同數據源

Mass 可以驗證 HTTP 請求中不同位置的數據：

```typescript
// 驗證 Query 參數
app.get('/search', 
  validate('query', Schema.Object({ q: Schema.String() })),
  (c) => {
    const { q } = c.req.valid('query')
    return c.text(`正在搜尋：${q}`)
  }
)

// 驗證 URL 參數
app.get('/users/:id',
  validate('param', Schema.Object({ id: Schema.Number() })),
  (c) => {
    const { id } = c.req.valid('param')
    return c.json({ userId: id })
  }
)
```

## ⏳ 進階模式

### 部分更新 (PATCH)

使用 `partial()` 工具將 Schema 中的所有屬性轉為可選，非常適合用於更新接口。

```typescript
import { partial } from '@gravito/mass'

const UpdateUserSchema = partial(CreateUserSchema)

app.patch('/users/:id', 
  validate('json', UpdateUserSchema), 
  (c) => {
    const updates = c.req.valid('json')
    return c.json({ updated: updates })
  }
)
```

### 自定義錯誤處理

透過驗證 Hook 覆蓋預設的 400 回應，提供符合您需求的錯誤格式。

```typescript
app.post('/strict-endpoint',
  validate('json', schema, (result, c) => {
    if (!result.success) {
      return c.json({
        code: 'VAL_ERR',
        errors: result.errors.map(e => ({ field: e.path, msg: e.message }))
      }, 422)
    }
  }),
  (c) => c.text('成功')
)
```

## 🧩 API 參考

### `validate(source, schema, hook?)`
強制執行 Schema 驗證的主要中間件。
- `source`: `'json' | 'query' | 'param' | 'form'`
- `schema`: TypeBox Schema 實例。
- `hook`: `(result, context) => Response | undefined`

### `Schema`
定義數據結構的核心工具，重新導出了所有 TypeBox 的建構子。
- `Schema.String()`
- `Schema.Number()`
- `Schema.Boolean()`
- `Schema.Object({ ... })`
- `Schema.Array(...)`
- `Schema.Optional(...)`

### `partial(schema)`
遞迴地將物件 Schema 中的所有屬性設為可選。

## 🤝 參與貢獻

我們歡迎任何形式的貢獻！詳細資訊請參閱 [貢獻指南](../../CONTRIBUTING.md)。

## 📄 開源授權

MIT © Carl Lee
npm package: @gravito/pulse
Description: The official CLI for Gravito Galaxy Architecture. Scaffold projects and manage your universe.
Author: Carl Lee
Latest version: 4.0.1

# Orbit Pulse

> Gravito 官方 CLI，提供專案建立、程式碼產生與開發工具。

## 安裝

```bash
# 全域安裝（建議）
bun add -g @gravito/pulse

# 或使用 bunx
bunx @gravito/pulse create my-app
```

## 快速開始

```bash
# 互動式建立專案
gravito create my-app

# 使用模板
gravito create my-app --template basic
```

## 常用指令

```bash
# 產生 Controller
gravito make:controller UserController

# 列出路由
gravito route:list
```
npm package: @gravito/resilience
Description: Event system resilience layer for Gravito (Circuit Breaker, DLQ, Backpressure, Worker Pool)
Latest version: 2.0.0

# @gravito/resilience

Event system resilience layer for Gravito framework - providing Circuit Breaker, Dead Letter Queue, Backpressure management, Worker Pool, and other reliability patterns.

## ✨ Features

- 🛡️ **Circuit Breaker**: Prevent cascading failures across Satellites with automatic state transitions.
- ⚙️ **Auto-scaling Worker Pools**: Native Bun worker implementation with dynamic scaling based on real-time load.
- 🔄 **Distributed Retry Scheduler**: Reliable task retries utilizing Bull Queue (Redis) for persistence.
- 📦 **Backpressure Management**: Intelligent flow control to protect your system from traffic spikes.
- 🎯 **Priority Queueing**: Ensure mission-critical tasks are processed first.
- 📊 **Observability**: Built-in OpenTelemetry integration for monitoring pool health and circuit states.
- 🧩 **Idempotency Support**: Safely retry operations without unintended side effects.

## 🌌 Role in Galaxy Architecture

In the **Gravito Galaxy Architecture**, Resilience acts as the **Guardian Layer (Immune System)**.

- **Satellite Isolation**: Ensures that a failure in one Satellite (e.g., `Catalog`) doesn't take down the entire Galaxy via circuit breakers.
- **Background Autopilot**: Manages the lifecycle of asynchronous tasks through its Worker Pool, offloading heavy processing from the `Photon` Sensing Layer.
- **Distributed Reliability**: Provides a unified interface for retries and DLQs that works across multiple process boundaries.

```mermaid
graph TD
    P[Photon: Sensing] --> S[Satellite: Business]
    S -- "Faulty Call" --> CB{Circuit Breaker}
    CB -- "Open" --> F[Fallback Response]
    S -- "Async Task" --> WP[Worker Pool]
    WP -- "Failed" --> RS[Retry Scheduler]
    RS -- "Persistent Fail" --> DLQ[Dead Letter Queue]
```

## Installation

```bash
bun add @gravito/resilience
```

## Usage

```typescript
import { CircuitBreaker, DeadLetterQueue, WorkerPool } from '@gravito/resilience'

// Use resilience components
const circuitBreaker = new CircuitBreaker({
  failureThreshold: 5,
  resetTimeout: 60000,
})
```

## 📚 Documentation

Detailed guides and references for the Galaxy Architecture:

- [🏗️ **Architecture Overview**](./README.md) — Resilience patterns and Guardian Layer.
- [⚙️ **Bun Worker Pool Guide**](./doc/BUN_WORKERS.md) — **NEW**: Dynamic scaling and multi-threaded processing.
- [🛡️ **Fault Tolerance Guide**](./doc/FAULT_TOLERANCE.md) — **NEW**: Circuit Breakers, Retry, and DLQ patterns.
- [📊 **Observability Guide**](./src/observability/index.ts) — Metrics and distributed tracing.
- [🔄 **Retry & Idempotency**](./src/retry/index.ts) — Reliable event delivery.

## Peer Dependencies

- `@gravito/core`: ^1.7.0
- `@opentelemetry/api`: ^1.9.0 (optional)

## License

MIT
npm package: @gravito/ripple
Description: Bun-native WebSocket broadcasting for Gravito. Channel-based real-time communication.
Author: Carl Lee
Latest version: 5.0.0

# @gravito/ripple

> 🌊 高性能 WebSocket 廣播模組，專為 Bun 打造。支援頻道式即時通訊。

[![Test Coverage](https://img.shields.io/badge/coverage-95.24%25-brightgreen)]()
[![Tests](https://img.shields.io/badge/tests-198%20passing-success)]()
[![TypeScript](https://img.shields.io/badge/typescript-5.x-blue)]()
[![Bun](https://img.shields.io/badge/bun-%3E%3D1.0-orange)]()

## 特性

- ⚡ **Bun 原生 WebSocket** - 零外部依賴，比 ws 函式庫快 3 倍
- 📡 **頻道式廣播** - 支援公開 (Public)、私有 (Private) 與存在 (Presence) 頻道
- 🔒 **安全授權** - 靈活的基於回呼 (Callback) 的授權系統
- 📊 **生產級可靠性** - 95.24% 測試覆蓋率，經過實戰檢驗的架構
- 🚀 **水平擴展** - 支援 Redis 驅動，實現多伺服器部署
- 🔍 **全方位可觀測性** - 內建日誌、健康檢查與連線追蹤
- 💪 **類型安全** - 全面的 TypeScript 支援與完整的 JSDoc 文檔
- 🎯 **Laravel Echo 相容** - 開發者熟悉的 API 設計

## 為什麼選擇 Ripple？

### 性能優先
- **亞毫秒延遲**：Bun 原生 WebSocket 實現 <1ms 的訊息傳遞
- **低內存占用**：10,000 個並發連線僅需約 25MB 內存
- **高效序列化**：訊息快取機制減少 60% 的 CPU 開銷

### 生產準備
- **198 個測試案例**，95.24% 代碼覆蓋率
- **優雅停機**：確保連線正確清理
- **內建監控**：即時健康檢查與性能指標
- **錯誤追蹤**：結構化日誌記錄

### 可擴展架構
- **LocalDriver**：零依賴的單機部署
- **RedisDriver**：跨伺服器的水平擴展
- **自定義驅動**：可輕鬆實作 NATS、RabbitMQ 等驅動

## 安裝

```bash
bun add @gravito/ripple
```

## 快速開始

### 伺服器設定

```typescript
import { PlanetCore } from '@gravito/core'
import { OrbitRipple, RippleServer } from '@gravito/ripple'

const core = new PlanetCore()

// 安裝 Ripple 模組
core.install(new OrbitRipple({
  path: '/ws',
  authorizer: async (channel, userId, socketId) => {
    // 私有頻道授權邏輯
    if (channel.startsWith('private-orders.')) {
      return userId !== undefined
    }
    // 存在頻道範例
    if (channel.startsWith('presence-chat.')) {
      return { id: userId, info: { name: 'User' } }
    }
    return true
  }
}))

const ripple = core.container.make<OrbitRipple>('ripple')

// 啟動伺服器
Bun.serve({
  port: 3000,
  fetch: (req, server) => {
    // 處理 WebSocket 升級
    if (ripple.getServer().upgrade(req, server)) return
    return new Response('Hello World')
  },
  websocket: ripple.getHandler()
})
```

### 發送廣播

```typescript
import { broadcast, PrivateChannel, BroadcastEvent } from '@gravito/ripple'

// 定義廣播事件
class OrderShipped extends BroadcastEvent {
  constructor(public orderId: number, public userId: string) {
    super()
  }

  broadcastOn() {
    return new PrivateChannel(`orders.${this.userId}`)
  }

  broadcastAs() {
    return 'order.shipped'
  }
}

// 在應用程式任何地方發送
broadcast(new OrderShipped(123, 'user_abc'))
```

## 性能表現

### 基準測試 (10,000 連線, 100KB 訊息)

| 指標 | LocalDriver | RedisDriver | ws library |
|--------|-------------|-------------|------------|
| **延遲 (p95)** | 0.8ms | 2.1ms | 2.5ms |
| **內存占用** | 25MB | 35MB | 65MB |
| **CPU 占用** | 12% | 18% | 45% |
| **吞吐量** | 100K msg/s | 50K msg/s | 30K msg/s |

## 文檔連結 (英文)

- **[架構概覽](./docs/architecture/overview.md)**
- **[授權模型](./docs/architecture/ADR-002-channel-authorization.md)**
- **[驅動層設計](./docs/architecture/ADR-003-driver-abstraction.md)**
- **[故障排除指南](./docs/troubleshooting.md)**
- **[安全指南](./docs/security.md)**

## 授權條款

MIT