todo

该 npm包 未使用任何脚手架，使用typescript开发源代码，mocha测试
为后续写npm包参考与学习之用，撰此文档
属于是开山之作了属于是

√ 1.新建文件夹 bimap_reconstruction
    预计使用 ts 编码，mocha 测试，最后产出可以使用 commonjs、es6+ 语法导入的 npm 包
    RootDir
      /dist ------------ 由 tsc 编译 ts 代码产出的 js 代码，作为 npm 包的最终内容
      /src ------------- 源代码都在这里了，使用 ts 编写
      /test ------------ 测试用的代码，使用 ts 编写，使用 mocha 执行
      /entry ----------- 不同模块语法对应入口文件，配合 package.json 中 export 使用
      .gitignore ------- git 推送仓库时的忽略项
      .eslintrc.js ----- eslint 配置项，使用了针对 ts 的 plugin 和 parser，配置了代码规范
      .npmignore ------- npm 发包时的忽略项，和包实际功能不挂钩的都应该忽略
      .package.json ---- npm 对该包的描述，主要的内容是 script 和 export 标签，配置了方便实用的命令集和模块化导入的入口文件
      .todo ------------ 开山之作的详细踩坑解说
      .tsconfig.json --- 配置 tsc 的运行参数，主要配置了输出目录 outDir、模块化语法 commonjs 和编译后的 js 语法版本 es2015
      .README.md ------- 该包的使用文档、教程等

    好！理清思路，从空文件夹开始吧！

√ 2.初始化 package.json
    开始初始化npm包，cd进根目录后使用
    > npm init
    按部就班的完成问题后得到
    RootDir
      /src ------------- 手动新建
      /test ------------ 手动新建
      /entry ----- ----- 手动新建
      .package.json ---- 它包含了一些基本信息，你包的版本、名称、仓库地址、作者等等
    
    package.json文件中对我们来说比较重要的就是
    {
      ...
      "script": { "test": "echo 'xxx' && exit -1" },
      "exports": {}, // 你可能还没有，加之
      "devDependencies": {}
    }
    script标签可以用于简化命令行里你需要敲的命令
    默认的内容就是很好的例子，你可以使用
    > npm run test || npm test
    来快捷的执行 `echo 'xxx' && exit -1`
    export标签可以指定本npm包再被导入时具体的入口文件
    例如，别人使用 npm 下载了你的包，需要使用 require(即commonjs) 语法导入
    你可以指定 "exports": { "require": "./index.js" } 让 index.js 作为入口
     
√ 3.初始化以及配置 typescript
    需要使用ts编写代码，那就先安装依赖，使用
    > npm i --save-dev typescript // 安装开发环境的依赖
    由于稍后会用到 node 内置的 require、assert 等内容来进行开发、测试，而 ts 并不识别
    同样的，稍后会用到 mocha 内置的 describe 等内容进行测试，ts 亦不识别
    因此安装 node 环境和 mocha 的 types 以供 ts 识别这些内容，使用 
    > npm i -D @types/node @types/mocha

    前置工作完成，使用
    > node_modules/.bin/tsc.cmd init // (for windows)初始化 tsconfig.json 文件，得到
    RootDir
      ...
      .tsconfig.json --- tsconfig.json 文件是 tsc 编译器编译 ts 时的选项
    tsc编译器会优先使用 cwd(当前工作目录) 下的tsconfig配置，找不到则逐级向上查找
    因此，想让不同的文件夹对应不同的配置只需要在他们的根目录下创建配置文件

    对于src下的文件，我们想让编译后的js代码是es2015版本的代码，并且js代码和d.ts声明文件都在dist文件夹下
    同时，该包编译后计划使用 commonjs 模块语法来实现模块化
    .tsconfig.json
    {
      "compilerOptions": {
        ...
        "target": "es2015",
        "outDir": "dist",
        "module": "CommonJs"
      },
      "include": ["src/*"] // 将只包含src下的文件
    }

    对于test下的文件，我们应该给它们一个独立于根目录tsconfig的配置，但又想复用已经写好的规则，可以使用extend属性来实现
    test/tsconfig.json
    {
      "extends": "../tsconfig.json",
      "include": "**/*", // 让 编辑器 识别test下的文件并给予自动补全等功能
    }
    对于这部分测试用的代码，我们将不进行编译，而是使用ts-node包直接执行它，详情见第4步

    之所以将test、src分开是由于
      1 逻辑上，只应该将源代码进行编译并发包，其他功能的代码不应参与
      2 后续的测试代码虽不需要额外进行编译，但是需要编辑器等对这部分代码识别，因此需要配置文件配置它们
    最后的文件结构形如
    RootDir
      ...
      /test
        .tsconfig.json - test使用的配置
      .tsconfig.json --- src使用的配置

