mm_files 0.0.0-stage → 1.0.0

package/example/index.js

@@ -0,0 +1,38 @@
+/**
+ * mm_file 模块最小可运行示例
+ * @description 演示 File 文件存储类的文本/JSON 读写与删除等核心能力，
+ *              使用系统临时目录，示例结束自动清理
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { File, fileAdmin } = require('../index.js');
+
+// 使用系统临时目录，示例结束自动清理
+const TMP_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'mm_file_demo_'));
+
+try {
+  // 创建 File 实例
+  const file = new File({ name: 'demo', dir: TMP_DIR });
+
+  // 写入并读取文本
+  file.saveText('hello.txt', 'hello mm_file');
+  console.log('hasFile:', file.hasFile('hello.txt'));
+  console.log('loadText:', file.loadText('hello.txt'));
+
+  // 写入并读取 JSON
+  file.saveJson('data.json', { name: 'mm_file', ok: true });
+  console.log('loadJson:', JSON.stringify(file.loadJson('data.json')));
+
+  // 复制与删除
+  file.copyFile('hello.txt', 'hello_copy.txt');
+  console.log('复制后存在:', file.hasFile('hello_copy.txt'));
+  file.delFile('hello.txt');
+  console.log('删除后存在:', file.hasFile('hello.txt'));
+
+  // 工厂函数获取实例
+  const file2 = fileAdmin('demo2', { dir: TMP_DIR });
+  console.log('fileAdmin 返回 File 实例:', file2 instanceof File);
+} finally {
+  fs.rmSync(TMP_DIR, { recursive: true, force: true });
+}

package/index.js

@@ -0,0 +1,25 @@
+/**
+ * mm_files 文件存储模块
+ * @description 提供文件存储适配器，支持 os.js 的 .admin 工厂调用规则
+ */
+const File = require('./lib/file');
+const Admin = require('mm_corejs').Admin;
+
+/**
+ * 文件管理器实例（Admin 工厂）
+ * 支持 os.js 调用：require('mm_files').admin.setServer(os) -> admin.get('os', config)
+ */
+let admin = new Admin();
+admin.setClass(File);
+
+// 模块导出
+module.exports = {
+  File,
+  admin,
+  fileAdmin(scope, config) {
+    if (!scope) {
+      scope = 'os';
+    }
+    return admin.get(scope, config);
+  }
+};

package/lib/file.js

