mm_store 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 qww
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,195 @@
-# Temporary Holding Version
+# 存储管理器（mm_store）
 
-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.
+## 说明
+mm_store 是基于内存列表的存储类，提供统一的增删改查（CRUD）、分页、关键词搜索与排序能力。
+通过配置主键、名称字段、分页大小、过滤参数名与模糊匹配，可快速搭建内存数据管理。
+
+## 功能特点
+
+- 支持增删改查：`add` / `del` / `delById` / `delByName` / `set` / `setById` / `setByName`
+- 支持精确与模糊（like）查询匹配
+- 支持分页与关键词搜索
+- 支持按字段排序
+- 支持清空与整体设置列表
+- 支持自定义主键、名称字段、分页大小等配置
+- 基于 mm_corejs 的 Admin 管理器，支持按作用域缓存实例
+
+## 安装
+
+```bash
+npm install mm_store
+```
+
+## 快速开始
+
+```javascript
+const { Store, storeAdmin } = require('mm_store');
+
+// 直接使用存储类
+const store = new Store();
+store.add({ id: 1, name: '苹果', type: 'fruit' });
+store.add({ id: 2, name: '香蕉', type: 'fruit' });
+console.log(store.list({ type: 'fruit' }));
+
+// 通过管理器按作用域获取实例（相同作用域返回同一实例）
+const scoped = storeAdmin('app');
+scoped.add({ id: 1, name: '配置项' });
+```
+
+## API
+
+### 类方法
+
+| 方法 | 说明 | 参数 | 返回值 |
+|---|---|---|---|
+| add | 添加数据项 | item | void |
+| del | 按查询条件删除 | query, all | boolean |
+| delById | 按主键删除 | id, all | boolean |
+| delByName | 按名称删除 | name, all | boolean |
+| set | 按查询条件更新 | query, item, all | boolean |
+| setById | 按主键更新 | id, item, all | boolean |
+| setByName | 按名称更新 | name, item, all | boolean |
+| get | 按查询条件获取单项 | query | object |
+| getById | 按主键获取 | id | object |
+| getByName | 按名称获取 | name | object |
+| list | 获取列表，支持分页与关键词 | query | Array |
+| count | 获取匹配数量 | query | number |
+| clear | 清空列表 | - | void |
+| setList | 整体设置列表 | list | void |
+| sort | 按字段排序 | field, order | void |
+
+### 工厂函数
+
+| 函数 | 说明 | 参数 | 返回值 |
+|---|---|---|---|
+| storeAdmin | 获取指定作用域的存储实例，不存在时创建 | scope, config | Store |
+| getStore | 获取 os 作用域的存储实例 | - | Store |
+
+## 配置项
+
+| 配置 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| key | string | 'id' | 主键字段 |
+| name | string | 'name' | 名称字段 |
+| size | number | 10 | 默认分页大小 |
+| filter.page_now | string | 'page_now' | 分页页码参数名 |
+| filter.page_size | string | 'page_size' | 分页大小参数名 |
+| filter.orderby | string | 'orderby' | 排序字段参数名 |
+| filter.groupby | string | 'groupby' | 分组字段参数名 |
+| filter.keyword | string | 'keyword' | 搜索关键词参数名 |
+| keyword | string[] | ['name', 'title', 'description'] | 关键词搜索字段 |
+| like | boolean | false | 是否启用模糊匹配 |
+
+## 使用示例
+
+### 1. 基本增删改查
+
+```javascript
+const { Store } = require('mm_store');
+
+const store = new Store();
+store.add({ id: 1, name: '张三', age: 18 });
+
+// 查询
+console.log(store.getById(1)); // { id: 1, name: '张三', age: 18 }
+console.log(store.getByName('张三')); // { id: 1, name: '张三', age: 18 }
+
+// 更新（保留原主键）
+store.setById(1, { age: 20 });
+console.log(store.getById(1)); // { id: 1, name: '张三', age: 20 }
+
+// 删除
+console.log(store.delById(1)); // true
+console.log(store.delById(1)); // false
+```
+
+### 2. 分页与关键词搜索
+
+```javascript
+const { Store } = require('mm_store');
+
+const store = new Store();
+store.add({ id: 1, name: '苹果', type: 'fruit' });
+store.add({ id: 2, name: '香蕉', type: 'fruit' });
+store.add({ id: 3, name: '白菜', type: 'vegetable' });
+
+// 条件过滤
+console.log(store.list({ type: 'fruit' })); // 苹果、香蕉
+
+// 关键词搜索（在 name / title / description 字段中匹配）
+console.log(store.list({ keyword: '蕉' })); // 香蕉
+
+// 分页
+console.log(store.list({ page_now: 1, page_size: 2 })); // 苹果、香蕉
+console.log(store.count({ type: 'fruit' })); // 2
+```
+
+### 3. 排序
+
+```javascript
+const { Store } = require('mm_store');
+
+const store = new Store();
+store.add({ id: 1, name: 'A' });
+store.add({ id: 3, name: 'C' });
+store.add({ id: 2, name: 'B' });
+
+store.sort('id', 'desc');
+console.log(store.list()); // 按 id 降序
+```
+
+### 4. 自定义配置
+
+```javascript
+const { Store } = require('mm_store');
+
+const store = new Store({
+  key: 'code',      // 主键字段
+  name: 'title',     // 名称字段
+  size: 5,           // 分页大小
+  like: true,        // 启用模糊匹配
+  keyword: ['title'] // 关键词搜索字段
+});
+
+store.add({ code: 'A1', title: 'Hello World' });
+console.log(store.get({ title: 'World' })); // 模糊匹配到 A1
+```
+
+### 5. 作用域工厂
+
+```javascript
+const { storeAdmin, getStore } = require('mm_store');
+
+// 按作用域获取，相同作用域返回同一实例
+const app = storeAdmin('app');
+app.add({ id: 1, name: '配置项A' });
+
+const appAgain = storeAdmin('app');
+console.log(appAgain === app); // true
+
+// 获取默认 os 作用域实例
+const osStore = getStore();
+osStore.add({ id: 1, name: '全局项' });
+```
+
+## 注意事项
+
+1. `add` 时主键与名称字段不能为空，主键不能重复。
+2. `set` / `setById` / `setByName` 更新时强制保留原主键。
+3. `list` 未传 `page_now` 时返回全部匹配项，传入后才分页。
+4. `del` 默认只删除第一个匹配项，传 `all = true` 删除全部匹配项。
+5. 通过 `storeAdmin(scope, config)` 传入的配置仅首次创建时生效，同作用域后续调用复用已有实例。
+
+## 依赖
+
+- mm_corejs：提供 Admin 管理器
+
+## 测试
+
+```bash
+npm test
+```
+
+## 许可证
+
+ISC

