@gravito/dark-matter 1.0.0-beta.1 → 1.0.0

package/README.md

@@ -42,6 +42,10 @@ await Mongo.disconnect()
 - 🔍 **Query Builder** - Type-safe query building
 - 📊 **Aggregation Pipeline** - Fluent aggregation API
 - 🔌 **Multi-connection** - Named connections support
+- 🛡️ **Transactions** - ACID transactions with convenient API
+- 📦 **GridFS** - Handle large file uploads/downloads
+- ⚡ **Change Streams** - Real-time database event listening
+- ✅ **Schema Validation** - JSON Schema enforcement
 
 ## API Reference
 
@@ -111,6 +115,12 @@ await Mongo.collection('users')
 await Mongo.collection('users')
   .where('status', 'deleted')
   .deleteMany()
+
+// Bulk Write
+await Mongo.collection('logs').bulkWrite([
+  { insertOne: { document: { event: 'login' } } },
+  { deleteOne: { filter: { status: 'old' } } }
+])
 ```
 
 ### Aggregation Pipeline
@@ -140,42 +150,90 @@ const ordersWithCustomers = await Mongo.collection('orders')
   })
   .unwind('$customer')
   .get()
+```
 
-// Project specific fields
-const projected = await Mongo.collection('users')
-  .aggregate()
-  .project({
-    name: 1,
-    email: 1,
-    fullName: { $concat: ['$firstName', ' ', '$lastName'] }
-  })
-  .get()
+### Advanced Features
+
+#### Transactions
+
+```typescript
+await Mongo.connection().withTransaction(async (session) => {
+  // Deduct from sender
+  await session.collection('accounts')
+    .where('_id', senderId)
+    .update({ $inc: { balance: -100 } })
+
+  // Add to receiver
+  await session.collection('accounts')
+    .where('_id', receiverId)
+    .update({ $inc: { balance: 100 } })
+})
+```
+
+#### Change Streams
+
+```typescript
+const stream = Mongo.collection('orders').watch(
+  [{ $match: { 'fullDocument.amount': { $gt: 1000 } } }]
+)
+
+for await (const event of stream) {
+  console.log('High value order:', event.fullDocument)
+}
+```
+
+#### GridFS (File Storage)
+
+```typescript
+const grid = new MongoGridFS(Mongo.database())
+
+// Upload
+const fileId = await grid.upload(Buffer.from('Hello'), { filename: 'hello.txt' })
+
+// Download
+const content = await grid.download(fileId)
 ```
 
-### Multiple Connections
+#### Schema Validation
 
 ```typescript
+await Mongo.database().createCollection('users', {
+  schema: {
+    validator: {
+      $jsonSchema: {
+        required: ['username'],
+        properties: { username: { bsonType: 'string' } }
+      }
+    },
+    validationAction: 'error'
+  }
+})
+```
+
+### Connection Management
+
+```typescript
+// Configure multiple connections
 Mongo.configure({
   default: 'main',
   connections: {
-    main: { uri: 'mongodb://localhost:27017', database: 'app' },
-    analytics: { uri: 'mongodb://analytics.example.com:27017', database: 'analytics' }
+    main: { uri: 'mongodb://localhost:27017/app' },
+    analytics: { uri: 'mongodb://stats-db:27017/stats' }
   }
 })
 
-// Use specific connection
-const data = await Mongo.connection('analytics')
-  .collection('events')
-  .where('type', 'pageview')
-  .get()
+// Check health
+const health = await Mongo.connection().getHealthStatus()
+console.log(health.latencyMs) // e.g. 15
 ```
 
 ## Roadmap
 
-- [ ] Schema validation
-- [ ] Transactions
-- [ ] Change streams
-- [ ] GridFS support
+- [x] Connection retry & health check
+- [x] Transactions
+- [x] Schema validation
+- [x] Change streams
+- [x] GridFS support
 
 ## License
 

package/README.zh-TW.md

@@ -13,6 +13,7 @@ bun add @gravito/dark-matter mongodb
 ```typescript
 import { Mongo } from '@gravito/dark-matter'
 
+// 設定
 Mongo.configure({
   default: 'main',
   connections: {
@@ -20,13 +21,220 @@ Mongo.configure({
   }
 })
 
+// 連線
 await Mongo.connect()
 
+// 使用
 const users = await Mongo.collection('users')
   .where('status', 'active')
   .orderBy('createdAt', 'desc')
   .limit(10)
   .get()
 
+// 斷線
 await Mongo.disconnect()
 ```