@@ -0,0 +1,259 @@
+/**
+ * 文件存储操作类
+ * @description 基于 mm_helper 文件工具函数，封装文件读写、复制、删除、遍历等能力
+ */
+const { Base } = require('mm_mod');
+const { file: FileUtil } = require('mm_helper');
+const {
+  fullname,
+  isFile,
+  isDir,
+  hasFile,
+  hasDir,
+  saveText,
+  loadText,
+  loadJson,
+  delFile,
+  delDir,
+  addDir,
+  copyFile,
+  copyDir,
+  getFile,
+  getDir,
+  getAllFile,
+  getAllDir,
+  dirname,
+  basename,
+  extname
+} = require('mm_helper');
+
+/**
+ * 文件存储操作类
+ * @class File
+ * @augments Base
+ */
+class File extends Base {
+  /**
+   * 默认配置
+   */
+  static config = {
+    name: 'default',
+    dir: fullname('./data/'),
+    encode: 'utf-8'
+  };
+
+  /**
+   * 构造函数
+   * @param {Object} config 配置对象
+   */
+  constructor(config) {
+    super(config);
+  }
+
+  /**
+   * 补全文件路径
+   * @param {String} file 文件路径
+   * @returns {String} 完整路径
+   */
+  getFullname(file) {
+    return fullname(file, this.config.dir);
+  }
+
+  /**
+   * 判断路径是否为文件
+   * @param {String} path 文件路径
+   * @returns {Boolean} 是文件返回true，否则返回false
+   */
+  isFile(path) {
+    return isFile(path);
+  }
+
+  /**
+   * 判断路径是否为目录
+   * @param {String} path 目录路径
+   * @returns {Boolean} 是目录返回true，否则返回false
+   */
+  isDir(path) {
+    return isDir(path);
+  }
+
+  /**
+   * 判断文件是否存在
+   * @param {String} file 文件路径
+   * @returns {Boolean} 存在返回true，否则返回false
+   */
+  hasFile(file) {
+    return hasFile(this.getFullname(file));
+  }
+
+  /**
+   * 判断目录是否存在
+   * @param {String} dir 目录路径
+   * @returns {Boolean} 存在返回true，否则返回false
+   */
+  hasDir(dir) {
+    return hasDir(this.getFullname(dir));
+  }
+
+  /**
+   * 保存文本到文件
+   * @param {String} file 文件路径
+   * @param {String} text 文本内容
+   * @returns {Boolean} 保存成功返回true，否则返回false
+   */
+  saveText(file, text) {
+    return saveText(this.getFullname(file), text);
+  }
+
+  /**
+   * 保存对象为JSON文件
+   * @param {String} file 文件路径
+   * @param {Object} obj 被保存的对象
+   * @param {Boolean} format 是否格式化
+   * @param {Number} space 格式化缩进空格数
+   * @returns {Boolean} 保存成功返回true，否则返回false
+   */
+  saveJson(file, obj, format = true, space = 2) {
+    return FileUtil.saveJson(this.getFullname(file), obj, format, space);
+  }
+
+  /**
+   * 加载文本文件
+   * @param {String} file 文件路径
+   * @param {String} encode 编码方式
+   * @returns {String|undefined} 加载的文本
+   */
+  loadText(file, encode) {
+    return loadText(this.getFullname(file), encode || this.config.encode);
+  }
+
+  /**
+   * 加载JSON文件
+   * @param {String} file 文件路径
+   * @returns {Object|undefined} 加载后转换的对象
+   */
+  loadJson(file) {
+    return loadJson(this.getFullname(file));
+  }
+
+  /**
+   * 删除文件
+   * @param {String} file 文件路径
+   * @returns {void}
+   */
+  delFile(file) {
+    return delFile(this.getFullname(file));
+  }
+
+  /**
+   * 删除目录
+   * @param {String} dir 目录路径
+   * @returns {void}
+   */
+  delDir(dir) {
+    return delDir(this.getFullname(dir));
+  }
+
+  /**
+   * 创建目录
+   * @param {String} dir 目录路径
+   * @returns {void}
+   */
+  addDir(dir) {
+    return addDir(this.getFullname(dir));
+  }
+
+  /**
+   * 复制文件
+   * @param {String} source 源文件路径
+   * @param {String} target 目标路径
+   * @returns {Boolean} 复制成功返回true，否则返回false
+   */
+  copyFile(source, target) {
+    return copyFile(this.getFullname(source), this.getFullname(target));
+  }
+
+  /**
+   * 复制目录
+   * @param {String} source 源目录路径
+   * @param {String} target 目标路径
+   * @returns {Boolean} 复制成功返回true，否则返回false
+   */
+  copyDir(source, target) {
+    return copyDir(this.getFullname(source), this.getFullname(target));
+  }
+
+  /**
+   * 获取当前目录下所有文件
+   * @param {String} dir 目录路径
+   * @param {String} keyword 搜索关键词
+   * @returns {Array} 文件路径数组
+   */
+  getFile(dir, keyword) {
+    return getFile(this.getFullname(dir), keyword);
+  }
+
+  /**
+   * 获取当前目录下所有目录
+   * @param {String} dir 目录路径
+   * @param {String} keyword 搜索关键词
+   * @returns {Array} 目录路径数组
+   */
+  getDir(dir, keyword) {
+    return getDir(this.getFullname(dir), keyword);
+  }
+
+  /**
+   * 递归搜索目录下所有文件
+   * @param {String} dir 目录路径
+   * @param {String} keyword 文件搜索关键词
+   * @param {String} keyword_dir 目录搜索关键词
+   * @param {Array} ignore 忽略目录数组
+   * @param {Number} max_depth 最大搜索深度，-1表示不限制深度
+   * @returns {Array} 文件路径数组
+   */
+  getAllFile(dir, keyword, keyword_dir, ignore, max_depth) {
+    return getAllFile(this.getFullname(dir), keyword, keyword_dir, ignore, max_depth);
+  }
+
+  /**
+   * 递归搜索目录下所有目录
+   * @param {String} dir 目录路径
+   * @param {String} keyword 目录搜索关键词
+   * @param {Array} ignore 忽略目录数组
+   * @param {Number} max_depth 最大搜索深度，-1表示不限制深度
+   * @returns {Array} 目录路径数组
+   */
+  getAllDir(dir, keyword, ignore, max_depth) {
+    return getAllDir(this.getFullname(dir), keyword, ignore, max_depth);
+  }
+
+  /**
+   * 获取路径所在目录
+   * @param {String} path 路径
+   * @returns {String} 路径所在目录
+   */
+  getDirname(path) {
+    return dirname(path);
+  }
+
+  /**
+   * 获取路径基础名
+   * @param {String} path 路径
+   * @returns {String} 基础名
+   */
+  getBasename(path) {
+    return basename(path);
+  }
+
+  /**
+   * 获取路径拓展名
+   * @param {String} path 路径
+   * @returns {String} 拓展名
+   */
+  getExtname(path) {
+    return extname(path);
+  }
+}
+
+module.exports = File;

package/package.json

