Skip to content

Commit

Permalink
doc (TypeScript): Formation errors with missing translations (#3020)
Browse files Browse the repository at this point in the history
1) Some parts still aren't translated into English, so tranlate them
all.
2) There're some formations error in JSON snippets, so fix them all.
  • Loading branch information
Maledong authored and dead-horse committed Sep 20, 2018
1 parent abd8d12 commit c65a648
Show file tree
Hide file tree
Showing 2 changed files with 50 additions and 49 deletions.
51 changes: 26 additions & 25 deletions docs/source/en/tutorials/typescript.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,12 @@ title: TypeScript

> [TypeScript](https://www.typescriptlang.org/) is a typed superset of JavaScript that compiles to plain JavaScript.
For a large number of enterprises' applications, TypeScript's static type checking, intellisenses, friendly IDE are valuable. For more please see [System Research Report For TypeScript](https://juejin.im/post/59c46bc86fb9a00a4636f939)
For a large number of enterprises' applications, TypeScript's static type checking, intellisense, friendly IDE are valuable. For more please see [System Research Report For TypeScript](https://juejin.im/post/59c46bc86fb9a00a4636f939).

However, we've met some problems influencing users' experience when developing Egg in TypeScript:

* The most outstanding Loader Mechanism (Auto-loading) makes TS not analyze dependencies in static.
* How to validate and show intellisenses in `config.{env}.js`, when we modify settings by plug-in and these configurations are automatically merged?
* How to validate and show intellisense in `config.{env}.js`, when we modify settings by plug-in and these configurations are automatically merged?
* During the period of developing, `tsc -w` is created as an independent process to build up codes, it makes us entangled about where to save the temporary files, and the complicated `npm scripts`.
* How to map to the TS source files instead of compiled js files in unit tests, coverage tests and error stacks online?

Expand All @@ -17,20 +17,21 @@ This article mainly describes:
* **Developing principles of TS for the application layer.**
* **How do we solve the problem for developers with the help of the tool chain so that they have no scene about it and keep in consistency**

For more about this tossing process, please see [[RFC] TypeScript tool support](https://github.com/eggjs/egg/issues/2272)
For more about this tossing process, please see [[RFC] TypeScript tool support](https://github.com/eggjs/egg/issues/2272).

---

## Quick Start
Be a quick initialization through the boilerplate:

A quick initialization through the boilerplate:

```bash
$ npx egg-init --type=ts showcase
$ cd showcase && npm i
$ npm run dev
```

The boilerplate above will create a very simple example, for a detailed one please see[eggjs/examples/hackernews-async-ts](https://github.com/eggjs/examples/tree/master/hackernews-async-ts)
The boilerplate above will create a very simple example, for a detailed one please see [eggjs/examples/hackernews-async-ts](https://github.com/eggjs/examples/tree/master/hackernews-async-ts)

![tegg.gif](https://user-images.githubusercontent.com/227713/38358019-bf7890fa-38f6-11e8-8955-ea072ac6dc8c.gif)

Expand Down Expand Up @@ -133,7 +134,7 @@ export default function robotMiddleware() {
}
```

`Middlewares` support input parameters, and the first one is the `config` of the same name. If you have other requirements, a full version is needed:
Middlewares support input parameters, and the first one is the config of the same name. If you have other requirements, a full version is needed:

```typescript
// app/middleware/news.ts
Expand Down Expand Up @@ -172,11 +173,11 @@ export default app => {

### Config

`Config` is a little complicated, because it supports:
Config is a little complicated, because it supports:

* In Controller, Service we need "multi-layer" intellisense configurations, they are automatically related to each other.
* In Config, `config.view = {}` will also support intellisenses.
* In `config.{env}.ts`, we can use customized configuration settings with intellisenses in `config.default.ts`.
* In Controller and Service, we need "multi-layer" intellisense configurations, they are automatically related to each other.
* In Config, `config.view = {}` will also support intellisense.
* In `config.{env}.ts`, we can use customized configuration settings with intellisense in `config.default.ts`.

```typescript
// app/config/config.default.ts
Expand Down Expand Up @@ -233,7 +234,7 @@ export default () => {

Remarks:

* `Conditional Types` is the KEY to solving config's intellisenses.
* `Conditional Types` is the KEY to solving config's intellisense.
* Anyone if interested in this, have a look at the implement of `PowerPartial` at [egg/index.d.ts](https://github.com/eggjs/egg/blob/master/index.d.ts).

```typescript
Expand All @@ -245,7 +246,7 @@ type PowerPartial<T> = {
};
```

### Plugin
### Plug-in

```javascript
// config/plugin.ts
Expand Down Expand Up @@ -292,7 +293,7 @@ Developers only need to config in `package.json` simply:

### egg-ts-helper

Due to the automatic loading mechanism, TS cannot analyze dependencies in static or relationship intellisenses.
Due to the automatic loading mechanism, TS cannot analyze dependencies in static or relationship intellisense.

Luckily, TS has many tricks to cope with it. We can use [Declaration Merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html) to write `d.ts` as a helper.

Expand All @@ -313,11 +314,11 @@ It's a bit too bothering to write them manually, so we offer you a tool [egg-ts-

What we do is just to do some configs in `package.json`:

```javascript
```json
{
 "devDependencies": {
"devDependencies": {
"egg-ts-helper": "^1"
 },
},
"scripts": {
"dev": "egg-bin dev -r egg-ts-helper/register",
"test-local": "egg-bin test -r egg-ts-helper/register",
Expand All @@ -330,7 +331,7 @@ The corresponding `d.ts` files are automatically generated in `typings/{app,conf

> In the future, the tool will also support the analysis of Egg in js, which will improve the experience of js development.
### Unit Test && Cov
### Unit Test and Cov

Unit Test is a MUST in development:

Expand Down Expand Up @@ -358,7 +359,7 @@ Run commands as what you do before, and we've built `Error stacks and coverages`

```json
{
 "name": "showcase",
"name": "showcase",
"scripts": {
"test": "npm run lint -- --fix && npm run test-local",
"test-local": "egg-bin test -r egg-ts-helper/register",
Expand All @@ -374,7 +375,7 @@ There's no main difference for debugging in TS, it can reach correct positions t

```json
{
 "name": "showcase",
"name": "showcase",
"scripts": {
"debug": "egg-bin debug -r egg-ts-helper/register",
"debug-test": "npm run test-local -- --inspect"
Expand All @@ -399,13 +400,13 @@ Configs in `package.json` :
{
"egg": {
"typescript": true
}
},
"scripts": {
   "start": "egg-scripts start --title=egg-server-showcase",
"start": "egg-scripts start --title=egg-server-showcase",
"stop": "egg-scripts stop --title=egg-server-showcase",
  "tsc": "ets && tsc -p tsconfig.json",
"tsc": "ets && tsc -p tsconfig.json",
"ci": "npm run lint && npm run cov && npm run tsc",
   "clean": "ets clean"
"clean": "ets clean"
}
}
```
Expand Down Expand Up @@ -439,7 +440,7 @@ And the corresponding `tsconfig.json`:
},
"exclude": [
"app/public",
   "app/web",
"app/web",
"app/views"
]
}
Expand Down Expand Up @@ -531,7 +532,7 @@ For developers, they can directly import your framework:
```typescript
// app/service/news.ts

// Developers can get all intellisenses after they import your framework
// Developers can get all intellisense after they import your framework
import { Service } from 'duck-egg';

export default class NewsService extends Service {
Expand Down
48 changes: 24 additions & 24 deletions docs/source/zh-cn/tutorials/typescript.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ showcase
└── tslint.json
```

### Controller
### 控制器(Controller

```typescript
// app/controller/home.ts
Expand All @@ -90,7 +90,7 @@ export default class HomeController extends Controller {
}
```

### Router
### 路由(Router

```typescript
// app/router.ts
Expand All @@ -102,7 +102,7 @@ export default (app: Application) => {
};
```

### Service
### 服务(Service

```typescript
// app/service/news.ts
Expand All @@ -120,7 +120,7 @@ export interface NewsItem {
}
```

### Middleware
### 中间件(Middleware

```typescript
// app/middleware/robot.ts
Expand Down Expand Up @@ -151,7 +151,7 @@ export default function newsMiddleware(options: BizConfig['news'], app: Applicat
}
```

### Extend
### 扩展(Extend

```typescript
// app/extend/context.ts
Expand All @@ -171,7 +171,7 @@ export default app => {
};
```

### Config
### 配置(Config

`Config` 这块稍微有点复杂,因为要支持:

Expand Down Expand Up @@ -246,7 +246,7 @@ type PowerPartial<T> = {
};
```

### Plugin
### 插件(Plug-in)

```javascript
// config/plugin.ts
Expand All @@ -263,7 +263,7 @@ const plugin: EggPlugin = {
export default plugin;
```

### Typings
### TS 类型定义(Typings

该目录为 TS 的规范,在里面的 `**/*.d.ts` 文件将被自动识别。

Expand Down Expand Up @@ -314,11 +314,11 @@ declare module 'egg' {

只需配置下 `package.json` :

```javascript
```json
{
 "devDependencies": {
"devDependencies": {
"egg-ts-helper": "^1"
 },
},
"scripts": {
"dev": "egg-bin dev -r egg-ts-helper/register",
"test-local": "egg-bin test -r egg-ts-helper/register",
Expand All @@ -331,7 +331,7 @@ declare module 'egg' {

> 后续该工具也会考虑支持 js 版 egg 应用的分析,可以一定程度上提升 js 开发体验。
### Unit Test && Cov
### 单元测试和覆盖率(Unit Test and Cov

单元测试当然少不了:

Expand Down Expand Up @@ -359,7 +359,7 @@ describe('test/app/service/news.test.js', () => {

```json
{
 "name": "showcase",
"name": "showcase",
"scripts": {
"test": "npm run lint -- --fix && npm run test-local",
"test-local": "egg-bin test -r egg-ts-helper/register",
Expand All @@ -369,13 +369,13 @@ describe('test/app/service/news.test.js', () => {
}
```

### Debug
### 调试(Debug

断点调试跟之前也没啥区别,会自动通过 `sourcemap` 断点到正确的位置。

```json
{
 "name": "showcase",
"name": "showcase",
"scripts": {
"debug": "egg-bin debug -r egg-ts-helper/register",
"debug-test": "npm run test-local -- --inspect"
Expand All @@ -388,9 +388,9 @@ describe('test/app/service/news.test.js', () => {

---

## 部署
## 部署(Deploy)

### 构建
### 构建(Build)

* 正式环境下,我们更倾向于把 ts 构建为 js ,建议在 `ci` 上构建并打包。

Expand All @@ -400,13 +400,13 @@ describe('test/app/service/news.test.js', () => {
{
"egg": {
"typescript": true
}
},
"scripts": {
   "start": "egg-scripts start --title=egg-server-showcase",
"start": "egg-scripts start --title=egg-server-showcase",
"stop": "egg-scripts stop --title=egg-server-showcase",
  "tsc": "ets && tsc -p tsconfig.json",
"tsc": "ets && tsc -p tsconfig.json",
"ci": "npm run lint && npm run cov && npm run tsc",
   "clean": "ets clean"
"clean": "ets clean"
}
}
```
Expand Down Expand Up @@ -440,15 +440,15 @@ describe('test/app/service/news.test.js', () => {
},
"exclude": [
"app/public",
   "app/web",
"app/web",
"app/views"
]
}
```

**注意:当有同名的 ts 和 js 文件时,egg 会优先加载 js 文件。因此在开发期,`egg-ts-helper` 会自动调用清除同名的 `js` 文件,也可 `npm run clean` 手动清除。**

### 错误堆栈
### 错误堆栈(Error Stack)

线上服务的代码是经过编译后的 js,而我们期望看到的错误堆栈是指向 TS 源码。
因此:
Expand All @@ -463,7 +463,7 @@ describe('test/app/service/news.test.js', () => {

---

## 插件/框架开发指南
## 插件 / 框架开发指南

**指导原则:**

Expand Down

0 comments on commit c65a648

Please sign in to comment.