mm_watcher 0.0.0-stage → 1.0.1

package/example/demo.js

@@ -0,0 +1,87 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { Watcher } = require('../index');
+
+/**
+ * 等待指定毫秒
+ * @param {number} ms - 等待时间
+ * @returns {Promise<void>} 到期后 resolve
+ */
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * 演示目录监听：忽略目录、忽略文件、新增/删除事件
+ * @returns {Promise<void>} 演示完成
+ */
+async function demoDirWatch() {
+  const dir = path.join(os.tmpdir(), 'mm_watcher_demo_dir');
+  fs.rmSync(dir, { recursive: true, force: true });
+  fs.mkdirSync(dir, { recursive: true });
+  fs.mkdirSync(path.join(dir, 'node_modules'), { recursive: true });
+
+  const changes = [];
+  const watcher = new Watcher({ target: dir, ignore: ['node_modules', '*.tmp'] });
+  const ok = watcher.start((list) => changes.push(...list));
+  console.log('目录监听:', ok, '| 目标:', dir);
+
+  fs.writeFileSync(path.join(dir, 'a.json'), '{}');
+  fs.writeFileSync(path.join(dir, 'cache.tmp'), 'x');
+  fs.writeFileSync(path.join(dir, 'node_modules/b.json'), '{}');
+  await delay(300);
+  console.log('变更事件:', changes);
+
+  fs.rmSync(path.join(dir, 'a.json'));
+  changes.length = 0;
+  await delay(300);
+  fs.writeFileSync(path.join(dir, 'a.json'), '{}');
+  await delay(300);
+  console.log('删除后重建:', changes.map((one) => one.type + ' ' + one.path));
+
+  watcher.dispose();
+  console.log('解绑后状态:', watcher.active);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+/**
+ * 演示单文件监听：修改与删除事件
+ * @returns {Promise<void>} 演示完成
+ */
+async function demoFileWatch() {
+  const dir = path.join(os.tmpdir(), 'mm_watcher_demo_file');
+  fs.rmSync(dir, { recursive: true, force: true });
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, 'config.json');
+  fs.writeFileSync(file, '{}');
+
+  const changes = [];
+  const watcher = new Watcher({ target: file });
+  const ok = watcher.start((list) => changes.push(...list));
+  console.log('单文件监听:', ok, '| 目标:', file);
+
+  fs.writeFileSync(file, '{"v":1}');
+  await delay(300);
+  console.log('修改事件:', changes.map((one) => one.type + ' ' + one.path));
+
+  changes.length = 0;
+  fs.rmSync(file);
+  await delay(300);
+  console.log('删除事件:', changes.map((one) => one.type + ' ' + one.path));
+
+  watcher.dispose();
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+async function main() {
+  await demoDirWatch();
+  await demoFileWatch();
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/index.js

@@ -0,0 +1,16 @@
+const Watcher = require('./lib/watcher');
+const Admin = require('mm_corejs').Admin;
+
+const admin = new Admin();
+admin.setClass(Watcher);
+
+module.exports = {
+  Watcher,
+  admin,
+  watcherAdmin(scope, config) {
+    if (!scope) {
+      scope = 'os';
+    }
+    return admin.get(scope, config);
+  }
+};

package/lib/fs_handle.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const fs = require('fs');
+
+/**
+ * 文件系统监听句柄
+ * @description 包装 fs.watch：目录递归或单文件监听，打开失败返回 false，关闭与 unref 均容错
+ */
+class FsHandle {
+  /** 底层 watcher，未打开时为 null */
+  #watcher = null;
+
+  /**
+   * 打开监听
+   * @param {string} target 监听目标绝对路径
+   * @param {{ recursive: boolean }} options 监听选项
+   * @param {(event_type: string, filename: string|null) => void} on_event 事件回调
+   * @param {() => void} on_error 错误回调
+   * @returns {boolean} 打开成功返回 true
+   */
+  open(target, options, on_event, on_error) {
+    let watcher = null;
+    try {
+      watcher = fs.watch(target, options, on_event);
+    } catch {
+      return false;
+    }
+    if (typeof watcher.unref === 'function') watcher.unref();
+    watcher.on('error', on_error);
+    this.#watcher = watcher;
+    return true;
+  }
+
+  /**
+   * 关闭监听，已关闭或关闭抛错时静默忽略
+   * @returns {void}
+   */
+  close() {
+    if (!this.#watcher) return;
+    try {
+      this.#watcher.close();
+    } catch {
+      // 监听器已关闭时忽略
+    }
+    this.#watcher = null;
+  }
+}
+
+/* 导出类 */
+module.exports = FsHandle;

package/lib/ignore_matcher.js

@@ -0,0 +1,92 @@
+'use strict';
+
+const path = require('path');
+
+/**
+ * 忽略匹配器
+ * @description 模式逐项编译：以 '.' 开头按扩展名匹配文件；含 * 或 ? 按通配符匹配目录名与文件名；否则精确名匹配目录名与文件名
+ */
+class IgnoreMatcher {
+  /** 精确名集合 */
+  #exact = new Set();
+  /** 通配符编译后的正则列表 */
+  #globs = [];
+  /** 扩展名集合（含点、小写） */
+  #exts = new Set();
+
+  /**
+   * 创建忽略匹配器
+   * @param {Array<string>} patterns 忽略模式数组
+   */
+  constructor(patterns) {
+    if (!Array.isArray(patterns)) return;
+    for (let i = 0; i < patterns.length; i++) {
+      this._compile(patterns[i]);
+    }
+  }
+
+  /**
+   * 编译单个模式
+   * @param {string} pattern 原始模式
+   * @returns {void}
+   * @private
+   */
+  _compile(pattern) {
+    const s = String(pattern).trim();
+    if (!s) return;
+    if (s.startsWith('.')) {
+      this.#exts.add(s.toLowerCase());
+      return;
+    }
+    if (s.includes('*') || s.includes('?')) {
+      this.#globs.push(this._globToRegExp(s));
+      return;
+    }
+    this.#exact.add(s);
+  }
+
+  /**
+   * 通配符转正则：* 匹配任意字符序列，? 匹配单个字符，其余特殊字符转义
+   * @param {string} pattern 通配符模式
+   * @returns {RegExp} 锚定正则
+   * @private
+   */
+  _globToRegExp(pattern) {
+    let source = '';
+    for (const ch of pattern) {
+      if (ch === '*') source += '.*';
+      else if (ch === '?') source += '.';
+      else source += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+    return new RegExp('^' + source + '$');
+  }
+
+  /**
+   * 判断目录名是否命中忽略
+   * @param {string} segment 目录段名
+   * @returns {boolean} 命中返回 true
+   */
+  isIgnoredDir(segment) {
+    if (this.#exact.has(segment)) return true;
+    for (let i = 0; i < this.#globs.length; i++) {
+      if (this.#globs[i].test(segment)) return true;
+    }
+    return false;
+  }
+
+  /**
+   * 判断文件名是否命中忽略（精确名、通配符或扩展名）
+   * @param {string} basename 文件名
+   * @returns {boolean} 命中返回 true
+   */
+  isIgnoredFile(basename) {
+    if (this.#exact.has(basename)) return true;
+    for (let i = 0; i < this.#globs.length; i++) {
+      if (this.#globs[i].test(basename)) return true;
+    }
+    return this.#exts.has(path.extname(basename).toLowerCase());
+  }
+}
+
+/* 导出类 */
+module.exports = IgnoreMatcher;

package/lib/path_util.js

@@ -0,0 +1,15 @@
+'use strict';
+
+/**
+ * 路径规范化：统一分隔符、去 "./" 前缀与首尾斜杠
+ * @param {string} p 原始路径
+ * @returns {string} 规范化后的路径
+ */
+function normalizeKey(p) {
+  return String(p)
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '')
+    .replace(/^\/+|\/+$/g, '');
+}
+
+module.exports = { normalizeKey };

package/lib/symbols.js

@@ -0,0 +1,8 @@
+'use strict';
+
+/* 内部事件分发方法名，仅供监听中枢调用 */
+const DISPATCH = Symbol('mm_watcher.dispatch');
+/* 内部停用方法名，仅供监听中枢在监听出错时调用 */
+const DEACTIVATE = Symbol('mm_watcher.deactivate');
+
+module.exports = { DISPATCH, DEACTIVATE };

package/lib/watcher.js

@@ -0,0 +1,118 @@
+'use strict';
+
+const hub = require('./watcher_hub');
+const { DISPATCH, DEACTIVATE } = require('./symbols');
+
+/* 默认防抖窗口（毫秒） */
+const DEFAULT_DEBOUNCE = 100;
+
+/**
+ * 文件监听器
+ * @description 监听目录（递归）或单个文件，事件经防抖与忽略过滤后以变更列表回调；
+ * 相同目标与忽略配置的多个监听器共享底层句柄，监听不可用时静默降级
+ */
+class Watcher {
+  /** 监听目标绝对路径 */
+  #target;
+  /** 共享句柄的监听键 */
+  #key;
+  /** 忽略模式数组 */
+  #ignore;
+  /** 防抖窗口（毫秒） */
+  #debounce;
+  /** 出错停用时的外部回调 */
+  #onError;
+  /** 变更回调 */
+  #callback = null;
+  /** 是否处于监听状态 */
+  #active = false;
+
+  /**
+   * 创建监听器
+   * @param {{ target: string, ignore?: Array<string>, debounce?: number, onError?: () => void }} [config] 监听配置，target 为目录或文件绝对路径
+   */
+  constructor(config = {}) {
+    this.#target = String(config.target).replace(/\\/g, '/');
+    this.#ignore = Array.isArray(config.ignore) ? [...config.ignore] : [];
+    this.#debounce =
+      Number.isFinite(config.debounce) && config.debounce >= 0
+        ? config.debounce
+        : DEFAULT_DEBOUNCE;
+    this.#onError = typeof config.onError === 'function' ? config.onError : null;
+    this.#key = [this.#target, this.#ignore.join(',')].join('\u0001');
+  }
+
+  /**
+   * 开启监听
+   * @param {(changes: Array<{ type: string, path: string }>) => void} [callback] 变更回调，type 为 change/unlink/refresh
+   * @returns {boolean} 监听是否可用
+   */
+  start(callback) {
+    if (this.#active) return true;
+    if (!hub.add(this)) return false;
+    this.#callback = typeof callback === 'function' ? callback : null;
+    this.#active = true;
+    return true;
+  }
+
+  /**
+   * 关闭监听并清空变更回调
+   * @returns {void}
+   */
+  dispose() {
+    if (!this.#active) return;
+    this.#active = false;
+    this.#callback = null;
+    hub.del(this);
+  }
+
+  /** 当前是否处于监听状态 */
+  get active() { return this.#active; }
+  /** 共享句柄的监听键 */
+  get key() { return this.#key; }
+  /** 监听目标绝对路径 */
+  get target() { return this.#target; }
+  /** 忽略模式副本 */
+  get ignorePatterns() { return [...this.#ignore]; }
+  /** 防抖窗口（毫秒） */
+  get debounce() { return this.#debounce; }
+
+  /**
+   * 接收中枢分发的变更列表
+   * @param {Array<{ type: string, path: string }>} changes 变更列表
+   * @returns {void}
+   */
+  [DISPATCH](changes) {
+    if (!this.#active || !changes.length) return;
+    if (!this.#callback) return;
+    const list = changes.map((one) => ({ ...one }));
+    try {
+      this.#callback(list);
+    } catch (error) {
+      console.error('[mm_watcher] 监听回调执行失败:', error);
+    }
+  }
+
+  /**
+   * 底层监听出错后停用本监听器并通知外部
+   * @returns {void}
+   */
+  [DEACTIVATE]() {
+    this.#active = false;
+    this.#callback = null;
+    if (this.#onError) {
+      this.#onError();
+    }
+  }
+
+  /**
+   * 关闭全部监听句柄
+   * @returns {void}
+   */
+  static closeAll() {
+    hub.closeAll();
+  }
+}
+
+/* 导出类 */
+module.exports = Watcher;

package/lib/watcher_hub.js

@@ -0,0 +1,242 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { normalizeKey } = require('./path_util');
+const IgnoreMatcher = require('./ignore_matcher');
+const FsHandle = require('./fs_handle');
+const { DISPATCH, DEACTIVATE } = require('./symbols');
+
+/**
+ * 监听中枢
+ * @description 按 目标+忽略配置 共享底层监听句柄，防抖窗口内合并事件，
+ * 逐路径 stat 分类为 change/unlink/refresh 并过滤忽略项，最后分发给各监听器
+ */
+class WatcherHub {
+  /** 监听键 -> { key, target, is_dir, debounce, matcher, watchers, timer, pending, handle } */
+  #entries = new Map();
+
+  /**
+   * 登记监听器，同键共享句柄
+   * @param {object} watcher 监听器实例
+   * @returns {boolean} 句柄可用返回 true
+   */
+  add(watcher) {
+    const key = watcher.key;
+    const exists = this.#entries.get(key);
+    if (exists) {
+      exists.watchers.add(watcher);
+      return true;
+    }
+    return this._openEntry(watcher);
+  }
+
+  /**
+   * 注销监听器，最后一个注销时关闭句柄
+   * @param {object} watcher 监听器实例
+   * @returns {void}
+   */
+  del(watcher) {
+    const entry = this.#entries.get(watcher.key);
+    if (!entry) return;
+    entry.watchers.delete(watcher);
+    if (entry.watchers.size === 0) {
+      this._closeEntry(entry);
+    }
+  }
+
+  /**
+   * 关闭全部监听句柄并停用全部监听器
+   * @returns {void}
+   */
+  closeAll() {
+    const keys = [...this.#entries.keys()];
+    for (let i = 0; i < keys.length; i++) {
+      this._teardown(keys[i]);
+    }
+  }
+
+  /**
+   * 关闭条目并停用其全部监听器
+   * @param {string} key 监听键
+   * @returns {void}
+   * @private
+   */
+  _teardown(key) {
+    const entry = this.#entries.get(key);
+    if (!entry) return;
+    const watchers = [...entry.watchers];
+    this._closeEntry(entry);
+    for (const watcher of watchers) {
+      watcher[DEACTIVATE]();
+    }
+  }
+
+  /**
+   * 为新监听器打开共享句柄
+   * @param {object} watcher 监听器实例
+   * @returns {boolean} 打开成功返回 true
+   * @private
+   */
+  _openEntry(watcher) {
+    const stat = this._stat(watcher.target);
+    if (!stat) return false;
+    const is_dir = stat.isDirectory();
+    const entry = {
+      key: watcher.key,
+      target: watcher.target,
+      is_dir,
+      debounce: watcher.debounce,
+      matcher: new IgnoreMatcher(watcher.ignorePatterns),
+      watchers: new Set([watcher]),
+      timer: null,
+      pending: new Set(),
+      handle: null,
+    };
+    this.#entries.set(entry.key, entry);
+
+    const handle = new FsHandle();
+    const ok = handle.open(
+      watcher.target,
+      { recursive: is_dir },
+      (event_type, filename) => this._onEvent(entry.key, filename),
+      () => this._onError(entry.key)
+    );
+    if (!ok) {
+      this.#entries.delete(entry.key);
+      return false;
+    }
+    entry.handle = handle;
+    return true;
+  }
+
+  /**
+   * 关闭并移除监听条目
+   * @param {object} entry 监听条目
+   * @returns {void}
+   * @private
+   */
+  _closeEntry(entry) {
+    if (entry.timer) clearTimeout(entry.timer);
+    entry.handle.close();
+    this.#entries.delete(entry.key);
+  }
+
+  /**
+   * 读取目标状态
+   * @param {string} target 目标绝对路径
+   * @returns {object|null} 状态对象，读取失败返回 null
+   * @private
+   */
+  _stat(target) {
+    try {
+      return fs.statSync(target);
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * 底层监听出错：关闭条目并停用全部监听器
+   * @param {string} key 监听键
+   * @returns {void}
+   * @private
+   */
+  _onError(key) {
+    this._teardown(key);
+  }
+
+  /**
+   * 记录文件系统事件，按防抖窗口合并后处理
+   * @param {string} key 监听键
+   * @param {string|null} filename 事件对应的相对路径，为空表示无法定位
+   * @returns {void}
+   * @private
+   */
+  _onEvent(key, filename) {
+    const entry = this.#entries.get(key);
+    if (!entry) return;
+
+    entry.pending.add(filename ? normalizeKey(filename) : '');
+    if (entry.timer) return;
+
+    entry.timer = setTimeout(() => {
+      entry.timer = null;
+      this._flush(key);
+    }, entry.debounce);
+
+    if (typeof entry.timer.unref === 'function') {
+      entry.timer.unref();
+    }
+  }
+
+  /**
+   * 处理防抖窗口内累积的事件并分发
+   * @param {string} key 监听键
+   * @returns {void}
+   * @private
+   */
+  _flush(key) {
+    const entry = this.#entries.get(key);
+    if (!entry || !entry.pending.size) return;
+
+    const list = [...entry.pending];
+    entry.pending.clear();
+
+    const changes = [];
+    for (let i = 0; i < list.length; i++) {
+      const event = this._classify(entry, list[i]);
+      if (!event) continue;
+      changes.push(event);
+      if (event.type === 'refresh') break;
+    }
+    if (!changes.length) return;
+
+    for (const watcher of entry.watchers) {
+      watcher[DISPATCH](changes);
+    }
+  }
+
+  /**
+   * 将单个路径事件分类为监听变更
+   * @description 无法定位的路径与目录事件分类为 refresh；忽略项返回 null；
+   * 目录目标按相对路径判状态，单文件目标按文件本身判状态
+   * @param {object} entry 监听条目
+   * @param {string} rel_path 规范化后的相对路径，空串表示无法定位
+   * @returns {{ type: string, path: string }|null} 变更事件，忽略时返回 null
+   * @private
+   */
+  _classify(entry, rel_path) {
+    if (!rel_path) return { type: 'refresh', path: '' };
+
+    if (!entry.is_dir) {
+      return this._toEvent(this._stat(entry.target), rel_path);
+    }
+
+    const parts = rel_path.split('/');
+    const basename = parts[parts.length - 1];
+    for (let i = 0; i < parts.length - 1; i++) {
+      if (entry.matcher.isIgnoredDir(parts[i])) return null;
+    }
+    if (entry.matcher.isIgnoredFile(basename)) return null;
+
+    return this._toEvent(this._stat(path.join(entry.target, rel_path)), rel_path);
+  }
+
+  /**
+   * 按路径状态生成变更事件
+   * @param {object|null} stat 状态对象，不存在为 null
+   * @param {string} rel_path 相对路径
+   * @returns {{ type: string, path: string }|null} 变更事件，特殊文件返回 null
+   * @private
+   */
+  _toEvent(stat, rel_path) {
+    if (!stat) return { type: 'unlink', path: rel_path };
+    if (stat.isDirectory()) return { type: 'refresh', path: rel_path };
+    if (!stat.isFile()) return null;
+    return { type: 'change', path: rel_path };
+  }
+}
+
+/* 导出单例 */
+module.exports = new WatcherHub();

package/package.json

@@ -1,6 +1,43 @@
 {
-  "name": "mm_watcher",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "mm_watcher",
+    "version": "1.0.1",
+    "description": "文件监听器，支持监听目录（递归）与单个文件，事件防抖合并、忽略目录与文件（精确名/扩展名/通配符），同目标多监听者共享底层句柄。",
+    "repository": {
+        "type": "git",
+        "url": "git+https://gitee.com/qiuwenwu91/mm_watcher.git"
+    },
+    "keywords": [
+        "mm_mod",
+        "mm_infra",
+        "mm_common",
+        "超级美眉",
+        "文件监听",
+        "目录监听",
+        "watcher"
+    ],
+    "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"
+    },
+    "devDependencies": {
+        "jest": "^30.5.2"
+    },
+    "dependencies": {
+        "mm_corejs": "^1.1.5"
+    }
+}

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.