@gravito/stasis 3.0.1 → 3.1.0

package/README.md

@@ -1,13 +1,18 @@
-# @gravito/stasis
+# @gravito/stasis 🧊
 
-> The Standard Cache Orbit for Galaxy Architecture.
+> High-performance caching and rate-limiting Orbit for Gravito.
 
-Provides a Laravel-like cache layer with:
+`@gravito/stasis` provides a robust, developer-friendly caching layer for the Gravito framework. Inspired by Laravel's cache system, it offers a unified API for multiple storage backends, distributed locking, and integrated rate limiting.
 
-- `CacheManager` + `CacheRepository` API (`get/put/add/remember/forever/increment/decrement/pull`)
-- Multiple stores (`memory`, `file`, `null`, `custom`)
-- Tags (memory store) and Locks (`lock().block()`)
-- Hook events (`cache:hit`, `cache:miss`, `cache:write`, `cache:forget`, `cache:flush`, `cache:init`)
+## 🌟 Key Features
+
+- **🚀 Unified Cache API**: Simple `get`, `put`, `remember`, and `forever` methods across all drivers.
+- **💾 Multiple Storage Drivers**: Native support for Memory, Redis, File-based, and Null storage.
+- **🔒 Distributed Locks**: Prevent race conditions with atomic, cross-process locks.
+- **⚡ Flexible Caching (SWR)**: Stale-While-Revalidate support to serve data fast while refreshing in the background.
+- **🚦 Integrated Rate Limiting**: Throttling mechanism built directly on top of your cache infrastructure.
+- **🏷️ Cache Tagging**: Group related items for bulk invalidation (supported in Memory driver).
+- **🪝 Hook System**: Lifecycle events for monitoring cache hits, misses, and writes.
 
 ## 📦 Installation
 
@@ -15,72 +20,96 @@ Provides a Laravel-like cache layer with:
 bun add @gravito/stasis
 ```
 
-## 🚀 Usage
+## 🚀 Quick Start
+
+### 1. Register the Orbit
 
 ```typescript
