add aggregate

Author: rockyshi1993

README.md

@@ -6,6 +6,7 @@
 - [状态](#status)
 - [安装](#install)
 - [快速开始](#quick-start)
+- [聚合查询（aggregate）](#aggregate)
 - [深度分页（聚合版，Mongo）](#deep-pagination-agg)
 - [统一 findPage：游标 + 跳页 + offset + totals](#findpage-unified)
 - [返回耗时（meta）](#返回耗时meta)
@@ -76,6 +77,48 @@ const MonSQLize = require('monsqlize');
 })();
 ```
 
+<a id='aggregate'></a>
+## 聚合查询（aggregate）
+> 提示：可在构造时通过 defaults 配置 aggregateMaxTimeMS（默认 10s）。如需允许落盘，请在本次调用显式传入 allowDiskUse: true。
+`aggregate(options)`  支持以数组形式传入聚合管道，并在管道中使用 `$lookup` 等操作符进行联表查询。
+
+- 适用：复杂查询与报表，或需要联表的场景。
+- 缓存：仅当 `options.cache>0` 时启用；缓存键包含 `op=aggregate | pipelineHash`。
+- 透传（Mongo 专属）：支持在 options 里传 `hint`/`collation`，分别透传至 `aggregate` 的 `hint`/`collation`。
+> 兼容性提示：`aggregate hint` 需要较新的 MongoDB/Node 驱动版本（建议 MongoDB ≥ 4.2，Node 驱动 ≥ 5.x）。
+
+示例：
+```js
+const MonSQLize = require('monsqlize');
+const { collection } = await new MonSQLize({
+  type: 'mongodb',
+  databaseName: 'example',
+  config: { uri: 'mongodb://localhost:27017' },
+}).connect();
+
+const pipeline = [
+  {
+    $lookup: {
+      from: 'user',
+      let: { userId: { $toObjectId: '$userId' } },
+      pipeline: [ { $match: { $expr: { $eq: ['$_id','$$userId'] } } } ],
+      as: 'userInfo'
+    }
+  },
+  { $match: { status: 'paid' } },
+  { $sort: { createdAt: -1, _id: 1 } },
+  { $limit: 10 }
+];
+
+// 聚合查询
+const result = await collection('orders').aggregate(pipeline, {
+  cache: 3000,
+});
+console.log(result);
+```
+> 说明：当前 Mongo 适配器的 `aggregate` 基于原生驱动实现，未来跨数据库将复用该方法名，以各自最优实现（如 SQL Join）。
+
+
 <a id='deep-pagination-agg'></a>
 ## 深度分页（聚合版，Mongo）
 > 提示：可在构造时通过 defaults 配置 findPageMaxLimit（默认 500）。如需聚合允许落盘，请在本次调用显式传入 allowDiskUse: true；未来版本可能提供 cursorSecret 以增强游标防篡改。

STATUS.md

@@ -86,16 +86,18 @@
     - 支持 limit/skip 普通分页；未传 limit 使用全局 findLimit（默认 10）；limit=0 表示不限制。
 - ✅ 深分页（统一 findPage）
     - 游标 after/before + 跳页 page（书签 bm: + 少量 hops）+ offset 兜底（小范围 `$skip+$limit`）+ totals（none/async/approx/sync）。
-    - 稳定排序（默认补 `_id`）；页内 `$lookup` 支持；书签/总数键采用去敏“查询形状哈希”，复用实例 cache。
+    - 稳定排序（默认补 `_id`）；页内 `$lookup` 支持；书签/总数键采用去敏"查询形状哈希"，复用实例 cache。
     - totals 优化：异步 totals 返回短 token（keyHash），并启用 5s inflight 去重；失败语义统一（total:null）。
 - ☑️ 链表/聚合驱动分页
     - 方案A（先分页后联表）已支持；按联表字段排序/筛选的方案B（先联表后分页）计划中。
 - ✅ count
     - 统计匹配文档数；totals.sync/async 会透传 hint/collation/maxTimeMS。
+    - 性能优化：空查询自动使用 estimatedDocumentCount（基于元数据，速度快）；有查询条件使用 countDocuments（精确统计）。
 - ❌ stream（find 流式返回）
-    - 计划中。
-- ❌ 聚合（aggregate/或 find 支持聚合）
-    - 后续可能透传或翻译。
+    - 支持流式查询，适合处理大数据集；默认 batchSize=1000；支持 maxTimeMS/hint/collation/noCursorTimeout。
+    - 自动记录慢查询日志；触发 slow-query 和 query 事件；不支持缓存（流式特性）。
+- ✅ 聚合（aggregate）
+    - 支持 MongoDB 聚合管道透传；支持 maxTimeMS/allowDiskUse/hint/collation/comment；默认禁用缓存（cache=0）；可选返回 meta 耗时信息。
 - ❌ distinct
     - 仅 Mongo 适配器语义；尚未纳入抽象。
 - ❌ explain
@@ -105,8 +107,6 @@
 - ❌ 高级查询/游标选项统一抽象
     - batchSize/hint/collation/noCursorTimeout/tailable/max/min/returnKey/allowPartialResults/
       readPreference/readConcern。
-- ❌ showRecordId
-    - Mongo 专属选项。
 - ❌ comment / let
     - let 多见于聚合；待评估透传策略。
 - ❌ readPreferenceTags