@@ -1,6 +1,49 @@
 {
-  "name": "mm_files",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+    "name": "mm_files",
+    "version": "1.0.0",
+    "description": "高性能文件存储操作模块，提供文件读写、复制、删除、遍历等能力，支持与mm_framework无缝集成",
+    "main": "index.js",
+    "scripts": {
+        "test": "node test.js",
+        "dev": "nodemon test.js",
+        "lint": "eslint . --config eslint.config.js",
+        "lint:fix": "eslint . --config eslint.config.js --fix"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://gitee.com/qiuwenwu91/mm_file.git"
+    },
+    "keywords": [
+        "mm_mod",
+        "mm_adapter",
+        "mm_persist",
+        "file",
+        "node.js",
+        "async",
+        "await",
+        "promise",
+        "storage",
+        "mm_file"
+    ],
+    "layer": "adapter",
+    "group": "persist",
+    "author": "邱文武",
+    "license": "MIT",
+    "bugs": {
+        "url": "https://gitee.com/qiuwenwu91/mm_file/issues"
+    },
+    "homepage": "https://gitee.com/qiuwenwu91/mm_file#readme",
+    "engines": {
+        "node": ">=14.0.0"
+    },
+    "dependencies": {
+        "mm_corejs": "^1.1.4",
+        "mm_mod": "^1.0.1",
+        "mm_helper": "^1.0.0"
+    },
+    "devDependencies": {
+        "eslint": "^10.9.1",
+        "eslint-plugin-jsdoc": "^64.2.1",
+        "mm_eslint": "^1.7.7"
+    }
 }

package/test.js

@@ -0,0 +1,75 @@
+'use strict';
+
+/**
+ * mm_files 模块测试
+ * @description 验证 File 类的导出结构、实例化及基于临时目录的文件读写能力。
+ */
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { File, admin, fileAdmin } = require('./index');
+
+let tempDir = '';
+try {
+  // 创建临时目录，测试结束后清理
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mm_file_'));
+
+  // 1. 导出类型校验
+  assert.strictEqual(typeof File, 'function', 'File 应为构造函数');
+  assert.strictEqual(typeof admin, 'object', 'admin 应为对象');
+  assert.strictEqual(typeof admin.get, 'function', 'admin.get 应为函数');
+  assert.strictEqual(typeof fileAdmin, 'function', 'fileAdmin 应为函数');
+
+  // 2. 实例化校验
+  const file = new File({ name: 'test', dir: tempDir });
+  assert.ok(file instanceof File, '实例应属于 File 类');
+  assert.strictEqual(file.config.name, 'test');
+  assert.strictEqual(file.config.dir, tempDir);
+
+  // 3. 文本写入 / 存在判断 / 读取
+  assert.strictEqual(file.saveText('a.txt', 'hello mm_file'), true);
+  assert.strictEqual(file.hasFile('a.txt'), true);
+  assert.strictEqual(file.loadText('a.txt'), 'hello mm_file');
+
+  // 4. JSON 写入 / 读取
+  const jsonObj = { name: 'mm_file', ok: true };
+  assert.strictEqual(file.saveJson('data.json', jsonObj), true);
+  assert.deepStrictEqual(file.loadJson('data.json'), jsonObj);
+
+  // 5. 目录操作
+  fs.mkdirSync(path.join(tempDir, 'subdir'));
+  assert.strictEqual(file.hasDir('subdir'), true);
+  assert.strictEqual(file.isDir(file.getFullname('subdir')), true);
+  assert.strictEqual(file.isFile(file.getFullname('a.txt')), true);
+
+  // 6. 遍历操作
+  const files = file.getFile('.');
+  assert.ok(Array.isArray(files), 'getFile 应返回数组');
+  assert.ok(files.includes(file.getFullname('a.txt')), '遍历结果应包含 a.txt');
+  const dirs = file.getDir('.');
+  assert.ok(Array.isArray(dirs), 'getDir 应返回数组');
+  assert.ok(dirs.includes(file.getFullname('subdir')), '遍历结果应包含 subdir');
+  assert.ok(Array.isArray(file.getAllFile('.')), 'getAllFile 应返回数组');
+  assert.ok(Array.isArray(file.getAllDir('.')), 'getAllDir 应返回数组');
+
+  // 7. 复制 / 删除
+  assert.strictEqual(file.copyFile('a.txt', 'b.txt'), true);
+  assert.strictEqual(file.hasFile('b.txt'), true);
+  file.delFile('a.txt');
+  assert.strictEqual(file.hasFile('a.txt'), false);
+  file.delDir('subdir');
+  assert.strictEqual(file.hasDir('subdir'), false);
+
+  // 8. 工厂导出
+  const fa = fileAdmin('test', { dir: tempDir });
+  assert.ok(fa instanceof File, 'fileAdmin 应返回 File 实例');
+
+  console.log('mm_files 模块测试通过');
+} finally {
+  if (tempDir) {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.