@eggjs/watcher 1.0.0

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@eggjs/watcher",
+  "version": "1.0.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "file watcher plugin for egg",
+  "eggPlugin": {
+    "name": "watcher",
+    "exports": {
+      "import": "./dist/esm",
+      "require": "./dist/commonjs"
+    }
+  },
+  "scripts": {
+    "lint": "eslint --cache src test --ext .ts",
+    "pretest": "npm run lint -- --fix && npm run prepublishOnly",
+    "test": "egg-bin test",
+    "preci": "npm run lint && npm run prepublishOnly && attw --pack",
+    "ci": "egg-bin cov",
+    "prepublishOnly": "tshy && tshy-after"
+  },
+  "homepage": "https://github.com/eggjs/egg-watcher",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:eggjs/egg-watcher.git"
+  },
+  "keywords": [
+    "egg-watcher",
+    "egg",
+    "watcher",
+    "watch"
+  ],
+  "engines": {
+    "node": ">= 18.19.0"
+  },
+  "dependencies": {
+    "@eggjs/utils": "^4.0.3",
+    "camelcase": "^5.0.0",
+    "sdk-base": "^5.0.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.17.1",
+    "@eggjs/tsconfig": "1",
+    "@types/node": "22",
+    "@types/mocha": "10",
+    "egg": "beta",
+    "egg-bin": "beta",
+    "egg-mock": "beta",
+    "eslint": "8",
+    "eslint-config-egg": "14",
+    "tshy": "3",
+    "tshy-after": "1",
+    "typescript": "5"
+  },
+  "type": "module",
+  "tshy": {
+    "exports": {
+      ".": "./src/index.ts",
+      "./package.json": "./package.json"
+    }
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/index.d.ts",
+        "default": "./dist/commonjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "types": "./dist/commonjs/index.d.ts",
+  "main": "./dist/commonjs/index.js",
+  "module": "./dist/esm/index.js"
+}

package/src/agent.ts

@@ -0,0 +1,3 @@
+import { Boot } from './lib/boot.js';
+
+export default Boot;

package/src/app.ts

@@ -0,0 +1,3 @@
+import { Boot } from './lib/boot.js';
+
+export default Boot;

package/src/config/config.default.ts

@@ -0,0 +1,17 @@
+import path from 'node:path';
+import { getSourceDirname } from '../lib/utils.js';
+
+export default {
+  /**
+   * watcher options
+   * @member Config#watcher
+   * @property {string} type - event source type
+   */
+  watcher: {
+    type: 'default', // default event source
+    eventSources: {
+      default: path.join(getSourceDirname(), 'lib', 'event-sources', 'default'),
+      development: path.join(getSourceDirname(), 'lib', 'event-sources', 'development'),
+    },
+  },
+};

package/src/config/config.local.ts

@@ -0,0 +1,5 @@
+export default {
+  watcher: {
+    type: 'development',
+  },
+};

package/src/config/config.unittest.ts

@@ -0,0 +1,5 @@
+export default {
+  watcher: {
+    type: 'development',
+  },
+};

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './lib/types.js';
+export * from './lib/watcher.js';
+export * from './lib/event-sources/index.js';

package/src/lib/boot.ts

