Javascript事件总线库mitt的源码指南

/*
 * 创建事件发射器，用于注册、移除和触发事件
 * @param {Map} all - 存储所有事件类型及其对应的处理函数的 Map 对象
 * @returns {Object} - 包含 all、on、off 和 emit 方法的对象
 */
function mitt(all) {
  all = all || new Map();

  return {
    // 事件名称与已注册的处理函数之间的映射表
    all,

    /**
     * 注册事件处理函数
     * @param {string} type - 要监听的事件类型（用 '*'表示所有事件）
     * @param {function} handler - 响应指定事件时要调用的函数
     */
    on(type, handler) {
      // 获取事件类型对应的处理函数列表
      const handlers = all.get(type);
      // 已有处理函数，将新处理函数添加到处理函数列表；没有，则用新处理函数初始化处理函数列表
      if (handlers) {
        handlers.push(handler);
      } else {
        all.set(type, [handler]);
      }
    },

    /**
     * 注销事件处理函数
     * 如果省略 handler，则会注销所有指定类型的处理程序
     * @param {string} type - 要注销注册 handler的事件类型（用 '＊'删除通配符处理程序）
     * @param {function} handler - 要注销的处理函数
     */
    off(type, handler) {
      const handlers = all.get(type);
      if (handlers) {
        // 如果指定了要注销的事件处理函数，从处理函数列表中移除它；
        // 未指定，则将该事件类型的处理函数列表清空
        if (handler) {
          handlers.splice(handlers.indexOf(handler) >>> 0, 1);
        } else {
          all.set(type, []);
        }
      }
    },

    /**
     * 触发事件，调用指定类型的所有处理程序。
     * 如果存在，将在匹配类型的处理程序之后调用 '*' 处理程序。
     * 
     * 注意：不支持手动触发 '*' 处理程序
     * @param {string} type - 要触发的事件类型
     * @param {any} evt - 传递给每个事件处理函数的参数（推荐对象）
     */
    emit(type, evt) {
      let handlers = all.get(type);
      if (handlers) {
        // 如果有处理函数，依次调用处理函数并传入参数
        // 注：使用 slice 函数用于创建数组的副本，避免影响原始列表
        handlers
          .slice()
          .map((handler) => {
            handler(evt);
          });
      }

      // 获取通配符事件类型对应的处理函数列表，有则依次调用并传参
      handlers = all.get('*');
      if (handlers) {
        handlers
          .slice()
          .map((handler) => {
            handler(type, evt);
          });
      }
    },
  };
}

const emitter = mitt()

// 监听一个事件
emitter.on('foo', e => console.log('foo', e) )

// 监听所有事件
emitter.on('*', (type, e) => console.log(type, e) )

// 触发一个事件
emitter.emit('foo', { a: 'b' })

// 清除所有事件
emitter.all.clear()

// 使用处理函数引用
function onFoo() {}
emitter.on('foo', onFoo)   // 监听
emitter.off('foo', onFoo)  // 移除监听

handlers.splice(handlers.indexOf(handler) >>> 0, 1);

handlers.slice().map((handler) => {
  handler(evt);
});

export type EventType = string | symbol;

// 事件处理器，可选的事件参数，不返回值
export type Handler<T = unknown> = (event: T) => void;
// 定义一个通用的事件处理函数类型，可以处理多种不同类型的事件
export type WildcardHandler<T = Record<string, unknown>> = (
 type: keyof T, // 必须是 T 类型中的某个属性名称
 event: T[keyof T] // 必须是 T 类型中所有属性值的联合类型
) => void;

// 一个包含当前已注册的某种类型事件处理程序的数组
export type EventHandlerList<T = unknown> = Array<Handler<T>>;
export type WildCardEventHandlerList<T = Record<string, unknown>> = Array<WildcardHandler<T>>;

