mm_cost 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# mm_cost 耗时统计模块
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+按 name 维度统计操作耗时与次数：`begin/end` 手动打点，或 `wrap` 包装异步函数（异常也计入耗时）。数据保存在进程内存中，可通过 `snapshot()` 导出对接 mm_metrics 上报。
+
+## 快速开始
+
+```javascript
+const { costAdmin } = require('mm_cost');
+
+const cost = costAdmin('web');
+
+// 方式一：手动打点
+const end = cost.begin('db.query');
+const rows = await db.query(sql);
+end();
+
+// 方式二：包装异步函数
+const safe_call = cost.wrap('http.call', (url) => fetch(url));
+await safe_call('https://example.com');
+
+// 导出统计：{ name, count, avg, min, max, total }
+console.log(cost.snapshot());
+```
+
+## API
+
+| 方法 | 说明 |
+| --- | --- |
+| `begin(name)` | 开始打点，返回 `end()` 函数，调用即记录耗时 |
+| `wrap(name, fn)` | 包装异步函数，自动统计每次调用耗时 |
+| `snapshot()` | 导出 `{ name, count, avg, min, max, total }` 快照 |
+| `clear()` | 清空统计 |
+
+默认配置：`max_keys: 10000`（超限淘汰最久未更新的统计项）。
+
+`costAdmin(scope, config)` 按作用域缓存实例，相同 `scope` 返回同一实例。

package/index.js

@@ -0,0 +1,25 @@
+const { Cost } = require('./lib/cost.js');
+const Admin = require('mm_corejs').Admin;
+
+/**
+ * 耗时统计 Admin 工厂
+ * 支持 os.js 调用：require('mm_cost').admin.setServer(os) -> admin.get(scope, config)
+ */
+let admin = new Admin();
+admin.setClass(Cost);
+
+/**
+ * 获取（或创建）指定作用域的耗时统计实例
+ * @param {string} [scope] 作用域，缺省 'web'
+ * @param {Object} [config] 配置参数
+ * @returns {Cost} 耗时统计实例
+ */
+function costAdmin(scope, config) {
+  return admin.get(scope || 'web', config);
+}
+
+module.exports = {
+  Cost,
+  admin,
+  costAdmin
+};

package/lib/cost.js