-import { PlanetCore } from '@gravito/core';
-import orbitCache from '@gravito/stasis';
-
-const core = new PlanetCore();
-
-// Initialize Cache Orbit (Laravel-like config)
-const cache = orbitCache(core, {
-  exposeAs: 'cache',
-  default: 'memory',
-  prefix: 'app_cache:',
-  defaultTtl: 60, // seconds
-  // Low-overhead hook dispatch (default: 'async')
-  // Use 'sync' + throwOnEventError for development/debug.
-  eventsMode: 'async',
-  stores: {
-    memory: { driver: 'memory', maxItems: 10_000 },
-    file: { driver: 'file', directory: './tmp/cache' },
-    null: { driver: 'null' },
+import { PlanetCore, defineConfig } from '@gravito/core'
+import { OrbitStasis } from '@gravito/stasis'
+
+const config = defineConfig({
+  config: {
+    cache: {
+      default: 'memory',
+      stores: {
+        memory: { driver: 'memory', maxItems: 5000 },
+        redis: { driver: 'redis', connection: 'default' }
+      }
+    }
   },
-});
-
-// Use in routes
-core.app.get('/heavy-data', async (c) => {
-  // Either use the manager returned from orbitCache(...) or request-scoped access:
-  // const cache = c.get('cache');
-
-  const data = await cache.remember('heavy_key', 300, async () => {
-    // Expensive computation...
-    return { result: 42 };
-  });
-  
-  return c.json(data);
-});
+  orbits: [new OrbitStasis()]
+})
+
+const core = await PlanetCore.boot(config)
 ```
 
-### Tags (memory store)
+### 2. Basic Caching
+
+```typescript
+const cache = core.container.make('cache')
 
-```ts
-const cache = c.get('cache');
-await cache.tags(['users']).set('user:1', { id: 1 }, 60);
-await cache.tags(['users']).clear(); // flush only tagged keys
+// Simple storage
+await cache.put('stats:total', 100, 3600) // Store for 1 hour
+
+// "Remember" pattern (Get or Set)
+const users = await cache.remember('users:all', 300, async () => {
+  return await db.users.findMany()
+})
 ```
 
-### Locks
+### 3. Distributed Locking
 
-```ts
-const cache = c.get('cache');
-await cache.lock('jobs:rebuild', 10).block(5, async () => {
-  // exclusive section
-});
+```typescript
+const lock = cache.lock('process-invoice:123', 10)
+
+if (await lock.get()) {
+  try {
+    // Perform critical task...
+  } finally {
+    await lock.release()
+  }
+}
 ```
 
-## 🪝 Hooks
+## 🚦 Rate Limiting
 
-- `cache:miss` - Fired when data is not found in cache.
-- `cache:hit` - Fired when data is retrieved from cache.
-- `cache:write` - Fired when writing cache.
-- `cache:forget` - Fired when forgetting cache.
-- `cache:flush` - Fired when flushing cache.
-- `cache:init` - Fired when the orbit is installed.
+Easily throttle requests or actions using your cache backend.
+
+```typescript
+const limiter = cache.limiter()
 
-By default, hook events run in `async` mode and never block cache reads/writes. For debug, set:
+if (await limiter.tooManyAttempts('login:127.0.0.1', 5)) {
+  const seconds = await limiter.availableIn('login:127.0.0.1')
+  throw new Error(`Too many attempts. Try again in ${seconds}s.`)
+}
 
-```ts
-orbitCache(core, { eventsMode: 'sync', throwOnEventError: true });
+await limiter.hit('login:127.0.0.1', 60) // Decay in 60s
 ```
+
+## 🛠️ Supported Drivers
+
+| Driver | Best For | Features |
+|---|---|---|
+| **Memory** | Local dev & Small apps | Fast, Tags, LRU |
+| **Redis** | Distributed production | Multi-node, Locks, Persistent |
+| **File** | Simple persistence | No external deps |
+| **Null** | Testing / Disabling cache | No-op |
+
+## 🧩 API Reference
+
+### `CacheManager`
+- `cache.get(key, default?)`: Retrieve an item.
+- `cache.put(key, value, ttl?)`: Store an item.
+- `cache.remember(key, ttl, callback)`: Get or execute callback and store.
+- `cache.flexible(key, ttl, stale, callback)`: Stale-While-Revalidate.
+- `cache.increment / decrement`: Atomic numeric updates.
+- `cache.tags(['tag1']).flush()`: Invalidate by tag.
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for details.
+
+## 📄 License
+
+MIT © Carl Lee

package/README.zh-TW.md

@@ -1,38 +1,115 @@
-# @gravito/stasis
+# @gravito/stasis 🧊
 
-> Gravito 的快取 Orbit，提供類 Laravel 的 Cache API。
+> 高效能快取與速率限制 (Rate Limiting) Orbit，專為 Gravito 設計。
 
-## 安裝
+`@gravito/stasis` 為 Gravito 框架提供了一個強大且開發者友善的快取層。受 Laravel 快取系統啟發，它為多種存儲後端、分佈式鎖定以及整合式速率限制提供了統一的 API。
+
+## 🌟 核心特性
+
+- **🚀 統一快取 API**：在所有驅動程式中提供簡潔的 `get`、`put`、`remember` 與 `forever` 方法。
+- **💾 多種存儲驅動**：原生支援 Memory、Redis、檔案 (File) 以及 Null 存儲。
+- **🔒 分佈式鎖 (Distributed Locks)**：透過原子性的跨進程鎖定防止競態條件 (Race Conditions)。
+- **⚡ 彈性快取 (SWR)**：支援 Stale-While-Revalidate 模式，在背景更新數據的同時快速響應請求。
+- **🚦 整合式速率限制**：直接在快取基礎設施上構建的流量節流機制。
+- **🏷️ 快取標籤 (Tagging)**：支援將相關項目分組，以便進行批量刪除（Memory 驅動支援）。
+- **🪝 Hook 系統**：提供生命週期事件，用於監控快取命中 (Hit)、未命中 (Miss) 與寫入。
+
+## 📦 安裝
 
 ```bash
 bun add @gravito/stasis
 ```
 
-## 快速開始
+## 🚀 快速上手
+
+### 1. 註冊 Orbit
 
 ```typescript
-import { PlanetCore } from '@gravito/core'
-import orbitCache from '@gravito/stasis'
-
-const core = new PlanetCore()
-
-const cache = orbitCache(core, {
-  exposeAs: 'cache',
-  default: 'memory',
-  prefix: 'app_cache:',
-  defaultTtl: 60,
-  stores: {
-    memory: { driver: 'memory', maxItems: 10_000 },
-    file: { driver: 'file', directory: './tmp/cache' },
-    null: { driver: 'null' },
+import { PlanetCore, defineConfig } from '@gravito/core'
+import { OrbitStasis } from '@gravito/stasis'
+
+const config = defineConfig({
+  config: {
+    cache: {
+      default: 'memory',
+      stores: {
+        memory: { driver: 'memory', maxItems: 5000 },
+        redis: { driver: 'redis', connection: 'default' }
+      }
+    }
   },
+  orbits: [new OrbitStasis()]
 })
 
-core.app.get('/heavy-data', async (c) => {
-  const data = await cache.remember('heavy_key', 300, async () => {
-    return { result: 42 }
-  })
+const core = await PlanetCore.boot(config)
+```
+
+### 2. 基礎快取操作
 
-  return c.json(data)
+```typescript
+const cache = core.container.make('cache')
+
+// 簡單存儲
+await cache.put('stats:total', 100, 3600) // 存儲 1 小時
+
+// "Remember" 模式 (讀取或設置)
+const users = await cache.remember('users:all', 300, async () => {
+  return await db.users.findMany()
 })
 ```
+
+### 3. 分佈式鎖定
+
+```typescript
+const lock = cache.lock('process-invoice:123', 10)
+
+if (await lock.get()) {
+  try {
+    // 執行關鍵任務...
+  } finally {
+    await lock.release()
+  }
+}
+```
+
+## 🚦 速率限制 (Rate Limiting)
+
+輕鬆地使用您的快取後端來限制請求或操作的頻率。
+
+```typescript
+const limiter = cache.limiter()
+
+if (await limiter.tooManyAttempts('login:127.0.0.1', 5)) {
+  const seconds = await limiter.availableIn('login:127.0.0.1')
+  throw new Error(`嘗試次數過多。請在 ${seconds} 秒後重試。`)
+}
+
+await limiter.hit('login:127.0.0.1', 60) // 60 秒後衰減
+```
+
+## 🛠️ 支援的驅動程式 (Drivers)
+
+| 驅動名稱 | 適用場景 | 核心功能 |
+|---|---|---|
+| **Memory** | 本地開發與小型應用 | 極速、標籤支援、LRU |
+| **Redis** | 分佈式生產環境 | 多節點共享、鎖定、持久化 |
+| **File** | 簡單的持久化需求 | 無外部依賴 |
+| **Null** | 測試或停用快取 | 不執行任何操作 |
+
+## 🧩 API 參考
+
+### `CacheManager`
+- `cache.get(key, default?)`：讀取項目。
+- `cache.put(key, value, ttl?)`：存儲項目。
+- `cache.remember(key, ttl, callback)`：讀取或執行回調並存儲。
+- `cache.flexible(key, ttl, stale, callback)`：Stale-While-Revalidate 模式。
+- `cache.increment / decrement`：原子性的數值更新。
+- `cache.tags(['tag1']).flush()`：按標籤清除快取。
+
+## 🤝 參與貢獻
+
+我們歡迎任何形式的貢獻！詳細資訊請參閱 [貢獻指南](../../CONTRIBUTING.md)。
+
+## 📄 開源授權
+
+MIT © Carl Lee