// 一个 Map 类型，用于存储事件类型及其处理函数列表
// 在 TypeScript 中，Map 是一个泛型类型，可以指定键和值的类型。例如，Map<string, number> 表示一个键为字符串类型，值为数字类型的 Map 对象。
export type EventHandlerMap<Events extends Record<EventType, unknown>> = Map<
  keyof Events | '*',
  // EventHandlerList<Events[keyof Events]> 表示一个处理 Events[keyof Events] 类型事件的处理函数列表，也就是说，事件类型为 Events 中所有属性值的联合类型。
  // WildCardEventHandlerList<Events> 表示一个处理所有事件类型的处理函数列表
  EventHandlerList<Events[keyof Events]> | WildCardEventHandlerList<Events>
>;

export interface Emitter<Events extends Record<EventType, unknown>> {
  all: EventHandlerMap<Events>;

  on<Key extends keyof Events>(type: Key, handler: Handler<Events[Key]>): void;
  // 通配符事件类型 '*' 的重载
  on(type: '*', handler: WildcardHandler<Events>): void;

  off<Key extends keyof Events>(type: Key, handler?: Handler<Events[Key]>): void;
  off(type: '*', handler: WildcardHandler<Events>): void;

  emit<Key extends keyof Events>(type: Key, event: Events[Key]): void;
  emit<Key extends keyof Events>(type: undefined extends Events[Key] ? Key : never): void;
}

function mitt<Events extends Record<EventType, unknown>>(all?: EventHandlerMap<Events>): Emitter<Events> {
  // 两种事件处理器的联合类型
  type GenericEventHandler =| Handler<Events[keyof Events]> | WildcardHandler<Events>;

  return {
    on<Key extends keyof Events>(type: Key, handler: GenericEventHandler) {/*...*/},
    off<Key extends keyof Events>(type: Key, handler?: GenericEventHandler) {/*...*/},
    emit<Key extends keyof Events>(type: Key, evt?: Events[Key]) {/*...*/}
  };
}

{
  "scripts": {
    // 运行 "typecheck", "lint", "mocha" 和 "test-types" 命令
    "test": "npm-run-all --silent typecheck lint mocha test-types",
    // 运行 "test" 目录下的 mocha 测试
    "mocha": "mocha test",
    // 运行 TypeScript 编译器，检查 test/test-types-compilation.ts 文件的类型，但不生成任何输出
    "test-types": "tsc test/test-types-compilation.ts --noEmit --strict",
    // 运行 ESLint 检查 src 和 test 目录下的 .ts 和 .js 文件
    "lint": "eslint src test --ext ts --ext js",
    // 运行 TypeScript 编译器，检查 TypeScript 代码的类型，但不生成任何输出
    "typecheck": "tsc --noEmit",
    // 使用 microbundle 将模块打包成 ES、CommonJS 和 UMD 格式
    "bundle": "microbundle -f es,cjs,umd",
    // 运行 "clean", "bundle" 和 "docs" 命令
    "build": "npm-run-all --silent clean -p bundle -s docs",
    // 删除 dist 目录
    "clean": "rimraf dist",
    // 使用 documentation 工具生成 API 文档
    "docs": "documentation readme src/index.ts --section API -q --parse-extension ts",
    // 运行 "build", "test" 命令，提交代码，打标签，推送到 Git 仓库，发布到 npm
    "release": "npm run -s build -s && npm t && git commit -am $npm_package_version && git tag $npm_package_version && git push && git push --tags && npm publish"
  }
}

{
  "mocha": {
    // 指定测试文件的扩展名为 ".ts"
    "extension": [
      "ts"
    ],
    // 指定需要在测试运行前加载的模块。这里指定了 "ts-node/register" 和 "esm" 模块，它们分别用于支持 TypeScript 和 ES modules
    "require": [
      "ts-node/register",
      "esm"
    ],
    // 指定测试文件的位置，这里表示所有以 "_test.ts" 结尾的文件都会被作为测试文件运行
    "spec": [
      "test/*_test.ts"
    ]
  },
}

