@gravito/constellation 3.0.1 → 3.1.0

package/README.md

@@ -2,333 +2,178 @@
 title: Constellation
 ---
 
-# Constellation
+# Constellation 🛰️
 
-Dynamic and static sitemap generation for Gravito applications. Constellation can be used standalone or as the sitemap and route-scanning engine for Luminosity.
+Powerful, high-performance SEO and Sitemap orchestration module for **Gravito applications**. Built for enterprise-scale indexing, intelligent redirect management, and atomic deployments.
 
-**Constellation** provides a flexible way to generate XML sitemaps for your Gravito application, supporting both dynamic generation (via routes) and static generation (for build time). It includes support for Google Sitemap extensions like Images, Videos, News, and i18n alternates.
+**Constellation** provides a flexible way to manage your site's search engine visibility, supporting both dynamic on-the-fly generation and static build-time generation with cloud storage integration.
 
-## Features
+---
+
+## 🌟 Key Features
 
-- **Dynamic Generation**: Serve `sitemap.xml` directly from your application
-- **Static Generation**: Generate files for static hosting
-- **Auto Scanning**: Automatically scan registered routes
-- **Sitemap Extensions**: Support for Images, Videos, News, and i18n
-- **Sitemap Index**: Generators for large sites (Phase 1/2)
-- **Enterprise Features**:
-  - **Cloud Storage**: AWS S3 and Google Cloud Storage support
-  - **Shadow Processing**: Atomic switching and versioning for safe deployments
-  - **Background Jobs**: Non-blocking generation with progress tracking
-  - **Incremental Generation**: Only update changed URLs, not the entire sitemap
-  - **301 Redirect Handling**: Comprehensive redirect detection and processing
-  - **Progress Tracking**: Real-time progress monitoring via API
+### 🚀 High Performance & Scalability
+- **Streaming Generation**: Uses `SitemapStream` for memory-efficient XML building.
+- **Stream Writing (v3.1+)**: Reduces memory peaks by 40%+ with async iterable streaming to storage.
+- **Gzip Compression (v3.1+)**: Automatically compress sitemaps to reduce file size by 70%+ and save bandwidth.
+- **Auto-Sharding**: Automatically splits large sitemaps into multiple files (50,000 URLs limit) and generates sitemap indexes.
+- **Async Iterators**: Support for streaming data directly from databases via async generators.
+- **Distributed Locking**: Prevents "cache stampedes" in distributed environments (e.g., Kubernetes) using Redis locks.
 
-## Installation
+### 🏢 Enterprise SEO Orchestration
+- **Incremental Generation**: Only update modified URLs instead of regenerating the entire sitemap.
+- **Shadow Processing**: Atomic "blue-green" deployments for sitemaps using temporary staging and swapping.
+- **301/302 Redirect Handling**: Intelligent detection and removal/replacement of redirected URLs to ensure search engines only see canonical links.
+- **Cloud Storage Integration**: Built-in support for AWS S3 and Google Cloud Storage (GCS).
+
+### 🛠️ Advanced Capabilities
+- **Rich Extensions**: Support for Images, Videos, News, and i18n alternate links (hreflang).
+- **Background Jobs**: Non-blocking generation with persistent progress tracking.
+- **Admin API**: Built-in endpoints for triggering generation and monitoring status.
+- **Auto Route Scanning**: Automatically extracts URLs from Gravito's router.
+
+---
+
+## 📦 Installation
 
 ```bash
 bun add @gravito/constellation
 ```
 
-## Usage
+---
 
-### 1. Dynamic Sitemap (Runtime)
+## 🚀 Quick Start
 
-Integrate directly into your Gravito app:
+### 1. Dynamic Mode (Runtime)
+Ideal for small to medium sites where data changes frequently.
 
 ```typescript
-// gravito.config.ts or index.ts
 import { OrbitSitemap, routeScanner } from '@gravito/constellation'
 
-OrbitSitemap.dynamic({
+const sitemap = OrbitSitemap.dynamic({
   baseUrl: 'https://example.com',
   providers: [
-    // Automatically scan routes
+    // Automatically scan Gravito routes
     routeScanner(core.router, {
       exclude: ['/api/*', '/admin/*'],
       defaultChangefreq: 'daily'
     }),
     
-    // Custom provider (e.g. from database)
+    // Custom database provider
     {
       async getEntries() {
-        const posts = await db.query('SELECT slug, updated_at FROM posts')
+        const posts = await db.posts.findMany()
         return posts.map(post => ({
           url: `/blog/${post.slug}`,
-          lastmod: post.updated_at
+          lastmod: post.updatedAt
         }))
       }
     }
   ],
-  cacheSeconds: 3600 // Cache for 1 hour
-}).install(core)
-```
+  cacheSeconds: 3600 // HTTP cache headers
+})
 
