mm_container 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# mm_container
 
-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.
+容器模块。提供只允许存放实例对象的容器，按作用域缓存容器实例，用于在模块间共享对象（如 logger、服务实例、缓存数据）。
+
+## 项目信息
+
+- **当前版本**: 1.0.0
+- **依赖**: mm_corejs（Admin 实例管理）
+- **运行环境**: Node.js（使用私有字段 `#map`，需 Node.js 12+）
+- **Gitee地址**: https://gitee.com/qiuwenwu91/mm_container
+
+## 特点
+
+- 容器内部用私有 `Map` 存储键值，不对外暴露 Map，避免绕过类型校验写入
+- 只允许存入实例对象（数组、日期、普通对象、class 实例等），拒绝函数、class 本身、基础值及 `null`/`undefined`
+- 校验在写入前执行，非法值不会写入，也不会覆盖同名键的旧值
+- 提供语义化方法 `set` / `get` / `has` / `del` / `clear` / `list`，`set`、`clear` 支持链式调用
+- 保留容器配置 `config` 与服务器实例 `server`
+- `containerAdmin(scope, config?)` 按作用域返回容器，同一作用域始终是同一个实例
+
+## 安装
+
+```bash
+npm install mm_container
+```
+
+## 基本使用
+
+```javascript
+const { Container, containerAdmin } = require('mm_container');
+
+// 1. 直接创建容器，可传入配置与服务器实例
+const container = new Container({ name: 'demo' }, { tag: 'server' });
+
+// 2. 存取实例对象
+const logger = { level: 'info' };
+container.set('logger', logger);
+console.log(container.get('logger') === logger); // true
+console.log(container.has('logger'));            // true
+console.log(container.size);                     // 1
+console.log(container.list());                   // [ { level: 'info' } ]
+
+// 3. 链式调用
+container.set('user', { id: 1 }).set('cache', { ttl: 60 });
+
+// 4. 删除与清空
+container.del('user');   // true
+container.clear();       // 返回容器自身
+console.log(container.size); // 0
+
+// 5. 类型限制：函数、class、基础值都会被拒绝
+try {
+  container.set('fn', () => {});
+} catch (e) {
+  console.log(e.message); // 容器只能存储实例对象
+}
+```
+
+按作用域共享容器：
+
+```javascript
+const { containerAdmin } = require('mm_container');
+
+// 不传作用域时使用默认作用域 'os'
+const os_container = containerAdmin();
+os_container.set('logger', { level: 'info' });
+
+// 同一作用域返回同一实例，配置仅在首次创建时生效
+const same = containerAdmin('os', { debug: true });
+console.log(same === os_container);   // true
+console.log(same.config);             // { name: 'os' }
+
+// 指定作用域，配置中会自动补充 name
+const cache_container = containerAdmin('cache', { ttl: 60 });
+console.log(cache_container.config);  // { ttl: 60, name: 'cache' }
+console.log(cache_container === os_container); // false
+```
+
+## API 说明
+
+### 入口（index.js）
+
+| 导出 | 签名 | 返回值 | 说明 |
+| --- | --- | --- | --- |
+| Container | `Container` | `Class` | 容器类，见下文 |
+| admin | `admin` | `Admin` | mm_corejs 的实例管理器，已绑定 `Container` |
+| containerAdmin | `containerAdmin(scope?, config?)` | `Container` | 获取指定作用域的容器实例，`scope` 为空时使用默认作用域 `'os'`。实例按作用域缓存，**配置仅在首次创建时生效**，`config.name` 始终等于作用域名 |
+
+> 需要跨模块共享同一个容器时，统一使用 `containerAdmin('作用域名')`，避免各自 `new Container()` 造成数据不互通。
+
+### 构造函数
+
+```javascript
+const container = new Container(config?, server?);
+```
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| config | `Object` | `{}` | 容器配置，原样保存在 `container.config` |
+| server | `Object` | `undefined` | 服务器实例，保存在 `container.server` |
+
+### 属性
+
+| 属性 | 类型 | 说明 |
+| --- | --- | --- |
+| config | `Object` | 容器配置 |
+| server | `Object \| undefined` | 服务器实例 |
+| size | `number` | 只读，当前键值数量 |
+
+### 方法
+
+| 方法 | 签名 | 返回值 | 说明 |
+| --- | --- | --- | --- |
+| set | `set(key, value)` | `Container` | 存入实例对象，返回容器自身便于链式调用；`value` 不是实例对象时抛错 |
+| get | `get(key)` | `*` | 获取键值，不存在时返回 `undefined` |
+| has | `has(key)` | `boolean` | 判断键是否存在 |
+| del | `del(key)` | `boolean` | 删除键值，删除成功返回 `true`，键不存在返回 `false` |
+| clear | `clear()` | `Container` | 清空容器，返回容器自身 |
+| list | `list()` | `Array` | 按插入顺序返回全部键值 |
+
+- 键名 `key` 不限制类型，与 `Map` 的键规则一致
+- 同名键再次 `set` 会覆盖旧值
+
+## 类型限制
+
+`set` 写入前会校验 `value`，仅 `typeof value === 'object' && value !== null` 的值可以存入。
+
+| 值 | 是否允许 | 说明 |
+| --- | --- | --- |
+| `{}`、`new Date()`、`[1, 2]` | 允许 | 实例对象 |
+| class 的实例（如 `new Logger()`） | 允许 | 实例对象 |
+| 函数（含箭头函数、async 函数） | 拒绝 | 抛 `Error('容器只能存储实例对象')` |
+| class 本身（如 `Container`） | 拒绝 | class 的本质是函数 |
+| `number`、`string`、`boolean`、`bigint`、`symbol` | 拒绝 | 基础值 |
+| `null`、`undefined` | 拒绝 | 不属于对象 |
+
+> 校验失败时不会写入数据，同名键的旧值与 `size` 保持不变。
+
+## 示例
+
+仓库内提供可运行示例：
+
+```bash
+npm run demo
+```
+
+示例代码见 `example/demo.js`，会依次演示基础寄存取、链式调用、删除清空、类型限制（函数 / class / 数字 / 字符串 / null）以及按作用域共享容器。
+
+## 测试
+
+```bash
+npm test
+```
+
+使用 jest 运行，覆盖构造、全部容器方法、类型限制、作用域缓存与默认作用域等场景。覆盖率阈值为 100%（语句、分支、函数、行），当前 37 个用例全部通过。
+
+## 更新日志
+
+### 1.0.0
+
+- 提供 `Container`、`admin`、`containerAdmin` 三个导出
+- 容器内部使用私有 `Map` 存储，提供 `set` / `get` / `has` / `del` / `clear` / `list` 及 `size`
+- 限制容器只能存储实例对象，拒绝函数、class 与基础值
+- 新增测试与示例，测试覆盖率 100%