package/example/index.js

@@ -0,0 +1,45 @@
+/**
+ * mm_store 存储类示例
+ * 演示 Store 类的增删改查、分页、关键词搜索与排序，
+ * 以及 storeAdmin() 作用域工厂与 getStore() 的用法。
+ * 运行：node example/index.js
+ */
+const { Store, storeAdmin, getStore } = require('../index.js');
+
+/**
+ * 主流程
+ */
+function main() {
+  // 方式1：类实例
+  const store = new Store();
+  store.add({ id: 1, name: '苹果', type: 'fruit' });
+  store.add({ id: 2, name: '香蕉', type: 'fruit' });
+  store.add({ id: 3, name: '白菜', type: 'vegetable' });
+  console.log('全部列表:', store.list());
+  console.log('水果列表:', store.list({ type: 'fruit' }));
+  console.log('关键词"蕉":', store.list({ keyword: '蕉' }));
+  console.log('第一页:', store.list({ page_now: 1, page_size: 2 }));
+
+  // 更新（保留原主键）
+  store.setById(1, { name: '红苹果' });
+  console.log('更新后 id=1:', store.getById(1));
+
+  // 删除
+  console.log('删除 id=3:', store.delById(3));
+
+  // 排序
+  store.sort('id', 'desc');
+  console.log('按 id 降序:', store.list());
+
+  // 方式2：作用域工厂（相同作用域返回同一实例）
+  const scoped = storeAdmin('app');
+  scoped.add({ id: 1, name: '配置项A' });
+  console.log('工厂实例:', scoped.list());
+
+  // 方式3：获取 os 作用域实例
+  const os_store = getStore();
+  os_store.add({ id: 1, name: '全局项' });
+  console.log('os 作用域:', os_store.list());
+}
+
+main();