@@ -0,0 +1,22 @@
+import type { Application, Agent, ILifecycleBoot } from 'egg';
+import { Watcher } from './watcher.js';
+
+export class Boot implements ILifecycleBoot {
+  #app: Application | Agent;
+  #watcher: Watcher;
+
+  constructor(appOrAgent: Application | Agent) {
+    this.#app = appOrAgent;
+    this.#watcher = this.#app.watcher = this.#app.cluster(Watcher, {})
+      .delegate('watch', 'subscribe')
+      .create(appOrAgent.config)
+      .on('info', (msg: string, ...args: any[]) => this.#app.coreLogger.info(msg, ...args))
+      .on('warn', (msg: string, ...args: any[]) => this.#app.coreLogger.warn(msg, ...args))
+      .on('error', (msg: string, ...args: any[]) => this.#app.coreLogger.error(msg, ...args));
+  }
+
+  async didLoad(): Promise<void> {
+    await this.#watcher.ready();
+    this.#app.coreLogger.info('[@eggjs/watcher:%s] watcher start success', this.#app.type);
+  }
+}

package/src/lib/event-sources/base.ts

@@ -0,0 +1,6 @@
+import { Base } from 'sdk-base';
+
+export abstract class BaseEventSource extends Base {
+  abstract watch(file: string): void;
+  abstract unwatch(file: string): void;
+}

package/src/lib/event-sources/default.ts

@@ -0,0 +1,18 @@
+import { BaseEventSource } from './base.js';
+
+export default class DefaultEventSource extends BaseEventSource {
+  constructor() {
+    super();
+    // delay emit so that can be listened
+    setImmediate(() => this.emit('info', '[@eggjs/watcher] defaultEventSource watcher will NOT take effect'));
+    this.ready(true);
+  }
+
+  watch() {
+    this.emit('info', '[@eggjs/watcher] using defaultEventSource watcher.watch() does NOTHING');
+  }
+
+  unwatch() {
+    this.emit('info', '[@eggjs/watcher] using defaultEventSource watcher.unwatch() does NOTHING');
+  }
+}

package/src/lib/event-sources/development.ts

@@ -0,0 +1,99 @@
+import { debuglog } from 'node:util';
+import path from 'node:path';
+import fs, { FSWatcher, WatchEventType } from 'node:fs';
+import { BaseEventSource } from './base.js';
+import type { ChangeInfo } from '../types.js';
+
+const debug = debuglog('@eggjs/watcher/lib/event-sources/development');
+
+// only used by local dev environment
+export default class DevelopmentEventSource extends BaseEventSource {
+  #fileWatching = new Map<string, FSWatcher>();
+
+  constructor() {
+    super();
+    this.ready(true);
+  }
+
+  watch(file: string) {
+    try {
+      const stat = fs.statSync(file, { throwIfNoEntry: false });
+      if (!stat) {
+        debug('watch %o ignore, file not exists', file);
+        return;
+      }
+      debug('watch %o, isFile: %o', file, stat.isFile());
+      // https://nodejs.org/docs/latest/api/fs.html#fswatchfilename-options-listener
+      let recursive = true;
+      if (process.platform === 'linux' && process.version.startsWith('v18.')) {
+        // https://github.com/fgnass/filewatcher/pull/6
+        // disable recursive on linux + Node.js <= 18
+        recursive = false;
+      }
+      const handler = fs.watch(file, {
+        persistent: true,
+        recursive,
+      }, (event, filename) => {
+        debug('watch %o => event: %o, filename: %o', file, event, filename);
+        let changePath = file;
+        if (stat.isFile()) {
+          this.#onFsWatchChange(event, changePath);
+        } else {
+          // dir
+          if (filename) {
+            changePath = path.join(file, filename);
+          }
+          this.#onFsWatchChange(event, changePath);
+        }
+      });
+      // 保存 handler，用于解除监听
+      this.#fileWatching.set(file, handler);
+    } catch (e) {
+      // file not exist, do nothing
+      // do not emit error, in case of too many logs
+      this.emit('warn', '[@eggjs/watcher:DevelopmentEventSource] watch %o error: %s', file, e);
+    }
+  }
+
+  unwatch(file: string) {
+    if (!file) return;
+
+    const h = this.#fileWatching.get(file);
+    if (!h) return;
+
+    // fs.watch 文件监听
+    h.removeAllListeners();
+    h.close();
+    this.#fileWatching.delete(file);
+  }
+
+  #onFsWatchChange(event: WatchEventType, file: string) {
+    if (!file) {
+      this.emit('warn', '[@eggjs/watcher:DevelopmentEventSource] event: %o', event);
+      return;
+    }
+    // { event: 'change',
+    // path: '/Users/mk2/git/changing/test/fixtures/foo.js',
+    // stat:
+    //  { dev: 16777220,
+    //    mode: 33188,
+    //    nlink: 1,
+    //    uid: 501,
+    //    gid: 20,
+    //    rdev: 0,
+    //    blksize: 4096,
+    //    ino: 72656587,
+    //    size: 11,
+    //    blocks: 8,
+    //    atime: Wed Jun 17 2015 00:08:11 GMT+0800 (CST),
+    //    mtime: Wed Jun 17 2015 00:08:38 GMT+0800 (CST),
+    //    ctime: Wed Jun 17 2015 00:08:38 GMT+0800 (CST),
+    //    birthtime: Tue Jun 16 2015 23:19:13 GMT+0800 (CST) } }
+    const info = {
+      path: file,
+      event,
+      stat: fs.statSync(file, { throwIfNoEntry: false }),
+    } as ChangeInfo;
+    this.emit('change', info);
+  }
+}

package/src/lib/event-sources/index.ts

@@ -0,0 +1,3 @@
+export * from './base.js';
+export * from './default.js';
+export * from './development.js';

package/src/lib/types.ts

@@ -0,0 +1,35 @@
+import type { WatchEventType, Stats } from 'node:fs';
+import type { Watcher } from './watcher.js';
+
+export interface WatcherConfig {
+  watcher: {
+    type: string;
+    eventSources: Record<string, string>;
+  };
+  [key: string]: Record<string, any>;
+}
+
+export interface ChangeInfo {
+  event: WatchEventType;
+  /**
+   * file stat if path exists
+   */
+  stat?: Stats;
+  path: string;
+}
+
+declare module 'egg' {
+  export interface EggWatcherAgent {
+    watcher: Watcher;
+  }
+  export interface Agent extends EggWatcherAgent {}
+
+  export interface EggWatcherApplication {
+    watcher: Watcher;
+  }
+  export interface Application extends EggWatcherApplication {}
+
+  export interface EggWatcherAppConfig extends WatcherConfig {}
+
+  export interface EggAppConfig extends EggWatcherAppConfig {}
+}

package/src/lib/utils.ts

@@ -0,0 +1,20 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// judge if parent is child's parent path
+// isEqualOrParentPath('/foo', '/foo/bar') => true
+// isEqualOrParentPath('/foo/bar', '/foo') => false
+export function isEqualOrParentPath(parent: string, child: string) {
+  return !path.relative(parent, child).startsWith('..');
+}
+
+export function getSourceDirname() {
+  if (typeof __dirname === 'string') {
+    return path.dirname(__dirname);
+  }
+
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+  // @ts-ignore
+  const __filename = fileURLToPath(import.meta.url);
+  return path.dirname(path.dirname(__filename));
+}

package/src/lib/watcher.ts

@@ -0,0 +1,117 @@
+import { debuglog } from 'node:util';
+import { Base } from 'sdk-base';
+import camelcase from 'camelcase';
+import { importModule } from '@eggjs/utils';
+import { BaseEventSource } from './event-sources/base.js';
+import { isEqualOrParentPath } from './utils.js';
+import type { ChangeInfo, WatcherConfig } from './types.js';
+
+const debug = debuglog('@eggjs/watcher/lib/watcher');
+
+export type WatchListener = (info: ChangeInfo) => void;
+
+export class Watcher extends Base {
+  #config: WatcherConfig;
+  #eventSource: BaseEventSource;
+
+  constructor(config: WatcherConfig) {
+    super({
+      initMethod: '_init',
+    });
+    this.#config = config;
+  }
+
+  protected async _init() {
+    const watcherType = this.#config.watcher.type;
+    let EventSource: typeof BaseEventSource = this.#config.watcher.eventSources[watcherType] as any;
+    if (typeof EventSource === 'string') {
+      EventSource = await importModule(EventSource);
+    }
+
+    // chokidar => watcherChokidar
+    // custom => watcherCustom
+    //
+    // e.g:
+    // config => { watcher: { type: 'custom' },  watcherCustom: { ... } }
+    const key = camelcase([ 'watcher', watcherType ]);
+    const eventSourceOptions = this.#config[key] ?? {};
+    this.#eventSource = Reflect.construct(EventSource, [ eventSourceOptions ]);
+    this.#eventSource.on('change', this.#onChange.bind(this))
+      .on('fuzzy-change', this.#onFuzzyChange.bind(this))
+      .on('info', (...args) => this.emit('info', ...args))
+      .on('warn', (...args) => this.emit('warn', ...args))
+      .on('error', (...args) => this.emit('error', ...args));
+    await this.#eventSource.ready();
+  }
+
+  watch(path: string | string[], listener: WatchListener) {
+    this.emit('info', '[@eggjs/watcher] Start watching: %j', path);
+    if (!path) return;
+
+    // support array
+    if (Array.isArray(path)) {
+      path.forEach(p => this.watch(p, listener));
+      return;
+    }
+
+    // one file only watch once
+    if (!this.listenerCount(path)) {
+      this.#eventSource.watch(path);
+    }
+    this.on(path, listener);
+  }
+
+  /*
+  // TODO wait unsubscribe implementation of cluster-client
+  unwatch(path, callback) {
+    if (!path) return;
+
+    // support array
+    if (Array.isArray(path)) {
+      path.forEach(p => this.unwatch(p, callback));
+      return;
+    }
+
+    if (callback) {
+      this.removeListener(path, callback);
+      // stop watching when no listener bound to the path
+      if (this.listenerCount(path) === 0) {
+        this._eventSource.unwatch(path);
+      }
+      return;
+    }
+
+    this.removeAllListeners(path);
+    this._eventSource.unwatch(path);
+  }
+  */
+
+  #onChange(info: ChangeInfo) {
+    debug('onChange %o', info);
+    this.emit('info', '[@eggjs/watcher] Received a change event from eventSource: %j', info);
+    const path = info.path;
+
+    for (const p of this.eventNames()) {
+      if (typeof p !== 'string') continue;
+      // if it is a sub path, emit a `change` event
+      if (isEqualOrParentPath(p, path)) {
+        this.emit(p, info);
+      }
+    }
+  }
+
+  #onFuzzyChange(info: ChangeInfo) {
+    debug('onFuzzyChange %o', info);
+    this.emit('info', '[@eggjs/watcher] Received a fuzzy-change event from eventSource: %j', info);
+    const path = info.path;
+
+    for (const p of this.eventNames()) {
+      if (typeof p !== 'string') continue;
+      // if it is a parent path, emit a `change` event
+      // just the opposite to `_onChange`
+      if (isEqualOrParentPath(path, p)) {
+        this.emit(p, info);
+      }
+    }
+  }
+}