eggjsegg-ts-helper
一个帮助 egg 生成 d.ts 的工具，通过 ts 提供的 Declaration Merging 能力来将 controller, proxy, service 等等 这些 egg 中动态加载的模块注入到 egg 的声明中。从而获得类型校验以及代码提示。
安装
打开应用目录并且安装
npm i egg-ts-helper --save-dev
快速开始
打开你的 egg 应用，通过 npx 来执行 ets 指令
npx ets
可以通过 -w 来监听文件改动并且重新生成 d.ts
npx ets -w
egg-ts-helper 已经内置在 egg-bin 中，可以通过以下命令方便使用
egg-bin dev --dts
再或者在 package.json 中配置 egg.declarations 为 true 即可。
命令行
$ ets -h
Usage: ets [commands] [options]
Options:
-v, --version 版本号
-w, --watch 是否监听文件改动
-c, --cwd [path] Egg 的项目目录，(默认值: process.cwd)
-C, --config [path] 配置文件，入参应该是合法的 JSON/JS 文件 (默认值: {cwd}/tshelper)
-o, --oneForAll [path] 创建一个 import 了所有生成的 d.ts 的声明 (默认值: typings/ets.d.ts)
-s, --silent 静默执行，不输出日志
-i, --ignore [dirs] 忽略 generator 中的相关配置，可以通过逗号配置忽略多个，比如: -i controller,service
-e, --enabled [dirs] 开启 generator 中的相关配置， 可以通过逗号配置忽略多个，比如: -e proxy,other
-E, --extra [json] 额外配置，可以是 json 字符串
-h, --help 帮助
Commands:
clean 清除所有包含同名 ts/tsx 文件的 js 文件
init <type> 在你的项目中初始化 egg-ts-helper
配置
| name | type | default | description | |
|---|---|---|---|---|
| cwd | string |
process.cwd | Egg 的项目目录 | |
| typings | string |
{cwd}/typings | 生成的声明放置目录 | |
| caseStyle | string Function |
lower | egg 的模块命名方式 (lower (首字母小写), upper (首字母大写), camel (驼峰) ) ，也可以传方法 (filename) => {return 'YOUR_CASE'} |
|
| silent | boolean |
false | 静默执行，不输出日志 | |
| watch | boolean |
false | 是否监听文件改动，使用 register 的话该值默认为 true |
|
| watchOptions | object |
undefined | chokidar 的配置 | |
| configFile | string |
{cwd}/tshelper.(js | json) | 配置文件路径 |
| generatorConfig | object |
生成器配置 |
可以在 ./tshelper.js ./tshelper.json 或者 package.json 中配置上面的配置
在 tshelper.js
// {cwd}/tshelper.js
module.exports = {
generatorConfig: {
model: {
enabled: true,
generator: "function",
interfaceHandle: "InstanceType<{{ 0 }}>"
},
}
}
在 tshelper.json
// {cwd}/tshelper.json
{
"generatorConfig": {
"model": {
"enabled": true,
"generator": "function",
"interfaceHandle": "InstanceType<{{ 0 }}>"
},
}
}
在 package.json
// {cwd}/package.json
{
"egg": {
"framework": "egg",
"tsHelper": {
"generatorConfig": {
"model": {
"enabled": true,
"generator": "function",
"interfaceHandle": "InstanceType<{{ 0 }}>"
},
}
}
}
}
同时也可以通过环境变量来传入配置 ( 1.22.0 版本后开始支持 )
ETS_CWD: cwdETS_FRAMEWORK: frameworkETS_TYPINGS: typingsETS_CASE_STYLE: caseStyleETS_AUTO_REMOVE_JS: autoRemoveJsETS_THROTTLE: throttleETS_WATCH: watchETS_SILENT: silentETS_CONFIG_FILE: configFile
Custom Loader
在 1.24.0 之后版本支持
egg-ts-helper 支持 egg 的 customLoader 配置，会自动去读取应用/插件/框架中的 customLoader 配置. 详情请看 https://github.com/eggjs/egg/issues/3480
在 config.default.ts 中配置 customLoader
'use strict';
import { EggAppConfig, PowerPartial } from 'egg';
export default function(appInfo: EggAppConfig) {
const config = {} as PowerPartial<EggAppConfig>;
config.keys = appInfo.name + '123123';
config.customLoader = {
model: {
directory: 'app/model',
inject: 'app',
caseStyle: 'upper',
},
};
return {
...config as {},
...bizConfig,
};
}
egg-ts-helper 将会根据 app/model 目录下的文件，自动生成声明 （ 参考 https://github.com/whxaxes/egg-boilerplate-d-ts 这个项目 ）
// This file is created by egg-ts-helper@1.24.1
// Do not modify this file!!!!!!!!!
import 'egg';
type AutoInstanceType<T, U = T extends (...args: any[]) => any ? ReturnType<T> : T> = U extends { new (...args: any[]): any } ? InstanceType<U> : U;
import ExportCastle from '../../../app/model/Castle';
import ExportUser from '../../../app/model/User';
declare module 'egg' {
interface Application {
model: T_custom_model;
}
interface T_custom_model {
Castle: AutoInstanceType<typeof ExportCastle>;
User: AutoInstanceType<typeof ExportUser>;
}
}
然后你就可以愉快的在代码中使用了。
Generator
如果需要支持老的 customLoader 方式（ 即指在 app.ts 等中调用 loader.loadToApp 或者 loader.loadToContext 的方式实现的 customLoader ），则需要使用 egg-ts-helper 生成器配置。
示例
比如需要给 app/model 下的文件创建 d.ts，则需要在你的配置文件中配置一下 generatorConfig.model。
// ./tshelper.js
module.exports = {
generatorConfig: {
model: {
directory: 'app/model', // 监听目录
// pattern: '**/*.(ts|js)', // 遍历的文件表达式，一般都不需要改这个
// ignore: '', // 指定忽略某些文件的表达式，默认为空
generator: 'class', // 生成器名称，取值为 class、auto、function、object
interface: 'IModel', // interface 名称，如果不填的话，将会随机生成个 interface
declareTo: 'Context.model', // 指定定义到 egg 的某个类型下
// watch: true, // 是否需要监听文件改动
// caseStyle: 'upper', // 模块命名格式
// interfaceHandle: val => `ReturnType<typeof ${val}>`, // interface 预处理方法
// trigger: ['add', 'unlink'], // 当接收到这些文件更改事件的时候，会触发 d.ts 的重新生成, 所有事件: ['add', 'unlink', 'change']
}
}
}
使用上面的配置，会生成下面这个 d.ts
注意，上面的 generator 是 class ，生成的声明即会对 import 进来的类型直接挂载，不会做任何处理，如果不了解这个，请配置
auto类型。
import Station from '../../../app/model/station'; // <-- 遍历 app/model 目录并且 import
declare module 'egg' {
interface Context { // <-- 这个 Context 是读配置中的 declareTo
model: IModel; // <-- 这个 IModel 是读配置中的 interface ，如果不传，会随机生成个 interface
}
interface IModel { // <-- 这个 IModel 同上
Station: Station; // <-- 将 app/model 中的文件 import 挂载到 IModel 上，从而将类型合并到 ctx.model 中
}
}
不同配置的效果
interface string
interface 设置为 IOther.
interface IOther {
Station: Station;
}
如果不设置 interface 将会使用随机的名称
interface T100 {
Station: Station;
}
这种情况下请一定要配置 declareTo，不然就没意义了。
generator string
生成器名称，watcher 监听到文件改动的时候会执行该生成器用来重新生成 d.ts，可以使用的生成器名称为 class function object auto 。下面列举一下不同生成器生成的声明有什么不同。
generator: 'class'
生成的声明如下
interface IModel {
Station: Station; // 不做任何处理，直接挂载
}
适合这样写的模块
export default class XXXController extends Controller { }
generator: 'function' ( 1.16.0 开始支持 )
生成的声明如下
interface IModel {
Station: ReturnType<typeof Station>; // 使用 ReturnType 获得方法的返回类型
}
适合这样写的模块
export default () => {
return {};
}
generator: 'object' ( 1.16.0 开始支持 )
生成的声明如下
interface IModel {
Station: typeof Station; // 使用 typeof 获得对象的原始类型。
}
适合这样写的模块
export default {}
generator: 'auto' ( 1.19.0 开始支持 )
生成的声明如下，自动判断 import 的类型是方法还是对象还是类，即用了这个，你就不用管 export 的是方法还是对象还是类了，对类型了解不清楚的可以直接用这个。
type AutoInstanceType<T, U = T extends (...args: any[]) => any ? ReturnType<T> : T> = U extends { new (...args: any[]): any } ? InstanceType<U> : U;
interface IModel {
Station: AutoInstanceType<typeof Station>;
}
适合上面描述的所有模块。
interfaceHandle function|string
如果在 generator 中找不到合适的生成器类型，可以通过该配置对类型进行预处理。
module.exports = {
generatorConfig: {
model: {
...
interfaceHandle: val => `${val} & { [key: string]: any }`,
}
}
}
生成的声明如下
interface IModel {
Station: Station & { [key: string]: any };
}
这个配置也可以是字符串 ( 1.18.0 开始支持 )
module.exports = {
generatorConfig: {
model: {
...
interfaceHandle: '{{ 0 }} & { [key: string]: any }',
}
}
}
生成的声明跟前面方法那个一样，{{ 0 }} 代表方法的第一个入参。
caseStyle function|string
caseStyle 可以设置为 lower、upper、camel 或者是方法。
declareTo string
可以将生成的声明定义到 egg 的类型中，比如 egg 的 ctx 的类型是 Context ，就可以配置到 Context 下，然后通过 ctx.xxx 就可以拿到提示了。 ( 1.15.0 开始支持 )
declareTo 设置为 Context.model，然后就可以通过 ctx.model.xxx 拿到代码提示了
import Station from '../../../app/model/station';
declare module 'egg' {
interface Context {
model: IModel;
}
interface IModel {
Station: Station;
}
}
declareTo 设置为 Application.model.subModel，然后就可以通过 app.model.subModel.xxx 拿到代码提示了
import Station from '../../../app/model/station';
declare module 'egg' {
interface Application {
model: {
subModel: IModel;
}
}
interface IModel {
Station: Station;
}
}
自定义生成器
// ./tshelper.js
// 自定义 generator
function myGenerator(config, baseConfig) {
// config.dir dir
// config.dtsDir d.ts 目录
// config.file 发生更改的文件 file
// config.fileList path 下的文件列表
console.info(config);
console.info(baseConfig);
// 返回值可以是对象或者数组 { dist: string; content: string } | Array<{ dist: string; content: string }>
// 如果返回的 content 是 undefined，egg-ts-helper 会删除 dist 指向的文件
return {
dist: 'd.ts file url',
content: 'd.ts content'
}
}
module.exports = {
generatorConfig: {
model: {
directory: 'app/model',
generator: myGenerator,
trigger: ['add', 'unlink'],
}
}
}
或者将自定义生成器定义到其他 js 中
// ./my-generator.js
module.exports.defaultConfig = {
// 默认的 watchDir config
}
// 自定义 generator
module.exports = (config, baseConfig) => {
// config.dir dir
// config.dtsDir d.ts 目录
// config.file 发生更改的文件 file
// config.fileList path 下的文件列表
console.info(config);
console.info(baseConfig);
// 返回值可以是对象或者数组 { dist: string; content: string } | Array<{ dist: string; content: string }>
// 如果返回的 content 是 undefined，egg-ts-helper 会删除 dist 指向的文件
return {
dist: 'd.ts file url',
content: 'd.ts content'
}
}
配置一下
// ./tshelper.js
module.exports = {
generatorConfig: {
model: {
directory: 'app/model',
generator: './my-generator',
trigger: ['add', 'unlink'],
}
}
}
示例项目
egg-ts-helper 可用于 egg 的 ts 和 js 项目.
TS 项目: https://github.com/whxaxes/egg-boilerplate-d-ts
JS 项目: https://github.com/whxaxes/egg-boilerplate-d-js
License
Contributors
Made with contributors-img.