√ 4.初始化以及配置 mocha
    mocha是一个测试框架，我们用来测试自己的代码过不过关，首先安装至开发依赖
    > npm i --save-dev mocha
    mocha需要配合断言库一起使用，我们就使用node自带的assert断言库即可
    由于mocha直接执行js代码，而测试的ts代码我们计划直接执行，不进行额外的编译，因此我们需要直接执行ts文件的包
    > npm i --save-dev ts-node
    我们将在mocha执行时将ts-node/register作为新的编译器从而让mocha直接执行ts
    这需要我们在命令行里将它作为参数传给mocha，稍后我们在第7步涉及到

√ 5.初始化 eslint
    需要使用 eslint 规范化代码，先使用
    > npm i --save-dev eslint // 安装依赖
    > node_modules/.bin/eslint.cmd init // 初始化并根据问题客制化代码规范细则
    执行完上述命令后，eslint会根据我们对问题的回答给我们生成一个推荐的初始配置文件
    RootDir
      ...
      .eslintrc.json // 本应是js文件，为了与其他配置文件后缀统一，我们改成json
    
    在init后的问答过程中，对ts相关的问题回答 ‘是’ 后会自行安装typescript配套的parser、plugin并在配置文件中应用
    这些配置对于我来说，推荐差不多就够用，但我不喜欢双引号以及句末的分号，因此现在我的eslintrc.json形如
    .eslintrc.json
    {
      ...
      "extends": [
        "eslint:recommended",
        "plugin:@typescript-eslint/recommended"
      ],
      "rules": {
        "quotes": [ // 单引号万岁！
          "error",
          "single"
        ],
        "semi": [ // 能不写分号就不写
          "error",
          "never"
        ]
      },
      "ignorePatterns": "dist/*" // 忽略对 dist 文件下内容的检查，因为它们是打包产物
    }
    
    接下来即可根据自己的需要配置rules等，相关配置可在官网查找

√ 6.初始化 git
    git是代码管理工具，后续团队或个人对代码的维护都需要它
    > git init // 初始化git
    > git remote add origin https://yourgitaddress // 为本地仓库添加远程仓库
    接下来就可以使用 git 来提交、拉取仓库信息啦

    同时，添加gitignore文件来控制默认需要被提交的文件
    对于该包，我们将dist下的文件忽略掉，毕竟他没有太大的阅读价值，将node_modules忽略掉
    .gitignore
      node_modules
      dist/
    
    最后的文件结构形如
    RootDir
      ...
      .gitignore

√ 7.在 package.json 添加内容
    由于后续可能经常用到tsc和mocha进行编译与测试，因此我们需要添加两个脚本用于编译和测试
    .package.json
    {
      ...
      "script": {
        "compile": "tsc", // 读取根目录的tsconfig文件并编译，即只编译src下的文件
        "test": "mocha --require ts-node/register test/**/*.ts" // 令mocha使用ts-node的register作编译器执行test下的文件
      }
    }

    由于该包计划支持commonjs和es6 module，因此需要有他们的入口文件，comminjs已是编译后的模块化语法，es6 module则对应.mjs
    .package.json
    {
      ...
      "exports": {
        "import": "./entry/esmodule.mjs", // 使用import导入时
        "require": "./dist/index.js" // 使用require导入时
        "default": "./dist/index.js", // 使用非import、require导入时
      }
    }

√ 8.添加说明文件及其他附属文件
    经过上面这些步骤，我们对包的开发和测试已经配置的差不多了，剩下的就是
    (1) 他人如何使用该包，README.md里可以写这些内容
    (2) 减小发包时不必要的代码，在npmignore里配置忽略项
    (3) 其他想加的东西，比如这个todo

    最后的文件结构形如
    RootDir
      /src
      /test
      /entry
      .gitignore
      .eslintrc.js
      .npmignore
      .package.json
      .tsconfig.json
      .README.md

√ 9. 开发代码并测试流程是否通过
    现在，在src中开发源代码之后...
    > npm run compile
    即可将src下的代码编译到dist目录中，形如
    RootDir
      dist ------------ 自动创建
    在命令行使用
    > npm link your_package_name // 将自己这个包局部链接到node_modules下
    链接之后，可以在test文件夹中的测试文件里使用
    test/importtest.ts
      import TEST from 'your_package_name'
    顺便测试下能不能成功导入之类的，后续想取消链接仅需
    > npm unlink your_package_name // 取消这个局部链接

    然后，在开发完测试代码之后...
    > npm test
    即可查看测试是否通过！


一个具备ts、语法检查、测试的npm包，就这样从零到一的写出来啦！
当然，你可以把上述的过程再写成npm包，用作后续开发这类包的脚手架，总之，随意发挥~