package/example/demo.js

@@ -0,0 +1,74 @@
+'use strict';
+
+const { Container, containerAdmin } = require('../index');
+
+/**
+ * 演示容器只接收实例对象，拒绝函数、class 与基础值
+ * @param {Container} container 容器实例
+ */
+function showTypeLimit(container) {
+  console.log('=== 类型限制 ===');
+  console.log('  存入函数: ' + getRejectMessage(container, 'fn', () => {}));
+  console.log('  存入 class: ' + getRejectMessage(container, 'cls', Container));
+  console.log('  存入数字: ' + getRejectMessage(container, 'num', 1));
+  console.log('  存入字符串: ' + getRejectMessage(container, 'str', 'text'));
+  console.log('  存入 null: ' + getRejectMessage(container, 'nil', null));
+}
+
+/**
+ * 获取容器拒绝值时的错误信息
+ * @param {Container} container 容器实例
+ * @param {string} key 键名
+ * @param {*} value 待存入的值
+ * @returns {string} 错误信息，未被拒绝时返回“未拒绝”
+ */
+function getRejectMessage(container, key, value) {
+  try {
+    container.set(key, value);
+    return '未拒绝';
+  } catch (e) {
+    return e.message;
+  }
+}
+
+/**
+ * 使用示例：演示 Container 的键值存取、类型限制与 containerAdmin 的作用域管理
+ */
+function runDemo() {
+  const container = new Container({ name: 'demo' }, { tag: 'server' });
+
+  console.log('=== 基础容器 ===');
+  console.log('  配置: ' + JSON.stringify(container.config));
+  console.log('  服务器: ' + JSON.stringify(container.server));
+
+  const item_a = { id: 1 };
+  const item_b = { id: 2 };
+  container.set('a', item_a).set('b', item_b);
+  console.log('  set 后 size: ' + container.size);
+  console.log('  get a: ' + JSON.stringify(container.get('a')));
+  console.log('  has b: ' + container.has('b'));
+  console.log('  list: ' + JSON.stringify(container.list()));
+
+  console.log('  del a: ' + container.del('a'));
+  console.log('  has a: ' + container.has('a'));
+
+  showTypeLimit(container);
+
+  container.clear();
+  console.log('  clear 后 size: ' + container.size);
+
+  console.log('=== 作用域容器 ===');
+  const os_container = containerAdmin();
+  os_container.set('logger', { level: 'info' });
+  console.log('  os 容器配置: ' + JSON.stringify(os_container.config));
+  console.log('  os 容器内容: ' + JSON.stringify(os_container.list()));
+  console.log('  同一作用域返回同一实例: ' + (containerAdmin('os') === os_container));
+
+  const cache_container = containerAdmin('cache', { ttl: 60 });
+  cache_container.set('user:1', { name: '张三' });
+  console.log('  cache 容器配置: ' + JSON.stringify(cache_container.config));
+  console.log('  cache 容器内容: ' + JSON.stringify(cache_container.list()));
+  console.log('  不同作用域为不同实例: ' + (cache_container !== os_container));
+}
+
+runDemo();

