Skip to content

Commit 4784a04

Browse files
fenyingfenying
committed
Improved APIs and added documents
1 parent e9abeee commit 4784a04

File tree

10 files changed

+195
-22
lines changed

10 files changed

+195
-22
lines changed

‎README.md

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
# LiteRT/type-guard
1+
# LiteRT/TypeGuard
22

3-
[![npm version](https://img.shields.io/npm/v/@litert/type-guard.svg?colorB=brightgreen)](https://www.npmjs.com/package/@litert/type-guard "Stable Version")
4-
[![License](https://img.shields.io/npm/l/@litert/type-guard.svg?maxAge=2592000?style=plastic)](https://github.com/litert/type-guard/blob/master/LICENSE)
5-
[![node](https://img.shields.io/node/v/@litert/type-guard.svg?colorB=brightgreen)](https://nodejs.org/dist/latest-v8.x/)
3+
[![npm version](https://img.shields.io/npm/v/@litert/type-uard.svg?colorB=brightgreen)](https://www.npmjs.com/package/@litert/typeguard "Stable Version")
4+
[![License](https://img.shields.io/npm/l/@litert/typeguard.svg?maxAge=2592000?style=plastic)](https://github.com/litert/typeguard/blob/master/LICENSE)
5+
[![node](https://img.shields.io/node/v/@litert/typeguard.svg?colorB=brightgreen)](https://nodejs.org/dist/latest-v8.x/)
66
[![GitHub issues](https://img.shields.io/github/issues/litert/type-guard.js.svg)](https://github.com/litert/type-guard.js/issues)
77
[![GitHub Releases](https://img.shields.io/github/release/litert/type-guard.js.svg)](https://github.com/litert/type-guard.js/releases "Stable Release")
88

@@ -20,14 +20,12 @@ A type checking code "JIT"😄.
2020
Install by NPM:
2121

2222
```sh
23-
npm i @litert/type-guard --save
23+
npm i @litert/typeguard --save
2424
```
2525

2626
## Document
2727

28-
### 简体中文版
29-
30-
准备中...
28+
- [简体中文版](./docs/zh-CN/index.md)
3129

3230
## License
3331

‎docs/zh-CN/index.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# TypeGuard 文档
2+
3+
- [快速入门](./quick-start.md)
4+
- 语法说明 （准备中）
5+
- API 文档 （准备中）

‎docs/zh-CN/quick-start.md

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# 快速入门
2+
3+
## 安装
4+
5+
```sh
6+
npm i @litert/typeguard -S
7+
```
8+
9+
## 使用
10+
11+
模块导出两个主要的方法 `createCompiler` 和 `createCompiler4JavaScript`。
12+
13+
### createCompiler
14+
15+
该方法创建一个 TypeGuard.Compiler 类型的编译器对象，用于编译规则为特定语言的检查代码。
16+
17+
> 目前仅支持 JavaScript。
18+
19+
```ts
20+
import * as TyG from "@litert/typeguard";
21+
22+
let compiler = TyG.createCompiler(new TyG.JavaScriptLanguage());
23+
24+
console.log(compiler.compile("uint8")); // 规则：0 ~ 255 的整数。
25+
console.log(compiler.compile(
26+
["$.and", "string", "|length eq 32"] // 规则：长度为 32 字符的字符串。
27+
));
28+
console.log(compiler.compile(
29+
["$.tuple", "string", "uint"] // 规则：[string, uint] 类型的元组。
30+
));
31+
```
32+
33+
### createCompiler4JavaScript
34+
35+
该方法创建一个 TypeGuard.Compiler4JavaScript 类型的编译器对象。该对象只能编译生成
36+
JavaScript 代码，但是会自动转换成可以执行的 JavaScript 函数。
37+
38+
```ts
39+
40+
import * as TyG from "@litert/typeguard";
41+
42+
let compiler = TyG.createCompiler(new TyG.JavaScriptLanguage());
43+
44+
const isOptionalString = compiler.compile<string | undefined>(
45+
["$.or", "string", "void"]
46+
);
47+
48+
console.log(isOptionalString("hello world"));
49+
console.log(isOptionalString(undefined));
50+
console.log(isOptionalString(null));
51+
```
52+
53+
## 基本类型
54+
55+
TypeGuard 支持大量内置简单类型，比如：
56+
57+
- `string`
58+
- `numeric`（任意数值或者数值字符串）
59+
- `number`（任意数值）
60+
- `float`（不包含 NaN）
61+
- `int`
62+
- `int8`
63+
- `int16`
64+
- `int32`
65+
- `int64`（等价于 int）
66+
- `uint`
67+
- `uint8`
68+
- `uint16`
69+
- `uint32`
70+
- `uint64`（等价于 uint）
71+
- `boolean`
72+
- `array`
73+
- `object`（包含 `null`）
74+
- `valid_object` （不包含 `null`）
75+
- `null`
76+
- `any`（任意类型）
77+
- `false`
78+
- `true`
79+
- `false_value`（任意非真值）
80+
- `true_value`（任意真值）
81+
- `undefined`
82+
- `optional`（等价于 undefined）
83+
- `void`（等价于 undefined）
84+
- ...
85+
86+
```ts
87+
import * as TyG from "@litert/typeguard";
88+
89+
let compiler = TyG.createCompiler4JavaScript();
90+
91+
const isUInt8 = compiler.compile("uint8");
92+
const isBoolean = compiler.compile("boolean");
93+
94+
console.log(isUInt8(123));
95+
console.log(isUInt8(255));
96+
console.log(isUInt8(256)); // 超出 UInt8 的范围
97+
console.log(isBoolean(true));
98+
console.log(isBoolean(null)); // null 不是 boolean 型
99+
console.log(isBoolean(false));
100+
console.log(isBoolean(123)); // 123 不是 boolean 型
101+
```
102+
103+
## 对象
104+
105+
```ts
106+
import * as TyG from "@litert/typeguard";
107+
108+
let compiler = TyG.createCompiler4JavaScript();
109+
110+
const isPerson = compiler.compile({
111+
"name": "string",
112+
"age": ["$.and", "uint", "|value between 1 100"]
113+
});
114+
115+
console.log(isPerson({
116+
"name": "Angus",
117+
"age": 24
118+
}));
119+
120+
console.log(isPerson({
121+
"name": "Edith"
122+
// 缺少 age
123+
}));
124+
125+
console.log(isPerson({
126+
"name": "Mike",
127+
"age": 101 // age 取值范围不对
128+
}));
129+
```
130+
131+
（未完待续，暂时可以参考 `sources/tests.ts`）

‎package-lock.json

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
2-
"name": "@litert/type-guard",
2+
"name": "@litert/typeguard",
33
"version": "0.1.0",
4-
"description": "A type checking code \"JIT\".",
4+
"description": "A type checking code \"JIT\" library.",
55
"main": "dist/index.js",
66
"scripts": {
77
"prepare": "npm run rebuild",

‎sources/common.ts

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ export interface CompileOptions {
3030
"stopOnEntry"?: boolean;
3131
}
3232

33-
export interface CompileResult<T = any> {
33+
export interface CompileResult {
3434

3535
"source": string;
3636
}
@@ -97,10 +97,18 @@ export const MIX_TYPE_REL = {
9797

9898
export interface Compiler {
9999

100-
compile<T = any>(
101-
descriptor: any,
100+
compile(
101+
rule: any,
102102
opts?: CompileOptions
103-
): CompileResult<T>;
103+
): CompileResult;
104+
}
105+
106+
export interface Compiler4JavaScript {
107+
108+
compile<T = any>(
109+
rule: any,
110+
stopOnEntry?: boolean
111+
): TypeChecker<T>;
104112
}
105113

106114
export const KEY_ARRAY_SUFFIX = "->[]";

‎sources/utilities.ts renamed to ‎sources/compiler.javascript.ts

Lines changed: 30 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,12 +13,38 @@
1313
+----------------------------------------------------------------------+
1414
*/
1515

16-
export function isNumericString(v: string): boolean {
16+
import * as TyG from ".";
1717

18-
return /^[-+]?\d+(\.\d+)?$/.test(v);
18+
class Compiler4JavaScript
19+
implements TyG.Compiler4JavaScript {
20+
21+
private _compiler: TyG.Compiler;
22+
23+
public constructor() {
24+
25+
this._compiler = TyG.createCompiler(new TyG.JavaScriptLanguage());
26+
}
27+
28+
public compile<T = any>(
29+
rule: any,
30+
stopOnEntry?: boolean
31+
): TyG.TypeChecker<T> {
32+
33+
return <TyG.TypeChecker<T>> new Function(
34+
"input",
35+
`${stopOnEntry && "debugger;" || ""} return ${
36+
this._compiler.compile(
37+
rule
38+
).source
39+
};`
40+
);
41+
42+
}
1943
}
2044

21-
export function escape(v: string): string {
45+
export function createCompiler4JavaScript(): TyG.Compiler4JavaScript {
2246

23-
return v.replace(/"/g, "\\\"");
47+
return new Compiler4JavaScript();
2448
}
49+
50+
export default createCompiler4JavaScript;

‎sources/compiler.ts

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -625,10 +625,10 @@ implements Compiler {
625625
);
626626
}
627627

628-
public compile<T>(
628+
public compile(
629629
descriptor: any,
630630
opts?: CompileOptions
631-
): CompileResult<T> {
631+
): CompileResult {
632632

633633
let ctx = new CompileContext();
634634

‎sources/index.ts

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,12 @@
1616
export {
1717

1818
TypeChecker,
19-
Language
19+
Language,
20+
Compiler,
21+
Compiler4JavaScript
2022

2123
} from "./common";
2224

2325
export { createCompiler } from "./compiler";
2426
export { JavaScriptLanguage } from "./lang.javascript";
27+
export { createCompiler4JavaScript } from "./compiler.javascript";

‎sources/lang.javascript.ts

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -383,3 +383,5 @@ implements Language {
383383
return `${arrName}[${index}]`;
384384
}
385385
}
386+
387+
export default JavaScriptLanguage;

0 commit comments

Comments
 (0)