{
  "eslintConfig": {
    // 指定一个或多个已有的ESLint配置文件，以便继承其中的规则和选项
    "extends": [
      "developit",
      // plugin: 表示对 @typescript-eslint 插件下的某一类配置对象的引用
      "plugin:@typescript-eslint/eslint-recommended",
      "plugin:@typescript-eslint/recommended"
    ],
    // 专门用于解析 TypeScript 代码的解析器
    "parser": "@typescript-eslint/parser",
    "parserOptions": {
      // 要解析的代码是 ES6 模块
      "sourceType": "module"
    },
    "env": {
      "browser": true,
      "mocha": true,
      "jest": false,
      "es6": true
    },
    // 指定了 expect 变量为全局变量，用于在测试中使用断言库
    "globals": {
      "expect": true
    },
    "rules": {
      // ...
    }
  },
  // 指定ESLint应该忽略的文件或目
  "eslintIgnore": [
    "dist",
    "index.d.ts"
  ]
}

{
  // 定义了 ES6 模块规范的入口文件。当使用现代打包工具（如 webpack、Rollup 等）构建项目时，会自动使用这个属性指定的文件作为入口，以支持 ES6 模块的导入和导出。
  "module": "dist/mitt.mjs",
  // 定义了 CommonJS 规范的入口文件。当使用 Node.js 运行时或者其他支持 CommonJS 规范的环境时，会自动使用这个属性指定的文件作为入口。
  "main": "dist/mitt.js",
  // 定义了 ES6 模块规范的入口文件。这个属性主要是为了向老版本的打包工具提供兼容性支持，因为老版本的打包工具不支持 module 属性。
  "jsnext:main": "dist/mitt.mjs",
  // 定义了 UMD 规范的入口文件。当使用不支持 ES6 模块或 CommonJS 规范的环境时，会自动使用这个属性指定的文件作为入口。
  "umd:main": "dist/mitt.umd.js",
  // 定义了源代码文件的入口。这个属性通常用于调试和开发环境，因为它可以让开发者在调试时直接跳转到源代码文件，而不是跳转到编译后的文件。
  "source": "src/index.ts",
  // 定义了 TypeScript 类型定义文件的路径。这个属性通常用于 TypeScript 项目，它告诉 TypeScript 编译器在编译时需要将这个文件作为类型定义文件使用。
  "typings": "index.d.ts",
  // 定义了模块的导出方式。是可以指定多个导出方式的对象，包括 import、require、types 和 default。以便在不同的环境下使用不同的导出方式，以适应不同的场景。
  "exports": {
    "types": "./index.d.ts",
    "import": "./dist/mitt.mjs",
    "require": "./dist/mitt.js",
    "default": "./dist/mitt.mjs"
  },
  // 用于指定哪些文件是该模块的一部分，这些文件将会被打包到该模块中，以便在其他项目中使用。
  // 默认情况下，所有文件都会被打包到该模块中，包括 node_modules 目录和测试文件等。
  "files": [
    "dist",
    "index.d.ts"
  ],
}

# 定义名为 CI 的工作流
name: CI

on:
  # 当有新的 pull request 提交时，且提交的分支名符合 ** 通配符模式时；
  pull_request:
    branches:
      - "**"
  # 当在 main 分支上进行 push 操作时。
  push:
    branches:
      - main

jobs:
  # 定义名为 build 作业（job）
  build:
    # 指定运行环境为 ubuntu-latest
    runs-on: ubuntu-latest
    # 定义步骤
    steps:
      # 使用 actions/checkout@v2 动作来检出代码库
      - uses: actions/checkout@v2
      # 使用 actions/setup-node@v2 动作来安装 Node.js 运行环境，指定版本为 14
      - uses: actions/setup-node@v2
        with:
          node-version: 14
      # 定义一个名为 npm install, build, and test 的步骤
      - name: npm install, build, and test
        # 包含以下命令
        run: |
          npm install
          npm run build --if-present # 如果有定义 build 命令，则运行该命令，用于打包构建项目；
          npm test
        # 定义一个名为 CI 的环境变量，将其值设为 true
        env:
          CI: true