mm_watcher 1.0.0 → 2.0.0

package/example/demo.js

@@ -15,32 +15,37 @@ function delay(ms) {
 }
 
 /**
- * 演示目录监听：忽略目录、忽略文件、新增/删除事件
+ * 演示目录监听：忽略目录、忽略文件、add/set/del/reload 事件
  * @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 });
+  fs.writeFileSync(path.join(dir, 'a.json'), '{}');
+
+  const watcher = new Watcher({ target: dir, ignore: ['node_modules', '*.tmp'] });
+  watcher.on('add', (p) => console.log('add   ', p));
+  watcher.on('set', (p) => console.log('set   ', p));
+  watcher.on('del', (p) => console.log('del   ', p));
+  watcher.on('reload', (p) => console.log('reload', p));
 
-  const changes = [];
-  const watcher = new Watcher(dir, { ignore: ['node_modules', '*.tmp'] });
-  const ok = watcher.start((list) => changes.push(...list));
+  const ok = watcher.listen();
   console.log('目录监听:', ok, '| 目标:', dir);
 
-  fs.writeFileSync(path.join(dir, 'a.json'), '{}');
+  fs.writeFileSync(path.join(dir, 'b.json'), '{}');
   fs.writeFileSync(path.join(dir, 'cache.tmp'), 'x');
-  fs.writeFileSync(path.join(dir, 'node_modules/b.json'), '{}');
+  fs.writeFileSync(path.join(dir, 'node_modules', 'skip.json'), '{}');
+  await delay(300);
+
+  fs.writeFileSync(path.join(dir, 'a.json'), '{"v":2}');
   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'), '{}');
+
+  fs.mkdirSync(path.join(dir, 'sub'), { recursive: true });
   await delay(300);
-  console.log('删除后重建:', changes.map((one) => one.type + ' ' + one.path));
 
   watcher.dispose();
   console.log('解绑后状态:', watcher.active);
@@ -48,7 +53,7 @@ async function demoDirWatch() {
 }
 
 /**
- * 演示单文件监听：修改与删除事件
+ * 演示单文件监听：set 与 del 事件
  * @returns {Promise<void>} 演示完成
  */
 async function demoFileWatch() {
@@ -58,19 +63,18 @@ async function demoFileWatch() {
   const file = path.join(dir, 'config.json');
   fs.writeFileSync(file, '{}');
 
-  const changes = [];
-  const watcher = new Watcher(file);
-  const ok = watcher.start((list) => changes.push(...list));
+  const watcher = new Watcher({ target: file });
+  watcher.on('set', (p) => console.log('set   ', p));
+  watcher.on('del', (p) => console.log('del   ', p));
+
+  const ok = watcher.listen();
   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 });

package/index.js

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

package/lib/watcher.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const { EventEmitter } = require('events');
 const hub = require('./watcher_hub');
 const { DISPATCH, DEACTIVATE } = require('./symbols');
 
@@ -8,10 +9,11 @@ const DEFAULT_DEBOUNCE = 100;
 
 /**
  * 文件监听器
- * @description 监听目录（递归）或单个文件，事件经防抖与忽略过滤后以变更列表回调；
+ * @description 监听目录（递归）或单个文件，事件经防抖与忽略过滤后按类型分发：
+ * on('add') 新增文件、on('set') 修改文件、on('del') 删除文件、on('reload') 目录变化或无法定位需全量重扫；
  * 相同目标与忽略配置的多个监听器共享底层句柄，监听不可用时静默降级
  */
