@gravito/nebula 4.0.0 → 4.1.0

package/README.md

@@ -1,8 +1,23 @@
 # @gravito/nebula
 
-> The Standard Storage Orbit for Galaxy Architecture.
+> The Standard Storage Orbit for Galaxy Architecture. Lightweight, multi-disk, and pluggable.
 
-Provides a unified file storage abstraction layer with multi-disk support and pluggable backends.
+[![npm version](https://img.shields.io/npm/v/@gravito/nebula.svg)](https://www.npmjs.com/package/@gravito/nebula)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![Bun](https://img.shields.io/badge/Bun-1.0+-black.svg)](https://bun.sh/)
+
+**@gravito/nebula** provides a unified file storage abstraction layer for Gravito applications. Built on the **Orbit** pattern, it acts as a bridge between the core micro-kernel and various storage backends (Local, S3, Memory, etc.), supporting multi-disk configurations and high extensibility via hooks.
+
+## ✨ Features
+
+- 🪐 **Orbit Integration** - Seamlessly plugs into the PlanetCore micro-kernel.
+- 💽 **Multi-Disk Support** - Manage multiple storage backends (disks) within a single application.
+- 🔌 **Pluggable Drivers** - Built-in support for `local`, `memory`, and `null` drivers, with easy `custom` driver implementation.
+- 🪝 **Powerful Hooks** - Intercept and modify storage operations (upload, delete, etc.) using Gravito's async Hook system.
+- 🏢 **Enterprise Ready** - Automatic service registration in the IoC container and context-aware middleware.
+- 🧪 **Test Friendly** - Includes a `MemoryStore` for fast, zero-side-effect unit testing.
+- 🚀 **Modern** - Built for **Bun** with native TypeScript support.
 
 ## 📦 Installation
 
@@ -12,14 +27,15 @@ bun add @gravito/nebula
 
 ## 🚀 Quick Start
 
-### Basic Usage
+### 1. Initialize with PlanetCore
 
 ```typescript
-import { PlanetCore } from '@gravito/core'
-import orbitStorage from '@gravito/nebula'
+import { PlanetCore } from '@gravito/core';
+import orbitStorage from '@gravito/nebula';
 
-const core = new PlanetCore()
+const core = new PlanetCore();
 
+// Quick install with options
 const storage = orbitStorage(core, {
   default: 'local',
   disks: {
@@ -29,326 +45,131 @@ const storage = orbitStorage(core, {
       baseUrl: '/uploads'
     }
   }
-})
+});
+```
 
-// Use in routes
+### 2. Use in Routes (Middleware)
+
+Nebula automatically injects the `storage` manager into the request context:
+
+```typescript
 core.app.post('/upload', async (c) => {
-  const body = await c.req.parseBody()
-  const file = body['file']
+  const body = await c.req.parseBody();
+  const file = body['file'];
   
   if (file instanceof File) {
-    const storage = c.get('storage')
-    await storage.put(file.name, file)
-    return c.json({ url: storage.getUrl(file.name) })
+    const storage = c.get('storage'); // Resolved from context
+    await storage.put(`avatars/${file.name}`, file);
+    
+    return c.json({ 
+      success: true, 
+      url: storage.getUrl(`avatars/${file.name}`) 
+    });
   }
   
-  return c.text('No file uploaded', 400)
-})
+  return c.text('No file uploaded', 400);
+});
 ```
 
----
-
 ## 🔧 Multi-Disk Configuration
 
+You can define multiple disks and switch between them at runtime:
+
 ```typescript
 const storage = orbitStorage(core, {
   default: 'local',
   disks: {
-    // Local disk
-    local: {
-      driver: 'local',
-      root: './uploads',
-      baseUrl: '/uploads'
-    },
-    
-    // Memory disk (for testing)
-    temp: {
-      driver: 'memory'
-    },
-    
-    // Null disk (no-op)
-    null: {
-      driver: 'null'
-    },
-    
-    // Custom disk (e.g., S3)
+    local: { driver: 'local', root: './uploads', baseUrl: '/uploads' },
+    temp: { driver: 'memory' },
     s3: {
       driver: 'custom',
-      store: new S3Store({
-        bucket: 'my-bucket',
-        region: 'us-east-1'
-      })
+      store: new S3Store({ bucket: 'my-bucket' })
     }
   }
-})
+});
 
-// Use default disk
-await storage.put('file.txt', 'content')
+// Uses 'local' (default)
+await storage.put('hello.txt', 'world');
 
-// Use specific disk
-await storage.disk('s3').put('important.pdf', pdfData)
-await storage.disk('temp').put('cache.json', jsonData)
+// Uses 's3' disk explicitly
+await storage.disk('s3').put('backup.zip', data);
 ```
 
----
-
 ## 📖 API Reference
 
-### StorageManager
-
-The main storage manager returned by `orbitStorage()` or `c.get('storage')`.
-
-#### Methods
-
-##### `disk(name?: string): StorageRepository`
-
-Get a specific disk repository. If `name` is not provided, returns the default disk.
-
-```typescript
-const local = storage.disk('local')
-const s3 = storage.disk('s3')
-```
-
-##### `put(key: string, data: Blob | Buffer | string): Promise<void>`
-
-Store a file (using default disk).
-
-```typescript
-await storage.put('file.txt', 'Hello World')
-await storage.put('image.png', imageBlob)
-```
-
-##### `get(key: string): Promise<Blob | null>`
-
-Retrieve a file (using default disk).
-
-```typescript
-const data = await storage.get('file.txt')
-if (data) {
-  console.log(await data.text())
-}
-```
-
-##### `delete(key: string): Promise<boolean>`
-
-Delete a file (using default disk). Returns `true` if deleted, `false` if file didn't exist.
-
-```typescript
-const deleted = await storage.delete('old-file.txt')
-```
-
-##### `exists(key: string): Promise<boolean>` 🆕
-
-Check if a file exists (using default disk).
-
-```typescript
-if (await storage.exists('config.json')) {
-  // File exists
-}
-```
-
-##### `copy(from: string, to: string): Promise<void>` 🆕
-
-Copy a file (using default disk).
-
-```typescript
-await storage.copy('original.txt', 'backup.txt')
-```
-
-##### `move(from: string, to: string): Promise<void>` 🆕
-
-Move/rename a file (using default disk).
-
-```typescript
-await storage.move('temp.txt', 'final.txt')
-```
-
-##### `getMetadata(key: string): Promise<StorageMetadata | null>` 🆕
-
-Get file metadata (using default disk).
+### `StorageManager`
 
-```typescript
-const meta = await storage.getMetadata('file.pdf')
-if (meta) {
-  console.log(meta.size, meta.mimeType, meta.lastModified)
-}
-```
-
-##### `getUrl(key: string): string`
-
-Get the public URL for a file (using default disk).
-
-```typescript
-const url = storage.getUrl('avatar.jpg')
-// "/uploads/avatar.jpg"
-```
+The central hub accessed via `c.get('storage')` or returned by `orbitStorage()`.
 
-##### `getSignedUrl(key: string, expiresIn: number): Promise<string>` 🆕
+- **`disk(name?: string)`**: Access a specific disk repository.
+- **`put(key, data)`**: Store content (Default disk).
+- **`get(key)`**: Retrieve content as a `Blob` (Default disk).
+- **`delete(key)`**: Remove a file (Default disk).
+- **`exists(key)`**: Check file existence (Default disk).
+- **`copy(from, to)`**: Copy a file (Default disk).
+- **`move(from, to)`**: Move/Rename a file (Default disk).
+- **`getUrl(key)`**: Get public URL (Default disk).
+- **`getSignedUrl(key, expires)`**: Get temporary signed URL (Default disk).
+- **`getMetadata(key)`**: Get file metadata (size, mimeType, etc.).
+- **`list(prefix?)`**: List files as an async iterable.
 
-Get a signed URL with expiration (if supported by the driver).
-
-```typescript
-// Generate a URL that expires in 1 hour
-const signedUrl = await storage.disk('s3').getSignedUrl('private.pdf', 3600)
-```
-
-##### `list(prefix?: string): AsyncIterable<StorageItem>` 🆕
-
-List files in a directory (if supported by the driver).
-
-```typescript
-for await (const item of storage.list('uploads/')) {
-  console.log(item.key, item.size, item.lastModified)
-}
-```
+### `StorageRepository`
 
----
+Returned by `storage.disk('name')`. Implements the same storage methods as above but scoped to that specific disk.
 
 ## 🪝 Hooks
 
-Nebula integrates with Gravito's hook system for extensibility.
+Nebula triggers various hooks during its lifecycle:
 
-| Hook | Type | Parameters | Description |
-|------|------|------------|-------------|
-| `storage:init` | Action | `{ manager: StorageManager }` | Fired when storage is initialized |
-| `storage:upload` | Filter | `data: Blob/Buffer/string, { key: string }` | Modify data before upload |
-| `storage:uploaded` | Action | `{ key: string }` | Triggered after successful upload |
-| `storage:hit` | Action | `{ key: string }` | File retrieved successfully |
-| `storage:miss` | Action | `{ key: string }` | File not found |
-| `storage:deleted` | Action | `{ key: string }` | File deleted |
-| `storage:copied` 🆕 | Action | `{ from: string, to: string }` | File copied |
-| `storage:moved` 🆕 | Action | `{ from: string, to: string }` | File moved |
+| Hook | Type | Context | Description |
+|------|------|---------|-------------|
+| `storage:init` | Action | `{ manager }` | Fired on initialization |
+| `storage:upload` | Filter | `data, { key }` | Modify data before it's saved |
+| `storage:uploaded`| Action | `{ key }` | Fired after successful save |
+| `storage:hit` | Action | `{ key }` | Fired when file is found/retrieved |
+| `storage:miss` | Action | `{ key }` | Fired when file is not found |
+| `storage:deleted` | Action | `{ key }` | Fired after file deletion |
 
-### Example: Auto-resize Images on Upload
+### Example: Image Resizing
 
 ```typescript
 core.hooks.addFilter('storage:upload', async (data, context) => {
-  if (context.key.endsWith('.jpg') || context.key.endsWith('.png')) {
-    // Resize image using sharp, etc.
-    return await resizeImage(data, { width: 1920 })
+  if (context.key.match(/\.(jpg|png)$/)) {
+    return await myImageProcessor.resize(data, 800);
   }
-  return data
-})
-```
-
-### Example: Log All Uploads
-
-```typescript
-core.hooks.addAction('storage:uploaded', async (context) => {
-  core.logger.info(`File uploaded: ${context.key}`)
-})
+  return data;
+});
 ```
 
----
+## 🔌 Custom Drivers
 
-## 🔌 Custom Storage Drivers
-
-Implement the `StorageStore` interface to create custom drivers.
+Implement the `StorageStore` interface to create your own backend:
 
 ```typescript
-import type { StorageStore, StorageMetadata } from '@gravito/nebula'
-
-class S3Store implements StorageStore {
-  async put(key: string, data: Blob | Buffer | string): Promise<void> {
-    // Upload to S3
-  }
-
-  async get(key: string): Promise<Blob | null> {
-    // Download from S3
-  }
-
-  async delete(key: string): Promise<boolean> {
-    // Delete from S3
-  }
-
-  async exists(key: string): Promise<boolean> {
-    // Check if exists in S3
-  }
+import type { StorageStore, StorageMetadata } from '@gravito/nebula';
 
-  async copy(from: string, to: string): Promise<void> {
-    // S3 copy operation
-  }
-
-  async move(from: string, to: string): Promise<void> {
-    await this.copy(from, to)
-    await this.delete(from)
-  }
-
-  async getMetadata(key: string): Promise<StorageMetadata | null> {
-    // Get S3 object metadata
-  }
-
-  getUrl(key: string): string {
-    return `https://my-bucket.s3.amazonaws.com/${key}`
-  }
-
-  async getSignedUrl(key: string, expiresIn: number): Promise<string> {
-    // Generate pre-signed URL
-  }
+class MyCustomStore implements StorageStore {
+  async put(key: string, data: Blob | Buffer | string): Promise<void> { /* ... */ }
+  async get(key: string): Promise<Blob | null> { /* ... */ }
+  async delete(key: string): Promise<boolean> { /* ... */ }
+  async exists(key: string): Promise<boolean> { /* ... */ }
+  getUrl(key: string): string { /* ... */ }
+  // ... implement other methods
 }
-
-// Use it
-const storage = orbitStorage(core, {
-  disks: {
-    s3: {
-      driver: 'custom',
-      store: new S3Store({ bucket: 'my-bucket' })
-    }
-  }
-})
 ```
 
----
-
 ## 🔄 Migration from v3.x
 
-### Configuration Changes
-
-```typescript
-// v3.x (Old)
-orbitStorage(core, {
-  local: { root: './uploads', baseUrl: '/uploads' },
-  exposeAs: 'storage'
-})
-
-// v4.0 (New)
-orbitStorage(core, {
-  default: 'local',
-  disks: {
-    local: { driver: 'local', root: './uploads', baseUrl: '/uploads' }
-  },
-  exposeAs: 'storage'
-})
-```
-
-**Note**: The old format is still supported for backward compatibility but is deprecated.
-
-### Return Value Changes
-
-```typescript
-// v3.x - Returns wrapped provider
-const storage = orbitStorage(core, { ... })
-await storage.put('file.txt', data)
-
-// v4.0 - Returns StorageManager
-const storage = orbitStorage(core, { ... })
-await storage.put('file.txt', data)  // Same API!
-await storage.disk('s3').put('file.txt', data)  // New!
-```
-
-The API is backward compatible, but v4.0 adds multi-disk support via `disk()`.
-
-### Type Changes
+Nebula v4.0 introduces the **Manager** pattern for multi-disk support. 
 
-| v3.x | v4.0 |
-|------|------|
-| `StorageProvider` | `StorageStore` |
-| `LocalStorageProvider` | `LocalStore` |
-| `OrbitStorageOptions` | `OrbitNebulaOptions` |
+- **Breaking**: The configuration structure has moved under a `disks` property.
+- **Compatibility**: The old flat configuration format is still supported but will trigger a deprecation warning.
+- **Types**: `StorageProvider` is now `StorageStore`, and `LocalStorageProvider` is now `LocalStore`.
 
-Old type names are still exported with `@deprecated` warnings.
+## 🤝 Contributing
 
----
+Contributions, issues and feature requests are welcome!
+Feel free to check the [issues page](https://github.com/gravito-framework/gravito/issues).
 
 ## 📝 License
 

package/README.zh-TW.md

@@ -1,37 +1,176 @@
 # @gravito/nebula
 
-> Gravito 的標準儲存 Orbit，提供檔案儲存抽象層。
+> Galaxy 架構的標準儲存 Orbit。輕量、多磁碟支援且可插拔。
 
-## 安裝
+[![npm version](https://img.shields.io/npm/v/@gravito/nebula.svg)](https://www.npmjs.com/package/@gravito/nebula)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![Bun](https://img.shields.io/badge/Bun-1.0+-black.svg)](https://bun.sh/)
+
+**@gravito/nebula** 為 Gravito 應用程式提供統一的檔案儲存抽象層。基於 **Orbit** 模式，它充當核心微核心與各種儲存後端（本地、S3、記憶體等）之間的橋樑，支援多磁碟配置並透過 Hook 系統提供高度可擴展性。
+
+## ✨ 特性
+
+- 🪐 **Orbit 整合** - 無縫插入 PlanetCore 微核心。
+- 💽 **多磁碟支援** - 在單個應用程式中管理多個儲存後端（磁碟）。
+- 🔌 **可插拔驅動** - 內建支援 `local`、`memory` 與 `null` 驅動，並支援輕鬆實作 `custom` 驅動。
+- 🪝 **強大的 Hooks** - 使用 Gravito 的異步 Hook 系統攔截並修改儲存操作（上傳、刪除等）。
+- 🏢 **企業級設計** - 在 IoC 容器中自動註冊服務，並提供 Context 感知的中間件。
+- 🧪 **測試友善** - 包含 `MemoryStore`，用於快速、無副作用的單元測試。
+- 🚀 **現代化** - 專為 **Bun** 構建，原生支援 TypeScript。
+
+## 📦 安裝
 
 ```bash
 bun add @gravito/nebula
 ```
 
-## 快速開始
+## 🚀 快速上手
+
+### 1. 初始化與 PlanetCore 整合
 
 ```typescript
-import { PlanetCore } from '@gravito/core'
-import orbitStorage from '@gravito/nebula'
+import { PlanetCore } from '@gravito/core';
+import orbitStorage from '@gravito/nebula';
 
-const core = new PlanetCore()
+const core = new PlanetCore();
 
+// 使用選項快速安裝
 const storage = orbitStorage(core, {
-  local: {
-    root: './uploads',
-    baseUrl: '/uploads'
-  },
-  exposeAs: 'storage'
-})
+  default: 'local',
+  disks: {
+    local: {
+      driver: 'local',
+      root: './uploads',
+      baseUrl: '/uploads'
+    }
+  }
+});
+```
 
-core.app.post('/upload', async (c) => {
-  const body = await c.req.parseBody()
-  const file = body['file']
+### 2. 在路由中使用（中間件）
+
+Nebula 會自動將 `storage` 管理器注入請求上下文（Context）：
 
+```typescript
+core.app.post('/upload', async (c) => {
+  const body = await c.req.parseBody();
+  const file = body['file'];
+  
   if (file instanceof File) {
-    await storage.put(file.name, file)
-    return c.json({ url: storage.getUrl(file.name) })
+    const storage = c.get('storage'); // 從上下文中解析
+    await storage.put(`avatars/${file.name}`, file);
+    
+    return c.json({ 
+      success: true, 
+      url: storage.getUrl(`avatars/${file.name}`) 
+    });
+  }
+  
+  return c.text('No file uploaded', 400);
+});
+```
+
+## 🔧 多磁碟配置
+
+您可以定義多個磁碟並在運行時切換：
+
+```typescript
+const storage = orbitStorage(core, {
+  default: 'local',
+  disks: {
+    local: { driver: 'local', root: './uploads', baseUrl: '/uploads' },
+    temp: { driver: 'memory' },
+    s3: {
+      driver: 'custom',
+      store: new S3Store({ bucket: 'my-bucket' })
+    }
   }
-  return c.text('No file uploaded', 400)
-})
+});
+
+// 使用 'local' (預設)
+await storage.put('hello.txt', 'world');
+
+// 明確使用 's3' 磁碟
+await storage.disk('s3').put('backup.zip', data);
 ```
+
+## 📖 API 參考
+
+### `StorageManager`
+
+透過 `c.get('storage')` 存取或由 `orbitStorage()` 回傳的中央管理器。
+
+- **`disk(name?: string)`**: 存取特定的磁碟倉庫。
+- **`put(key, data)`**: 儲存內容（預設磁碟）。
+- **`get(key)`**: 取得內容為 `Blob`（預設磁碟）。
+- **`delete(key)`**: 刪除檔案（預設磁碟）。
+- **`exists(key)`**: 檢查檔案是否存在（預設磁碟）。
+- **`copy(from, to)`**: 複製檔案（預設磁碟）。
+- **`move(from, to)`**: 移動/重新命名檔案（預設磁碟）。
+- **`getUrl(key)`**: 取得公開 URL（預設磁碟）。
+- **`getSignedUrl(key, expires)`**: 取得臨時簽名 URL（預設磁碟）。
+- **`getMetadata(key)`**: 取得檔案元數據（大小、MIME 類型等）。
+- **`list(prefix?)`**: 列出檔案（異步叠代器）。
+
+### `StorageRepository`
+
+由 `storage.disk('name')` 回傳。實作與上述相同的儲存方法，但範圍限定於該特定磁碟。
+
+## 🪝 Hooks
+
+Nebula 在其生命週期中觸發各種 Hook：
+
+| Hook | 類型 | 上下文 | 描述 |
+|------|------|---------|-------------|
+| `storage:init` | Action | `{ manager }` | 初始化時觸發 |
+| `storage:upload` | Filter | `data, { key }` | 在儲存前修改資料 |
+| `storage:uploaded`| Action | `{ key }` | 儲存成功後觸發 |
+| `storage:hit` | Action | `{ key }` | 找到/取得檔案時觸發 |
+| `storage:miss` | Action | `{ key }` | 找不到檔案時觸發 |
+| `storage:deleted` | Action | `{ key }` | 檔案刪除後觸發 |
+
+### 範例：圖片縮放
+
+```typescript
+core.hooks.addFilter('storage:upload', async (data, context) => {
+  if (context.key.match(/\.(jpg|png)$/)) {
+    return await myImageProcessor.resize(data, 800);
+  }
+  return data;
+});
+```
+
+## 🔌 自定義驅動
+
+實作 `StorageStore` 介面來建立您自己的後端：
+
+```typescript
+import type { StorageStore, StorageMetadata } from '@gravito/nebula';
+
+class MyCustomStore implements StorageStore {
+  async put(key: string, data: Blob | Buffer | string): Promise<void> { /* ... */ }
+  async get(key: string): Promise<Blob | null> { /* ... */ }
+  async delete(key: string): Promise<boolean> { /* ... */ }
+  async exists(key: string): Promise<boolean> { /* ... */ }
+  getUrl(key: string): string { /* ... */ }
+  // ... 實作其他方法
+}
+```
+
+## 🔄 從 v3.x 遷移
+
+Nebula v4.0 引入了 **Manager** 模式以支援多磁碟。
+
+- **破壞性變更**：配置結構已移至 `disks` 屬性下。
+- **相容性**：舊的扁平配置格式仍然支援，但會觸發棄用警告。
+- **類型變更**：`StorageProvider` 現已更名為 `StorageStore`，`LocalStorageProvider` 更名為 `LocalStore`。
+
+## 🤝 貢獻
+
+歡迎提交貢獻、問題與功能請求！
+請隨時查看 [Issues 頁面](https://github.com/gravito-framework/gravito/issues)。
+
+## 📝 授權
+
+MIT © [Carl Lee](https://github.com/gravito-framework/gravito)