@gravito/stasis 3.0.1 → 3.1.1

package/README.md

@@ -1,86 +1,76 @@
-# @gravito/stasis
+# @gravito/stasis 🧊
 
-> The Standard Cache Orbit for Galaxy Architecture.
+> High-performance Cache and State Management Orbit for Gravito.
 
-Provides a Laravel-like cache layer with:
+`@gravito/stasis` wraps complex caching logic into an elegant and powerful API, ensuring your application handles high concurrency and massive datasets with ease.
 
-- `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`)
+---
 
-## 📦 Installation
+## 📖 Quick Index
+*   [**Architecture Deep Dive**](./docs/architecture.md) — Understand the mechanics of hybrid caching and predictive engines.
+*   [**Observability & Protection**](./docs/observability.md) — How to prevent OOM and monitor cache performance.
+
+---
+
+## 🌟 Core Capabilities
+*   🚀 **Unified API**: Seamlessly switch between Memory, Redis, File, and other storage drivers.
+*   🏗️ **Tiered Cache (Hybrid)**: Combine local Memory with distributed Redis for extreme read speeds.
+*   🔒 **Distributed Locks**: Atomic cross-instance concurrency control.
+*   🚦 **Rate Limiting**: Built-in traffic throttling on top of your cache infrastructure.
+*   🧠 **Smart Pre-warming**: Access path prediction and automated pre-fetching powered by Markov Chains.
 
+## 📦 Installation
 ```bash
 bun add @gravito/stasis
 ```
 
-## 🚀 Usage
+## 🚀 5-Minute Quick Start
 
+### 1. Configure 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 { defineConfig } from '@gravito/core'
+import { OrbitStasis } from '@gravito/stasis'
+
+export default defineConfig({
+  config: {
+    cache: {
+      default: 'tiered', // default to tiered caching
+      stores: {
+        local: { driver: 'memory', maxItems: 1000 },
+        remote: { driver: 'redis', connection: 'default' },
+        tiered: { driver: 'tiered', local: 'local', remote: 'remote' }
+      }
+    }
   },
-});
-
-// 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()]
+})
 ```
 
-### Tags (memory store)
+### 2. Basic Caching Example
+```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
+// 💡 Classic "Remember" pattern
+const news = await cache.remember('news:today', 3600, () => {
+  return await db.news.latest();
+});
 ```
 
-### Locks
+---
 
-```ts
-const cache = c.get('cache');
-await cache.lock('jobs:rebuild', 10).block(5, async () => {
-  // exclusive section
-});
-```
+## 🛠️ Drivers Overview
 
-## 🪝 Hooks
+| Driver Name | Tier | Best For |
+| :--- | :--- | :--- |
+| **Memory** | L1 | Local hotspots, LRU restricted |
+| **Redis** | L2 | Distributed sharing, Atomic locks |
+| **Tiered** | Hybrid | **Recommended**: Balance of speed and consistency |
+| **Predictive**| Smart | Scenarios with clear access patterns |
+| **File** | Persistent | Simple local persistence |
 
-- `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.
+---
 
-By default, hook events run in `async` mode and never block cache reads/writes. For debug, set:
+## 🤝 Contributing
+We welcome any optimization suggestions! Please see our [Contributing Guide](../../CONTRIBUTING.md).
 
-```ts
-orbitCache(core, { eventsMode: 'sync', throwOnEventError: true });
-```
+MIT © Carl Lee

package/README.zh-TW.md

@@ -1,38 +1,76 @@
-# @gravito/stasis
+# @gravito/stasis 🧊
 
-> Gravito 的快取 Orbit，提供類 Laravel 的 Cache API。
+> Gravito 的高效能快取與狀態管理 Orbit。
 
-## 安裝
+`@gravito/stasis` 將複雜的快取邏輯封裝成優雅且強大的 API，讓你的應用在處理高併發與海量數據時依然游刃有餘。
 
+---
+
+## 📖 快速索引
+*   [**技術架構深探**](./docs/architecture.zh-TW.md) — 了解混合式快取與預測機制的運作原理。
+*   [**可觀察性與資源保護**](./docs/observability.zh-TW.md) — 如何防止 OOM 並監控快取效能。
+
+---
+
+## 🌟 核心能力
+*   🚀 **統一 API**：無縫切換 Memory, Redis, File 等不同存儲驅動。
+*   🏗️ **混合快取 (Tiered)**：結合本地 Memory 與分散式 Redis，實現極限讀取速度。
+*   🔒 **分散式鎖**：基於原子操作的跨實例並發控制。
+*   🚦 **流量節流**：內建基於快取基礎設施的 Rate Limiting。
+*   🧠 **智慧預熱**：基於馬可夫鏈的存取路徑預測與自動讀取。
+
+## 📦 安裝
 ```bash
 bun add @gravito/stasis
 ```
 
-## 快速開始
+## 🚀 5 分鐘快速上手
 
+### 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 { defineConfig } from '@gravito/core'
+import { OrbitStasis } from '@gravito/stasis'
+
+export default defineConfig({
+  config: {
+    cache: {
+      default: 'tiered', // 預設使用分層快取
+      stores: {
+        local: { driver: 'memory', maxItems: 1000 },
+        remote: { driver: 'redis', connection: 'default' },
+        tiered: { driver: 'tiered', local: 'local', remote: 'remote' }
+      }
+    }
   },
+  orbits: [new OrbitStasis()]
 })
+```
 
-core.app.get('/heavy-data', async (c) => {
-  const data = await cache.remember('heavy_key', 300, async () => {
-    return { result: 42 }
-  })
+### 2. 資料存取範例
+```typescript
+const cache = core.container.make('cache');
 
-  return c.json(data)
-})
+// 💡 經典的「讀取或存儲」模式
+const news = await cache.remember('news:today', 3600, () => {
+  return await db.news.latest();
+});
 ```
+
+---
+
+## 🛠️ 驅動程式一覽
+
+| 驅動名稱 | 性質 | 適用場景 |
+| :--- | :--- | :--- |
+| **Memory** | L1 | 本地熱點、LRU 限制 |
+| **Redis** | L2 | 分散式共用、原子性鎖 |
+| **Tiered** | Hybrid | **推薦**：平衡效能與一致性 |
+| **Predictive**| Smart | 具有明顯路徑規律的存取場景 |
+| **File** | Persistent | 簡單的本地持久化 |
+
+---
+
+## 🤝 參與貢獻
+我們歡迎任何優化建議！請參閱 [貢獻指南](../../CONTRIBUTING.md)。
+
+MIT © Carl Lee