-class Watcher {
+class Watcher extends EventEmitter {
   /** 监听目标绝对路径 */
   #target;
   /** 共享句柄的监听键 */
@@ -21,49 +23,45 @@ class Watcher {
   /** 防抖窗口（毫秒） */
   #debounce;
   /** 出错停用时的外部回调 */
-  #onError;
-  /** 变更回调 */
-  #callback = null;
+  #on_error;
   /** 是否处于监听状态 */
   #active = false;
 
   /**
    * 创建监听器
-   * @param {string} target 目录或文件绝对路径
-   * @param {{ ignore?: Array<string>, debounce?: number, onError?: () => void }} [options] 监听选项
+   * @param {{ target: string, ignore?: Array<string>, debounce?: number, onError?: () => void }} [config] 监听配置，target 为目录或文件绝对路径
    */
-  constructor(target, options = {}) {
-    this.#target = String(target).replace(/\\/g, '/');
-    this.#ignore = Array.isArray(options.ignore) ? [...options.ignore] : [];
+  constructor(config = {}) {
+    super();
+    this.#target = String(config.target).replace(/\\/g, '/');
+    this.#ignore = Array.isArray(config.ignore) ? [...config.ignore] : [];
     this.#debounce =
-      Number.isFinite(options.debounce) && options.debounce >= 0
-        ? options.debounce
+      Number.isFinite(config.debounce) && config.debounce >= 0
+        ? config.debounce
         : DEFAULT_DEBOUNCE;
-    this.#onError = typeof options.onError === 'function' ? options.onError : null;
+    this.#on_error = 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) {
+  listen() {
     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;
+    this.removeAllListeners();
     hub.del(this);
   }
 
@@ -79,18 +77,18 @@ class Watcher {
   get debounce() { return this.#debounce; }
 
   /**
-   * 接收中枢分发的变更列表
-   * @param {Array<{ type: string, path: string }>} changes 变更列表
+   * 接收中枢分发的一组变更并逐条发出事件
+   * @param {Array<{ type: string, path: string }>} events 变更列表，type 为 add/set/del/reload
    * @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);
+  [DISPATCH](events) {
+    if (!this.#active) return;
+    for (let i = 0; i < events.length; i++) {
+      try {
+        this.emit(events[i].type, events[i].path);
+      } catch (error) {
+        console.error('[mm_watcher] 事件处理失败:', error);
+      }
     }
   }
 
@@ -100,9 +98,9 @@ class Watcher {
    */
   [DEACTIVATE]() {
     this.#active = false;
-    this.#callback = null;
-    if (this.#onError) {
-      this.#onError();
+    this.removeAllListeners();
+    if (this.#on_error) {
+      this.#on_error();
     }
   }
 

package/lib/watcher_hub.js

@@ -10,10 +10,10 @@ const { DISPATCH, DEACTIVATE } = require('./symbols');
 /**
  * 监听中枢
  * @description 按 目标+忽略配置 共享底层监听句柄，防抖窗口内合并事件，
- * 逐路径 stat 分类为 change/unlink/refresh 并过滤忽略项，最后分发给各监听器
+ * 依据基线文件集合将路径事件分类为 add/set/del/reload 并过滤忽略项，最后分发给各监听器
  */
 class WatcherHub {
-  /** 监听键 -> { key, target, is_dir, debounce, matcher, watchers, timer, pending, handle } */
+  /** 监听键 -> { key, target, is_dir, debounce, matcher, known, watchers, timer, pending, handle } */
   #entries = new Map();
 
   /**
@@ -57,23 +57,7 @@ class WatcherHub {
   }
 
   /**
-   * 关闭条目并停用其全部监听器
-   * @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
@@ -88,12 +72,12 @@ class WatcherHub {
       is_dir,
       debounce: watcher.debounce,
       matcher: new IgnoreMatcher(watcher.ignorePatterns),
+      known: new Set(),
       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(
@@ -102,11 +86,11 @@ class WatcherHub {
       (event_type, filename) => this._onEvent(entry.key, filename),
       () => this._onError(entry.key)
     );
-    if (!ok) {
-      this.#entries.delete(entry.key);
-      return false;
-    }
+    if (!ok) return false;
+
     entry.handle = handle;
+    this.#entries.set(entry.key, entry);
+    entry.known = this._scanKnown(entry);
     return true;
   }
 
@@ -122,6 +106,22 @@ class WatcherHub {
     this.#entries.delete(entry.key);
   }
 
+  /**
+   * 关闭条目并停用其全部监听器
+   * @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 {string} target 目标绝对路径
@@ -136,6 +136,53 @@ class WatcherHub {
     }
   }
 
+  /**
+   * 建立基线文件集合：目录目标递归收集未忽略文件，单文件目标记录文件本身
+   * @param {object} entry 监听条目
+   * @returns {Set<string>} 相对路径集合
+   * @private
+   */
+  _scanKnown(entry) {
+    const known = new Set();
+    if (!entry.is_dir) {
+      known.add(path.basename(entry.target));
+      return known;
+    }
+    this._walkKnown(entry, entry.target, '', known);
+    return known;
+  }
+
+  /**
+   * 递归收集目录内未忽略的相对文件路径
+   * @param {object} entry 监听条目
+   * @param {string} dir 当前目录绝对路径
+   * @param {string} prefix 相对路径前缀
+   * @param {Set<string>} known 收集集合
+   * @returns {void}
+   * @private
+   */
+  _walkKnown(entry, dir, prefix, known) {
+    let dirents = [];
+    try {
+      dirents = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (let i = 0; i < dirents.length; i++) {
+      const dirent = dirents[i];
+      const rel_path = prefix ? prefix + '/' + dirent.name : dirent.name;
+      if (dirent.isDirectory()) {
+        if (!entry.matcher.isIgnoredDir(dirent.name)) {
+          this._walkKnown(entry, path.join(dir, dirent.name), rel_path, known);
+        }
+        continue;
+      }
+      if (!dirent.isFile()) continue;
+      if (entry.matcher.isIgnoredFile(dirent.name)) continue;
+      known.add(rel_path);
+    }
+  }
+
   /**
    * 底层监听出错：关闭条目并停用全部监听器
    * @param {string} key 监听键
@@ -183,58 +230,60 @@ class WatcherHub {
     const list = [...entry.pending];
     entry.pending.clear();
 
-    const changes = [];
+    const events = [];
     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;
+      events.push(event);
+      if (event.type === 'reload') break;
     }
-    if (!changes.length) return;
+    if (!events.length) return;
 
     for (const watcher of entry.watchers) {
-      watcher[DISPATCH](changes);
+      watcher[DISPATCH](events);
     }
   }
 
   /**
-   * 将单个路径事件分类为监听变更
-   * @description 无法定位的路径与目录事件分类为 refresh；忽略项返回 null；
-   * 目录目标按相对路径判状态，单文件目标按文件本身判状态
+   * 将单个路径事件分类为监听变更并更新基线集合
+   * @description 无法定位与目录事件分类为 reload 并重建基线；忽略项返回 null；
+   * 基线外的新增分类为 add，基线内的修改分类为 set，消失的路径分类为 del
    * @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);
+    if (!rel_path) {
+      entry.known = this._scanKnown(entry);
+      return { type: 'reload', 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.is_dir) {
+      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;
     }
-    if (entry.matcher.isIgnoredFile(basename)) return null;
 
-    return this._toEvent(this._stat(path.join(entry.target, rel_path)), rel_path);
-  }
+    const stat = this._stat(entry.is_dir ? path.join(entry.target, rel_path) : entry.target);
 
-  /**
-   * 按路径状态生成变更事件
-   * @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 };
+    if (stat && stat.isDirectory()) {
+      entry.known = this._scanKnown(entry);
+      return { type: 'reload', path: rel_path };
+    }
+    if (stat && stat.isFile()) {
+      const type = entry.known.has(rel_path) ? 'set' : 'add';
+      entry.known.add(rel_path);
+      return { type, path: rel_path };
+    }
+    if (!stat) {
+      entry.known.delete(rel_path);
+      return { type: 'del', path: rel_path };
+    }
+    return null;
   }
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "mm_watcher",
-    "version": "1.0.0",
-    "description": "文件监听器，支持监听目录（递归）与单个文件，事件防抖合并、忽略目录与文件（精确名/扩展名/通配符），同目标多监听者共享底层句柄。",
+    "version": "2.0.0",
+    "description": "文件监听器，listen 监听目录（递归）或单个文件，on 订阅 add/set/del/reload 事件，支持忽略目录与文件（精确名/扩展名/通配符）、事件防抖合并、同目标多监听者共享底层句柄。",
     "repository": {
         "type": "git",
         "url": "git+https://gitee.com/qiuwenwu91/mm_watcher.git"
@@ -36,5 +36,8 @@
     },
     "devDependencies": {
         "jest": "^30.5.2"
+    },
+    "dependencies": {
+        "mm_corejs": "^1.1.5"
     }
 }