+
+## 功能特色
+
+- 🚀 **Bun 原生** - 針對 Bun runtime 最佳化
+- 🎯 **Laravel 風格 API** - 熟悉且直觀的 Fluent Interface
+- 🔍 **Query Builder** - 類型安全的查詢建構器
+- 📊 **Aggregation Pipeline** - 流暢的聚合管道 API
+- 🔌 **多連線支援** - 支援多個具名資料庫連線
+- 🛡️ **Transactions** - 支援 ACID 交易與簡便的 API
+- 📦 **GridFS** - 支援大檔案上傳與下載
+- ⚡ **Change Streams** - 即時監聽資料庫變更事件
+- ✅ **Schema Validation** - JSON Schema 資料驗證支援
+
+## API 參考
+
+### 查詢建構器 (Query Builder)
+
+```typescript
+// 基本查詢
+const users = await Mongo.collection('users')
+  .where('status', 'active')
+  .where('age', '>', 18)
+  .whereIn('role', ['admin', 'editor'])
+  .get()
+
+// 排序與分頁
+const latest = await Mongo.collection('posts')
+  .orderBy('createdAt', 'desc')
+  .limit(10)
+  .skip(20)
+  .get()
+
+// 選擇特定欄位
+const names = await Mongo.collection('users')
+  .select('name', 'email')
+  .get()
+
+// 根據 ID 查詢
+const user = await Mongo.collection('users').find('507f1f77bcf86cd799439011')
+
+// 計數與存在檢查
+const count = await Mongo.collection('users').where('status', 'active').count()
+const exists = await Mongo.collection('users').where('email', 'john@example.com').exists()
+```
+
+### CRUD 操作
+
+```typescript
+// 新增
+const result = await Mongo.collection('users').insert({
+  name: 'John',
+  email: 'john@example.com',
+  createdAt: new Date()
+})
+console.log(result.insertedId)
+
+// 批次新增
+const results = await Mongo.collection('users').insertMany([
+  { name: 'Alice' },
+  { name: 'Bob' }
+])
+
+// 更新
+await Mongo.collection('users')
+  .where('_id', userId)
+  .update({ status: 'inactive' })
+
+// 批次更新
+await Mongo.collection('users')
+  .where('status', 'pending')
+  .updateMany({ status: 'active' })
+
+// 刪除
+await Mongo.collection('users')
+  .where('_id', userId)
+  .delete()
+
+// 批次刪除
+await Mongo.collection('users')
+  .where('status', 'deleted')
+  .deleteMany()
+
+// 批次寫入 (Bulk Write)
+await Mongo.collection('logs').bulkWrite([
+  { insertOne: { document: { event: 'login' } } },
+  { deleteOne: { filter: { status: 'old' } } }
+])
+```
+
+### 聚合管道 (Aggregation Pipeline)
+
+```typescript
+// 分組與統計
+const stats = await Mongo.collection('orders')
+  .aggregate()
+  .match({ status: 'completed' })
+  .group({
+    _id: '$customerId',
+    totalOrders: { $sum: 1 },
+    totalAmount: { $sum: '$amount' }
+  })
+  .sort({ totalAmount: 'desc' })
+  .limit(10)
+  .get()
+
+// 關聯查詢 (Lookup / JOIN)
+const ordersWithCustomers = await Mongo.collection('orders')
+  .aggregate()
+  .lookup({
+    from: 'customers',
+    localField: 'customerId',
+    foreignField: '_id',
+    as: 'customer'
+  })
+  .unwind('$customer')
+  .get()
+```
+
+### 進階功能
+
+#### 交易 (Transactions)
+
+```typescript
+await Mongo.connection().withTransaction(async (session) => {
+  // 從發送者扣款
+  await session.collection('accounts')
+    .where('_id', senderId)
+    .update({ $inc: { balance: -100 } })
+
+  // 增加到接收者
+  await session.collection('accounts')
+    .where('_id', receiverId)
+    .update({ $inc: { balance: 100 } })
+})
+```
+
+#### Change Streams (即時變更流)
+
+```typescript
+const stream = Mongo.collection('orders').watch(
+  [{ $match: { 'fullDocument.amount': { $gt: 1000 } } }]
+)
+
+for await (const event of stream) {
+  console.log('高額訂單:', event.fullDocument)
+}
+```
+
+#### GridFS (檔案儲存)
+
+```typescript
+const grid = new MongoGridFS(Mongo.database())
+
+// 上傳
+const fileId = await grid.upload(Buffer.from('Hello'), { filename: 'hello.txt' })
+
+// 下載
+const content = await grid.download(fileId)
+```
+
+#### Schema Validation (資料驗證)
+
+```typescript
+await Mongo.database().createCollection('users', {
+  schema: {
+    validator: {
+      $jsonSchema: {
+        required: ['username'],
+        properties: { username: { bsonType: 'string' } }
+      }
+    },
+    validationAction: 'error'
+  }
+})
+```
+
+### 連線管理
+
+```typescript
+// 設定多重連線
+Mongo.configure({
+  default: 'main',
+  connections: {
+    main: { uri: 'mongodb://localhost:27017/app' },
+    analytics: { uri: 'mongodb://stats-db:27017/stats' }
+  }
+})
+
+// 檢查連線健康狀態
+const health = await Mongo.connection().getHealthStatus()
+console.log(health.latencyMs) // 例如: 15
+```
+
+## 開發路線圖 (Roadmap)
+
+- [x] 連線重試與健康檢查
+- [x] 交易 (Transactions) 支援
+- [x] Schema Validation
+- [x] Change Streams
+- [x] GridFS 支援
+
+## 授權
+
+MIT