package/index.js

@@ -0,0 +1,36 @@
+const Admin = require('mm_corejs').Admin;
+const Store = require('./lib/store');
+
+const admin = new Admin();
+admin.setClass(Store);
+
+/**
+ * 获取指定作用域的存储实例，不存在时创建
+ * @param {string} [scope] 作用域名称，缺省时使用 os
+ * @param {Object} [config] 存储配置项
+ * @returns {Store} 存储实例
+ */
+function storeAdmin(scope, config) {
+  if (!scope) {
+    scope = 'os';
+  }
+  let store = admin.get(scope, config);
+  if (!store) {
+    store = new Store(config);
+    admin.set(scope, store);
+  }
+  return store;
+}
+
+module.exports = {
+  Store,
+  admin,
+  storeAdmin,
+  /**
+   * 获取 os 作用域的存储实例
+   * @returns {Store} 存储实例
+   */
+  getStore() {
+    return storeAdmin('os');
+  }
+};

package/lib/store.js

@@ -0,0 +1,440 @@
+/**
+ * 存储类
+ */
+class Store {
+  // 存储列表
+  #list = [];
+
+  /**
+   * 配置项
+   */
+  static config = {
+    // 主键
+    key: 'id',
+    // 名称字段
+    name: 'name',
+    // 默认分页大小
+    size: 10,
+    // 过滤器配置 - 用于过滤query参数
+    filter: {
+      // 分页码
+      page_now: 'page_now',
+      // 分页大小
+      page_size: 'page_size',
+      // 排序字段
+      orderby: 'orderby',
+      // 分组字段
+      groupby: 'groupby',
+      // 搜索关键词
+      keyword: 'keyword'
+    },
+    // 关键词查询字段
+    keyword: ['name', 'title', 'description'],
+    // 模糊查询字段
+    like: false
+  };
+
+  /**
+   * 构造函数
+   * @param {Object} config 配置项
+   */
+  constructor(config) {
+    this.setConfig(config);
+  }
+
+  /**
+   * 设置配置项
+   * @param {Object} config 配置项
+   * @returns {void}
+   */
+  setConfig(config) {
+    this.config = {
+      ...Store.config,
+      ...this.config,
+      ...config,
+      filter: {
+        ...Store.config.filter,
+        ...(this.config && this.config.filter),
+        ...(config && config.filter)
+      }
+    };
+  }
+
+  /**
+   * 匹配查询项
+   * @param {Object} obj 数据项
+   * @param {Object} qy 查询项
+   * @returns {boolean} 是否匹配成功，成功返回true，失败返回false
+   */
+  match(obj, qy) {
+    let like = this.config.like;
+    return Object.keys(qy).every(field => {
+      let is_string = typeof obj[field] === 'string';
+      if (like && is_string) {
+        return String(obj[field]).includes(String(qy[field] ?? ''));
+      }
+      return obj[field] === qy[field];
+    });
+  }
+
+  /**
+   * 判断值是否为空
+   * @param {*} value 待判断的值
+   * @returns {boolean} undefined、null、空字符串返回true，其余返回false
+   */
+  _isEmpty(value) {
+    return value === undefined || value === null || value === '';
+  }
+
+  /**
+   * 断言项是否符合要求
+   * @param {Object} item 要断言的项
+   * @returns {void}
+   * @throws {Error} 主键不能为空
+   */
+  _assertKey(item) {
+    if (this._isEmpty(item[this.config.key])) {
+      throw new Error('主键不能为空');
+    }
+  }
+
+  /**
+   * 断言项是否符合要求
+   * @param {Object} item 要断言的项
+   * @returns {void}
+   * @throws {Error} 名称不能为空
+   */
+  _assertName(item) {
+    if (this._isEmpty(item[this.config.name])) {
+      throw new Error('名称不能为空');
+    }
+  }
+
+  /**
+   * 断言项是否符合要求
+   * @param {Object} item 要断言的项
+   * @returns {void}
+   * @throws {Error} 主键已存在
+   */
+  _assertHas(item) {
+    if (this.getById(item[this.config.key])) {
+      throw new Error('主键已存在');
+    }
+  }
+
+  /**
+   * 添加项
+   * @param {Object} item 要添加的项
+   * @returns {void}
+   */
+  add(item) {
+    this._assertKey(item);
+    this._assertName(item);
+    this._assertHas(item);
+    this.#list.push(item);
+  }
+
+  /**
+   * 删除项
+   * @param {Object} query 查询条件，符合条件的删除
+   * @param {boolean} all 是否删除所有符合条件的项，默认false（只删第一个匹配项）
+   * @returns {boolean} 是否删除了数据项，删除成功返回true，否则返回false
+   */
+  del(query, all = false) {
+    if (!all) {
+      const index = this.#list.findIndex(o => this.match(o, query));
+      if (index < 0) return false;
+      this.#list.splice(index, 1);
+      return true;
+    }
+    let deleted = false;
+    // 倒叙遍历，避免索引变化导致的跳过
+    for (let i = this.#list.length - 1; i >= 0; i--) {
+      if (this.match(this.#list[i], query)) {
+        this.#list.splice(i, 1);
+        deleted = true;
+      }
+    }
+    return deleted;
+  }
+
+  /**
+   * 删除项 - 根据主键删除
+   * @param {string} id 主键值
+   * @param {boolean} all 是否删除所有符合条件的项，默认false（只删第一个匹配项）
+   * @returns {boolean} 是否删除了数据项，删除成功返回true，否则返回false
+   */
+  delById(id, all = false) {
+    if (!all) {
+      const index = this.#list.findIndex(o => o[this.config.key] === id);
+      if (index < 0) return false;
+      this.#list.splice(index, 1);
+      return true;
+    }
+    let deleted = false;
+    // 倒叙遍历，避免索引变化导致的跳过
+    for (let i = this.#list.length - 1; i >= 0; i--) {
+      if (this.#list[i][this.config.key] === id) {
+        this.#list.splice(i, 1);
+        deleted = true;
+      }
+    }
+    return deleted;
+  }
+
+  /**
+   * 删除项 - 根据名称删除
+   * @param {string} name 名称值
+   * @param {boolean} all 是否删除所有符合条件的项，默认false（只删第一个匹配项）
+   * @returns {boolean} 是否删除了数据项，删除成功返回true，否则返回false
+   */
+  delByName(name, all = false) {
+    if (!all) {
+      const index = this.#list.findIndex(o => o[this.config.name] === name);
+      if (index < 0) return false;
+      this.#list.splice(index, 1);
+      return true;
+    }
+    let deleted = false;
+    // 倒叙遍历，避免索引变化导致的跳过
+    for (let i = this.#list.length - 1; i >= 0; i--) {
+      if (this.#list[i][this.config.name] === name) {
+        this.#list.splice(i, 1);
+        deleted = true;
+      }
+    }
+    return deleted;
+  }
+
+  /**
+   * 设置查询项
+   * @param {Object} query 查询项
+   * @param {Object} item 要设置的项
+   * @param {boolean} all 是否设置所有符合条件的项，默认false（只设第一个匹配项）
+   * @returns {boolean} 是否设置了数据项，设置成功返回true，否则返回false
+   */
+  set(query, item, all = false) {
+    if (!all) {
+      const index = this.#list.findIndex(o => this.match(o, query));
+      if (index < 0) return false;
+      // 合并更新，并强制保留原主键
+      const id = this.#list[index][this.config.key];
+      this.#list[index] = { ...this.#list[index], ...item, [this.config.key]: id };
+      return true;
+    }
+    let changed = false;
+    for (let i = 0; i < this.#list.length; i++) {
+      if (this.match(this.#list[i], query)) {
+        // 合并更新，并强制保留原主键
+        const id = this.#list[i][this.config.key];
+        this.#list[i] = { ...this.#list[i], ...item, [this.config.key]: id };
+        changed = true;
+      }
+    }
+    return changed;
+  }
+
+  /**
+   * 设置查询项 - 根据主键设置
+   * @param {string} id 主键值
+   * @param {Object} item 要设置的项
+   * @param {boolean} all 是否设置所有符合条件的项，默认false（只设第一个匹配项）
+   * @returns {boolean} 是否设置了数据项，设置成功返回true，否则返回false
+   */
+  setById(id, item, all = false) {
+    if (!all) {
+      const index = this.#list.findIndex(o => o[this.config.key] === id);
+      if (index < 0) return false;
+      // 合并更新，并强制保留原主键
+      this.#list[index] = { ...this.#list[index], ...item, [this.config.key]: id };
+      return true;
+    }
+    let changed = false;
+    for (let i = 0; i < this.#list.length; i++) {
+      if (this.#list[i][this.config.key] === id) {
+        // 合并更新，并强制保留原主键
+        this.#list[i] = { ...this.#list[i], ...item, [this.config.key]: id };
+        changed = true;
+      }
+    }
+    return changed;
+  }
+
+  /**
+   * 设置查询项 - 根据名称设置
+   * @param {string} name 名称值
+   * @param {Object} item 要设置的项
+   * @param {boolean} all 是否设置所有符合条件的项，默认false（只设第一个匹配项）
+   * @returns {boolean} 是否设置了数据项，设置成功返回true，否则返回false
+   */
+  setByName(name, item, all = false) {
+    if (!all) {
+      const index = this.#list.findIndex(o => o[this.config.name] === name);
+      if (index < 0) return false;
+      // 合并更新，并强制保留原主键
+      const id = this.#list[index][this.config.key];
+      this.#list[index] = { ...this.#list[index], ...item, [this.config.key]: id };
+      return true;
+    }
+    let changed = false;
+    for (let i = 0; i < this.#list.length; i++) {
+      if (this.#list[i][this.config.name] === name) {
+        // 合并更新，并强制保留原主键
+        const id = this.#list[i][this.config.key];
+        this.#list[i] = { ...this.#list[i], ...item, [this.config.key]: id };
+        changed = true;
+      }
+    }
+    return changed;
+  }
+
+  /**
+   * 获取查询项 - 单项数据
+   * @param {Object} query 查询项
+   * @returns {Object} 匹配到的数据项
+   */
+  get(query) {
+    return this.#list.find(o => this.match(o, query));
+  }
+
+  /**
+   * 获取查询项 - 根据主键获取
+   * @param {string} id 主键值
+   * @returns {Object} 匹配到的数据项
+   */
+  getById(id) {
+    return this.#list.find(o => o[this.config.key] === id);
+  }
+
+  /**
+   * 获取查询项 - 根据名称获取
+   * @param {string} name 名称值
+   * @returns {Object} 匹配到的数据项
+   */
+  getByName(name) {
+    return this.#list.find(o => o[this.config.name] === name);
+  }
+
+  /**
+   * 过滤列表
+   * @param {Object} query 查询项
+   * @returns {Array} 过滤后的列表
+   */
+  _matchList(query) {
+    return this.#list.filter(o => this.match(o, query));
+  }
+
+  /**
+   * 搜索列表 - 关键词模糊搜索
+   * @param {Object} query 查询项
+   * @param {string} keyword 搜索关键词
+   * @returns {Array} 搜索后的列表
+   */
+  _searchList(query, keyword) {
+    const list = this._matchList(query);
+    if (!keyword) {
+      return list;
+    }
+    const fields = this.config.keyword || [];
+    return list.filter(o =>
+      fields.some(field => String(o[field] ?? '').includes(String(keyword)))
+    );
+  }
+
+  /**
+   * 获取列表 - 多项数据
+   * @param {Object} query 查询项
+   * @returns {Array} 匹配的数据列表
+   */
+  list(query) {
+    if (!query) {
+      return [...this.#list];
+    }
+    const page_key = this.config.filter.page_now;
+    const size_key = this.config.filter.page_size;
+    const keyword_key = this.config.filter.keyword;
+    const qy = { ...query };
+    const page = qy[page_key] || 1;
+    const size = qy[size_key] || this.config.size;
+    const keyword = qy[keyword_key];
+    delete qy[page_key];
+    delete qy[size_key];
+    delete qy[this.config.filter.orderby];
+    delete qy[this.config.filter.groupby];
+    delete qy[keyword_key];
+
+    const filtered = this._searchList(qy, keyword);
+    if (query[page_key]) {
+      const offset = (page - 1) * size;
+      return filtered.slice(offset, offset + size);
+    }
+    return filtered;
+  }
+
+  /**
+   * 获取列表大小 - 多项数据
+   * @param {Object} query 查询项
+   * @returns {number} 匹配的总数
+   */
+  count(query) {
+    if (!query) {
+      return this.#list.length;
+    }
+    const page_key = this.config.filter.page_now;
+    const size_key = this.config.filter.page_size;
+    const keyword_key = this.config.filter.keyword;
+    const qy = { ...query };
+    const keyword = qy[keyword_key];
+    delete qy[page_key];
+    delete qy[size_key];
+    delete qy[this.config.filter.orderby];
+    delete qy[this.config.filter.groupby];
+    delete qy[keyword_key];
+    return this._searchList(qy, keyword).length;
+  }
+
+  /**
+   * 清空列表
+   * @returns {void}
+   */
+  clear() {
+    this.#list = [];
+  }
+
+  /**
+   * 设置列表
+   * @param {Array} list 要设置的列表
+   * @returns {void}
+   */
+  setList(list) {
+    this.#list = list;
+  }
+
+  /**
+   * 排序列表 - 按指定字段排序
+   * @param {string} orderby 排序字段，默认'sort'字段
+   * @param {string} order 排序方向，默认'asc'
+   * @returns {void}
+   */
+  sort(field = 'sort', order = 'asc') {
+    if (order !== 'asc' && order !== 'desc') {
+      order = 'asc';
+    }
+    if (order === 'asc') {
+      this.#list.sort((a, b) => {
+        const val_a = a[field];
+        const val_b = b[field];
+        return val_a < val_b ? -1 : val_a > val_b ? 1 : 0;
+      });
+    }
+    else {
+      this.#list.sort((a, b) => {
+        const val_a = a[field];
+        const val_b = b[field];
+        return val_b < val_a ? -1 : val_b > val_a ? 1 : 0;
+      });
+    }
+  }
+}
+
+module.exports = Store;

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "mm_store",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "存储类：提供基于内存列表的增删改查、分页、关键词搜索与排序能力，支持自定义主键与过滤配置",
+  "main": "index.js",
+  "scripts": {
+    "test": "node test.js"
+  },
+  "keywords": [
+    "mm_mod",
+    "mm_infra",
+    "mm_data",
+    "store",
+    "存储",
+    "列表",
+    "分页",
+    "搜索",
+    "排序"
+  ],
+  "layer": "infra",
+  "group": "data",
+  "author": "邱文武",
+  "license": "ISC",
+  "dependencies": {
+    "mm_corejs": "^1.1.4"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "index.js",
+    "lib",
+    "example",
+    "README.md",
+    "LICENSE"
+  ]
 }