-### 2. Static Generation (Build Time)
+sitemap.install(core)
+```
 
-Generate files during build:
+### 2. Static Mode (Build Time)
+Recommended for large-scale sites or when serving from a CDN.
 
 ```typescript
-import { OrbitSitemap, routeScanner } from '@gravito/constellation'
+import { OrbitSitemap, DiskSitemapStorage } from '@gravito/constellation'
 
 const sitemap = OrbitSitemap.static({
   baseUrl: 'https://example.com',
-  outDir: './dist',
-  providers: [
-    routeScanner(core.router),
-    // ...
-  ]
+  outDir: './dist/sitemaps',
+  storage: new DiskSitemapStorage('./dist/sitemaps'),
+  shadow: { enabled: true, mode: 'atomic' }, // Safe deployment
+  providers: [...]
 })
 
 await sitemap.generate()
 ```
 
-### 3. Manual Usage (SitemapStream)
-
-Use the low-level API for custom needs:
-
-```typescript
-import { SitemapStream } from '@gravito/constellation'
-
-const sitemap = new SitemapStream({ baseUrl: 'https://example.com' })
-
-sitemap.add('/')
-sitemap.add({
-  url: '/about',
-  changefreq: 'monthly',
-  priority: 0.8,
-  alternates: [
-    { lang: 'en', url: '/about' },
-    { lang: 'zh-TW', url: '/zh/about' }
-  ],
-  images: [
-    { loc: '/img/team.jpg', title: 'Our Team' }
-  ]
-})
-
-console.log(sitemap.toXML())
-```
-
-## Extensions
-
-### Video Sitemap
-```typescript
-sitemap.add({
-  url: '/video-page',
-  videos: [{
-    thumbnail_loc: 'https://...',
-    title: 'Video Title',
-    description: 'Description',
-    player_loc: 'https://...',
-    duration: 600
-  }]
-})
-```
-
-### News Sitemap
-```typescript
-sitemap.add({
-  url: '/news/article',
-  news: {
-    publication: { name: 'The Daily', language: 'en' },
-    publication_date: '2024-01-01',
-    title: 'Article Title'
-  }
-})
-```
-
-## Scaling & Distributed (Advanced)
-
-### Large Scale Sharding
-Orbit Sitemap automatically handles large datasets by splitting them into multiple files (default 50,000 URLs per file).
-
-```typescript
-OrbitSitemap.dynamic({
-  // ...
-  maxEntriesPerFile: 10000, // Custom split limit
-  storage: new RedisSitemapStorage({ ... }) // Store generated files in Redis/S3
-})
-```
-
-### Async Iterators (Streaming)
-For large datasets, use Async Generators in your providers to stream URLs without loading them all into memory.
+---
 
-```typescript
-{
-  async *getEntries() {
-    for await (const row of db.cursor('SELECT * FROM massive_table')) {
-      yield { url: `/item/${row.id}` }
-    }
-  }
-}
-```
+## 🏗️ Architecture & Modules
 
-### Distributed Locking
-In a distributed environment (e.g. Kubernetes), use `lock` to prevent concurrent sitemap generation.
+Constellation is composed of several specialized sub-modules:
 
-```typescript
-OrbitSitemap.dynamic({
-  // ...
-  lock: new RedisSitemapLock(redisClient),
-  storage: new S3SitemapStorage(bucket)
-})
-```
+| Component | Responsibility |
+|---|---|
+| **SitemapGenerator** | Core engine for building XML files and indexes. |
+| **IncrementalGenerator** | Handles partial updates based on change tracking. |
+| **RedirectHandler** | Processes URL lists against redirect rules. |
+| **ShadowProcessor** | Manages atomic staging and versioning of files. |
+| **RouteScanner** | Integrates with Gravito router for auto-discovery. |
+| **SitemapStorage** | Abstraction for Local Disk, S3, GCS, or Memory. |
 
-## Enterprise Features
+---
 
-### Cloud Storage (S3 / GCP)
+## 💎 Advanced Usage
 
-Store sitemaps directly in cloud storage with shadow processing:
+### Stream Writing & Compression (v3.1+)
+Reduce memory usage and file size with streaming and gzip compression:
 
 ```typescript