package/index.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const Container = require('./lib/container');
+const { Admin } = require('mm_corejs');
+
+const admin = new Admin();
+admin.setClass(Container);
+
+/**
+ * 获取容器管理器
+ * 未指定作用域时使用默认作用域；同一作用域返回同一个容器实例。
+ * @param {string} scope 作用域名称
+ * @param {Object} config 容器配置
+ * @returns {Container} 容器实例
+ */
+function containerAdmin(scope, config) {
+  if (!scope) {
+    scope = 'os';
+  }
+  return admin.get(scope, config);
+}
+
+module.exports = {
+  Container,
+  admin,
+  containerAdmin
+};

package/lib/container.js

@@ -0,0 +1,107 @@
+/**
+ * 判断是否为实例对象
+ * 数组、日期等对象均属于实例对象；函数、class、基础值均不属于实例对象。
+ * @param {*} value 待判断的值
+ * @returns {boolean} 是否为实例对象
+ */
+function _isInstanceObject(value) {
+  return typeof value === 'object' && value !== null;
+}
+
+/**
+ * 校验容器存储的值
+ * @param {*} value 待校验的值
+ * @throws {Error} 值不是实例对象时抛错
+ */
+function _checkValue(value) {
+  if (!_isInstanceObject(value)) {
+    throw new Error('容器只能存储实例对象');
+  }
+}
+
+/**
+ * 容器类
+ * 内部使用私有 Map 存储键值，提供语义化的存取方法，并保存容器配置与服务器实例。
+ * 容器只允许存储实例对象，不允许存储函数、class 和基础值。
+ */
+class Container {
+  #map;
+
+  /**
+   * 构造函数
+   * @param {Object} config 容器配置
+   * @param {Object} server 服务器实例
+   */
+  constructor(config = {}, server) {
+    this.#map = new Map();
+    this.config = config;
+    this.server = server;
+  }
+
+  /**
+   * 获取键值数量
+   * @returns {number} 键值数量
+   */
+  get size() {
+    return this.#map.size;
+  }
+
+  /**
+   * 设置键值
+   * @param {*} key 键名
+   * @param {Object} value 键值，必须是实例对象
+   * @returns {Container} 容器自身，便于链式调用
+   * @throws {Error} 值不是实例对象时抛错
+   */
+  set(key, value) {
+    _checkValue(value);
+    this.#map.set(key, value);
+    return this;
+  }
+
+  /**
+   * 获取键值
+   * @param {*} key 键名
+   * @returns {*} 键值，不存在时返回 undefined
+   */
+  get(key) {
+    return this.#map.get(key);
+  }
+
+  /**
+   * 判断键是否存在
+   * @param {*} key 键名
+   * @returns {boolean} 是否存在
+   */
+  has(key) {
+    return this.#map.has(key);
+  }
+
+  /**
+   * 删除键值
+   * @param {*} key 键名
+   * @returns {boolean} 是否删除成功
+   */
+  del(key) {
+    return this.#map.delete(key);
+  }
+
+  /**
+   * 清空容器
+   * @returns {Container} 容器自身，便于链式调用
+   */
+  clear() {
+    this.#map.clear();
+    return this;
+  }
+
+  /**
+   * 列出全部键值
+   * @returns {Array} 键值数组
+   */
+  list() {
+    return Array.from(this.#map.values());
+  }
+}
+
+module.exports = Container;

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "mm_container",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "容器工具，基于 Map 提供语义化的键值存取（set/get/has/del/clear/list），并保存容器配置与服务器实例。",
+  "keywords": [
+    "mm_mod",
+    "mm_infra",
+    "mm_common",
+    "超级美眉",
+    "容器",
+    "键值存储",
+    "container"
+  ],
+  "layer": "infra",
+  "group": "common",
+  "author": "邱文武",
+  "license": "ISC",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "lib",
+    "example"
+  ],
+  "directories": {
+    "example": "example",
+    "lib": "lib"
+  },
+  "scripts": {
+    "test": "jest --coverage",
+    "demo": "node example/demo.js",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": {
+    "mm_corejs": "^1.1.5"
+  },
+  "devDependencies": {
+    "jest": "^30.5.2"
+  }
+}