@@ -0,0 +1,135 @@
+'use strict';
+
+const { Base } = require('mm_mod');
+
+/**
+ * 耗时统计类
+ *
+ * 按 name 维度统计操作耗时与次数：begin/end 手动打点，或 wrap 包装异步函数。
+ * 数据保存在进程内存中，可通过 snapshot 导出对接 mm_metrics 上报。
+ */
+class Cost extends Base {
+  /**
+   * 模块默认配置
+   */
+  static config = {
+    name: 'cost',
+    title: '耗时统计模块',
+    description: '按 name 维度统计操作耗时与次数：begin/end 打点或 wrap 包装',
+    // 最大跟踪 name 数，超出后淘汰最久未更新的统计项
+    max_keys: 10000
+  };
+
+  /**
+   * 统计表：name -> { count, total, min, max, _start(临时打点) }
+   * @type {Map<string, Object>}
+   */
+  #stats = new Map();
+
+  /**
+   * 获取（或创建）统计项
+   * @param {string} name 统计维度名称
+   * @returns {Object} 统计项
+   */
+  #item(name) {
+    let item = this.#stats.get(name);
+    if (!item) {
+      if (this.#stats.size >= this.config.max_keys) {
+        let oldest_key = null;
+        let oldest = Infinity;
+        for (const [k, v] of this.#stats) {
+          if (v.updated_at < oldest) {
+            oldest = v.updated_at;
+            oldest_key = k;
+          }
+        }
+        if (oldest_key !== null) {
+          this.#stats.delete(oldest_key);
+        }
+      }
+      item = { count: 0, total: 0, min: Infinity, max: 0, updated_at: Date.now() };
+      this.#stats.set(name, item);
+    }
+    return item;
+  }
+
+  /**
+   * 开始一次耗时打点
+   * @param {string} name 统计维度名称
+   * @returns {Function} end 函数：调用即结束打点并返回耗时毫秒
+   */
+  begin(name) {
+    if (!name || typeof name !== 'string') {
+      throw new TypeError(`${this._label()} name must be a non-empty string`);
+    }
+    const start = Date.now();
+    return () => this._end(name, Date.now() - start);
+  }
+
+  /**
+   * 结束一次打点（内部方法，通常通过 begin 返回的 end 函数调用）
+   * @param {string} name 统计维度名称
+   * @param {number} elapsed 耗时毫秒
+   * @returns {number} 耗时毫秒
+   */
+  _end(name, elapsed) {
+    const item = this.#item(name);
+    item.count += 1;
+    item.total += elapsed;
+    if (elapsed < item.min) {
+      item.min = elapsed;
+    }
+    if (elapsed > item.max) {
+      item.max = elapsed;
+    }
+    item.updated_at = Date.now();
+    return elapsed;
+  }
+
+  /**
+   * 包装异步函数：自动统计每次调用的耗时
+   * @param {string} name 统计维度名称
+   * @param {Function} fn 异步函数
+   * @returns {Function} 包装后的函数（透传参数与返回值，异常也计入耗时）
+   */
+  wrap(name, fn) {
+    return async (...args) => {
+      const end = this.begin(name);
+      try {
+        return await fn(...args);
+      } finally {
+        end();
+      }
+    };
+  }
+
+  /**
+   * 导出统计快照
+   * @returns {Array<Object>} 每项 { name, count, avg, min, max, total }
+   */
+  snapshot() {
+    const out = [];
+    for (const [name, item] of this.#stats) {
+      out.push({
+        name,
+        count: item.count,
+        total: item.total,
+        avg: item.count > 0 ? Math.round((item.total / item.count) * 100) / 100 : 0,
+        min: item.min === Infinity ? 0 : item.min,
+        max: item.max
+      });
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  /**
+   * 清空统计
+   * @returns {Cost} 当前实例
+   */
+  clear() {
+    this.#stats.clear();
+    return this;
+  }
+}
+
+module.exports = { Cost };

package/package.json

@@ -1,6 +1,27 @@
 {
-  "name": "mm_cost",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "mm_cost",
+    "version": "1.0.1",
+    "description": "超级美眉耗时统计模块：按 name 维度统计操作耗时与次数，begin/end 打点或 wrap 包装",
+    "main": "index.js",
+    "scripts": {
+        "test": "node test.js && node --test tests/cost.test.js"
+    },
+    "keywords": [
+        "mm_mod",
+        "mm_middleware",
+        "cost",
+        "timing",
+        "profiling"
+    ],
+    "layer": "middleware",
+    "group": "web",
+    "author": "邱文武",
+    "license": "MIT",
+    "dependencies": {
+        "mm_corejs": "^1.1.4",
+        "mm_mod": "^1.0.1"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    }
+}

package/test.js

@@ -0,0 +1,16 @@
+'use strict';
+const assert = require('assert');
+const mod = require('./index.js');
+
+assert.strictEqual(typeof mod.Cost, 'function', '应导出 Cost 类');
+assert.strictEqual(typeof mod.costAdmin, 'function', '应导出 costAdmin 函数');
+
+const c = mod.costAdmin('smoke');
+assert.ok(c instanceof mod.Cost);
+const end = c.begin('op');
+end();
+const snap = c.snapshot();
+assert.strictEqual(snap.length, 1);
+assert.strictEqual(snap[0].count, 1);
+
+console.log('mm_cost 模块测试通过');

package/tests/cost.test.js

@@ -0,0 +1,88 @@
+'use strict';
+/**
+ * mm_cost 单元测试
+ */
+const test = require('node:test');
+const assert = require('assert');
+
+const { Cost, costAdmin } = require('../index.js');
+
+test('begin/end 打点统计', async () => {
+  const c = new Cost();
+  const end = c.begin('db.query');
+  await new Promise((r) => setTimeout(r, 25));
+  const elapsed = end();
+  assert.ok(elapsed >= 20, `耗时应 >= 20ms，实际 ${elapsed}`);
+  const snap = c.snapshot();
+  assert.strictEqual(snap.length, 1);
+  const s = snap[0];
+  assert.strictEqual(s.name, 'db.query');
+  assert.strictEqual(s.count, 1);
+  assert.strictEqual(s.total, elapsed);
+  assert.strictEqual(s.min, elapsed);
+  assert.strictEqual(s.max, elapsed);
+  assert.ok(s.avg > 0);
+  assert.throws(() => c.begin(''), TypeError);
+});
+
+test('多次打点：count/avg/min/max 汇总', () => {
+  const c = new Cost();
+  c._end('op', 10);
+  c._end('op', 30);
+  c._end('op', 20);
+  const s = c.snapshot()[0];
+  assert.strictEqual(s.count, 3);
+  assert.strictEqual(s.total, 60);
+  assert.strictEqual(s.min, 10);
+  assert.strictEqual(s.max, 30);
+  assert.strictEqual(s.avg, 20);
+});
+
+test('wrap 包装异步函数：成功与异常均计入', async () => {
+  const c = new Cost();
+  const fn = c.wrap('job', async (x) => x * 2);
+  assert.strictEqual(await fn(21), 42);
+  const bad = c.wrap('bad', async () => { throw new Error('x'); });
+  await assert.rejects(() => bad(), /x/);
+  const snap = Object.fromEntries(c.snapshot().map((s) => [s.name, s]));
+  assert.strictEqual(snap.job.count, 1, '成功调用应计入');
+  assert.strictEqual(snap.bad.count, 1, '异常调用也应计入');
+  // 透传参数与返回值
+  assert.strictEqual(await fn(5), 10);
+  assert.strictEqual(c.snapshot().find((s) => s.name === 'job').count, 2);
+});
+
+test('不同 name 独立统计，快照按名称排序', () => {
+  const c = new Cost();
+  c._end('c', 1);
+  c._end('a', 2);
+  c._end('b', 3);
+  assert.deepStrictEqual(c.snapshot().map((s) => s.name), ['a', 'b', 'c']);
+});
+
+test('clear 与 max_keys 淘汰', async () => {
+  const c = new Cost();
+  c._end('x', 1);
+  c.clear();
+  assert.strictEqual(c.snapshot().length, 0);
+
+  const limited = new Cost({ max_keys: 2 });
+  const tick = () => new Promise((r) => setTimeout(r, 3));
+  limited._end('k1', 1);
+  await tick();
+  limited._end('k2', 1);
+  await tick();
+  limited._end('k1', 1); // k1 变为最近使用
+  await tick();
+  limited._end('k3', 1); // 淘汰 k2
+  const names = limited.snapshot().map((s) => s.name);
+  assert.ok(!names.includes('k2'), 'k2 应被淘汰');
+  assert.ok(names.includes('k1') && names.includes('k3'));
+});
+
+test('工厂函数按作用域共享实例', () => {
+  const a = costAdmin('ut-cost', {});
+  const b = costAdmin('ut-cost');
+  assert.strictEqual(a, b);
+  assert.notStrictEqual(costAdmin('ut-cost-2'), a);
+});