-import { OrbitSitemap, S3SitemapStorage } from '@gravito/constellation'
+import { SitemapGenerator, DiskSitemapStorage } from '@gravito/constellation'
 
-const sitemap = OrbitSitemap.static({
+const generator = new SitemapGenerator({
   baseUrl: 'https://example.com',
-  storage: new S3SitemapStorage({
-    bucket: 'my-sitemap-bucket',
-    region: 'us-east-1',
-    shadow: {
-      enabled: true,
-      mode: 'atomic' // or 'versioned'
-    }
-  }),
-  providers: [...]
-})
-```
-
-### Shadow Processing
-
-Generate sitemaps safely with atomic switching or versioning:
-
-```typescript
-const sitemap = OrbitSitemap.static({
-  // ...
-  shadow: {
+  storage: new DiskSitemapStorage('./public/sitemaps', 'https://example.com/sitemaps'),
+  providers: [...],
+  // 啟用 gzip 壓縮，減少檔案大小 70%+
+  compression: {
     enabled: true,
-    mode: 'atomic' // Atomic switch: generate to temp, then swap
-    // or 'versioned' // Versioning: keep old versions, switch when ready
+    level: 6  // 1-9，預設 6（平衡速度與壓縮率）
   }
 })
-```
-
-### Background Generation with Progress Tracking
-
-Generate sitemaps asynchronously without blocking:
 
-```typescript
-import { OrbitSitemap, MemoryProgressStorage } from '@gravito/constellation'
-
-const sitemap = OrbitSitemap.static({
-  // ...
-  progressStorage: new MemoryProgressStorage()
-})
-
-// Trigger background generation
-const jobId = await sitemap.generateAsync({
-  onProgress: (progress) => {
-    console.log(`${progress.percentage}% (${progress.processed}/${progress.total})`)
-  },
-  onComplete: () => {
-    console.log('Generation completed!')
-  }
-})
-
-// Query progress via API
-// GET /admin/sitemap/status/:jobId
+await generator.run()
+// 產生 sitemap.xml.gz（而非 sitemap.xml）
 ```
 
-### Incremental Generation
-
-Only update changed URLs, perfect for large sites:
+**效益**:
+- 🔥 記憶體峰值降低 40%+（大型 sitemap 使用串流寫入）
+- 📦 檔案大小減少 70%+（啟用 gzip 壓縮）
+- ⚡ 自動偵測 Storage 是否支援串流寫入
 
+### Cloud Storage (AWS S3)
 ```typescript
-import { OrbitSitemap, MemoryChangeTracker } from '@gravito/constellation'
+import { S3SitemapStorage } from '@gravito/constellation'
 
 const sitemap = OrbitSitemap.static({
+  storage: new S3SitemapStorage({
+    bucket: 'my-bucket',
+    region: 'us-west-2'
+  }),
+  compression: { enabled: true },  // 壓縮後上傳，節省 S3 儲存成本
   // ...
-  incremental: {
-    enabled: true,
-    changeTracker: new MemoryChangeTracker(),
-    autoTrack: true
-  }
 })
-
-// Full generation (first time)
-await sitemap.generate()
-
-// Incremental update (only changed URLs)
-await sitemap.generateIncremental(new Date('2024-01-01'))
 ```
 
-### 301 Redirect Handling
-
-Automatically handle URL redirects in your sitemap:
-
+### Background Progress Tracking
 ```typescript
-import { OrbitSitemap, MemoryRedirectManager, RedirectDetector } from '@gravito/constellation'
-
-const redirectManager = new MemoryRedirectManager()
-const detector = new RedirectDetector({
-  baseUrl: 'https://example.com',
-  autoDetect: {
-    enabled: true,
-    timeout: 5000,
-    cache: true
-  }
-})
-
-// Auto-detect redirects
-const redirects = await detector.detectBatch(['/old-page', '/another-old'])
-
-// Register redirects
-for (const [from, rule] of redirects) {
-  if (rule) {
-    await redirectManager.register(rule)
-  }
-}
+import { MemoryProgressStorage } from '@gravito/constellation'
 
 const sitemap = OrbitSitemap.static({
+  progressStorage: new MemoryProgressStorage(),
   // ...
-  redirect: {
-    enabled: true,
-    manager: redirectManager,
-    strategy: 'remove_old_add_new', // or 'keep_relation', 'update_url', 'dual_mark'
-    followChains: true,
-    maxChainLength: 5
-  }
 })
-```
-
-### API Endpoints
-
-Install API endpoints for triggering generation and querying progress:
-
-```typescript
-const sitemap = OrbitSitemap.static({ ... })
-
-// Install API endpoints
-sitemap.installApiEndpoints(core, '/admin/sitemap')
 
-// Available endpoints:
-// POST /admin/sitemap/generate - Trigger generation
-// GET /admin/sitemap/status/:jobId - Query progress
-// GET /admin/sitemap/history - List generation history
+// Trigger background job
+const jobId = await sitemap.generateAsync()
 ```
 
-### Creating Custom Storage/Lock
-Implement `SitemapStorage` and `SitemapLock` interfaces:
-
+### API Endpoints
+Install admin routes to manage sitemaps remotely:
 ```typescript
-import { SitemapStorage, SitemapLock } from '@gravito/constellation'
-
-class MyStorage implements SitemapStorage { ... }
-class MyLock implements SitemapLock { ... }
+sitemap.installApiEndpoints(core, '/admin/seo/sitemap')
+// POST /admin/seo/sitemap/generate
+// GET  /admin/seo/sitemap/status/:jobId
 ```
 
-## Type Reference
-
-See `dist/index.d.ts` for full type definitions including `SitemapEntry`, `SitemapImage`, `SitemapVideo`, etc.
-
-## License
+---
 
-MIT
+## 📄 License
+MIT © Carl Lee

package/README.zh-TW.md

@@ -1,33 +1,150 @@
-# Constellation
+---
+title: Constellation
+---
 
-> Gravito 的 Sitemap 產生器，支援動態輸出與靜態生成，可被 Luminosity 作為 sitemap 與路由掃描的工具層使用。
+# Constellation 🛰️
 
-## 特色
+強大且高效能的 SEO 與 Sitemap 編排模組，專為 **Gravito 應用程式**量身打造。支援企業級索引規模、智慧重新導向管理以及原子化部署。
 
-- **動態 sitemap**：在執行期提供 `sitemap.xml`
-- **靜態生成**：建置時輸出檔案
-- **路由掃描**：自動掃描已註冊路由
-- **擴充支援**：Images、Videos、News、i18n
+**Constellation** 提供彈性的方式來管理網站的搜尋引擎能見度，支援動態即時生成（Dynamic）以及建構時生成（Static），並可整合雲端儲存空間。
 
-## 安裝
+---
+
+## 🌟 核心特性
+
+### 🚀 高效能與可擴展性
+- **串流生成 (Streaming)**：使用 `SitemapStream` 進行記憶體效率極高的 XML 建立。
+- **自動分片 (Auto-Sharding)**：自動將大型 Sitemap 分割成多個檔案（預設單檔 50,000 條 URL）並生成 Sitemap Index 索引檔。
+- **非同步迭代器 (Async Iterators)**：支援透過 Async Generators 直接從資料庫串流讀取數據。
+- **分散式鎖定 (Distributed Locking)**：利用 Redis 鎖防止在分散式環境（如 Kubernetes）中發生「快取擊穿」(Cache Stampede)。
+
+### 🏢 企業級 SEO 編排
+- **增量生成 (Incremental Generation)**：僅更新有變動的 URL，而非重新生成整個 Sitemap。
+- **影子處理 (Shadow Processing)**：支援「藍綠部署」概念的原子化更新，透過暫存區進行驗證與切換。
+- **301/302 重新導向處理**：智慧偵測並移除或替換重新導向的 URL，確保搜尋引擎只抓取標準鏈結 (Canonical Links)。
+- **雲端儲存整合**：內建支援 AWS S3 與 Google Cloud Storage (GCS)。
+
+### 🛠️ 進階功能
+- **豐富的擴充協定**：支援圖片 (Images)、影片 (Videos)、新聞 (News) 以及 i18n 多語系交替連結 (hreflang)。
+- **背景任務 (Background Jobs)**：非阻塞式生成流程，並具備持久化的進度追蹤功能。
+- **管理 API**：內建端點可用於遠端觸發生成任務與監控狀態。
+- **自動路徑掃描**：自動從 Gravito 的路由系統中提取 URL。
+
+---
+
+## 📦 安裝
 
 ```bash
 bun add @gravito/constellation
 ```
 
-## 快速開始
+---
+
+## 🚀 快速上手
+
+### 1. 動態模式 (Dynamic Mode - 執行階段)
+適合中小型網站或資料變動頻繁的情境。
 
 ```typescript
 import { OrbitSitemap, routeScanner } from '@gravito/constellation'
 
-OrbitSitemap.dynamic({
+const sitemap = OrbitSitemap.dynamic({
   baseUrl: 'https://example.com',
   providers: [
+    // 自動掃描 Gravito 路由
     routeScanner(core.router, {
       exclude: ['/api/*', '/admin/*'],
       defaultChangefreq: 'daily'
-    })
+    }),
+    
+    // 自定義資料庫提供者
+    {
+      async getEntries() {
+        const posts = await db.posts.findMany()
+        return posts.map(post => ({
+          url: `/blog/${post.slug}`,
+          lastmod: post.updatedAt
+        }))
+      }
+    }
   ],
-  cacheSeconds: 3600
-}).install(core)
+  cacheSeconds: 3600 // HTTP 快取標頭
+})
+
+sitemap.install(core)
+```
+
+### 2. 靜態模式 (Static Mode - 建構階段)
+推薦用於大型網站或需要透過 CDN 發佈的情境。
+
+```typescript
+import { OrbitSitemap, DiskSitemapStorage } from '@gravito/constellation'
+
+const sitemap = OrbitSitemap.static({
+  baseUrl: 'https://example.com',
+  outDir: './dist/sitemaps',
+  storage: new DiskSitemapStorage('./dist/sitemaps'),
+  shadow: { enabled: true, mode: 'atomic' }, // 安全部署
+  providers: [...]
+})
+
+await sitemap.generate()
+```
+
+---
+
+## 🏗️ 架構與模組
+
+Constellation 由多個專業子模組組成：
+
+| 元件 | 職責 |
+|---|---|
+| **SitemapGenerator** | 負責建立 XML 檔案與索引的核心引擎。 |
+| **IncrementalGenerator** | 處理基於異動追蹤的局部更新。 |
+| **RedirectHandler** | 根據重新導向規則處理 URL 列表。 |
+| **ShadowProcessor** | 管理檔案的原子化暫存與版本控制。 |
+| **RouteScanner** | 整合 Gravito 路由實現自動發現。 |
+| **SitemapStorage** | 抽象化儲存層（本地磁碟、S3、GCS 或記憶體）。 |
+
+---
+
+## 💎 進階用法
+
+### 雲端儲存 (AWS S3)
+```typescript
+import { S3SitemapStorage } from '@gravito/constellation'
+
+const sitemap = OrbitSitemap.static({
+  storage: new S3SitemapStorage({
+    bucket: 'my-bucket',
+    region: 'us-west-2'
+  }),
+  // ...
+})
+```
+
+### 背景任務進度追蹤
+```typescript
+import { MemoryProgressStorage } from '@gravito/constellation'
+
+const sitemap = OrbitSitemap.static({
+  progressStorage: new MemoryProgressStorage(),
+  // ...
+})
+
+// 觸發背景任務
+const jobId = await sitemap.generateAsync()
 ```
+
+### 管理端 API 端點
+安裝管理路由以便遠端控管 Sitemap：
+```typescript
+sitemap.installApiEndpoints(core, '/admin/seo/sitemap')
+// POST /admin/seo/sitemap/generate - 觸發生成
+// GET  /admin/seo/sitemap/status/:jobId - 查詢進度
+```
+
+---
+
+## 📄 授權
+MIT © Carl Lee

package/dist/{DiskSitemapStorage-7ZZMGC4K.js → DiskSitemapStorage-VLN5I24C.js}

@@ -1,6 +1,6 @@
 import {
   DiskSitemapStorage
-} from "./chunk-7WHLC3OJ.js";
+} from "./chunk-3IZTXYU7.js";
 export {
   DiskSitemapStorage
 };