Skip to content

Latest commit

 

History

History
245 lines (183 loc) · 8.2 KB

README.md

File metadata and controls

245 lines (183 loc) · 8.2 KB
Raw

BiEnum

简体中文 | English

1. 简介

BiEnum 是一种 Web 前端静态枚举方案，是 TypeScript 原生枚举（enum）的加强版。

BiEnum 加强了枚举标签和枚举值的编译时类型检查，也使代码编辑器有更精确的智能感知（IntelliSense）。

BiEnum 支持将任何值作为枚举标签或枚举值，使设计与实现异构枚举（Heterogeneous Enum）甚至是嵌套枚举成为易事。

定义 运行时对象

2. 原生枚举

2.1 类型过宽

枚举标签和枚举值为不同 JavaScript 基础类型（例如 string、number）的 TypeScript 枚举 在运行时是枚举标签和枚举值双向映射的 JavaScript 对象。

enum Direction {
    Up = 1,
    Down = 2,
}

Direction.Up // 1
Direction[2] // 'Down'

原生的 enum 类型检查不严格，编译器只粗略地判定 Direction 的枚举标签和枚举值是 string 和 number。

下面的示例中，3、4 都不是业务上的合法枚举值，但能编译通过，给运行时阶段埋下隐患。

let direction: Direction; // Actually, number
direction = 1; // ok
direction = true; // As expected: error, TS2322: Type 'true' is not assignable to type 'Direction'.
direction = 3; // Not as expected: compilation passed.

Direction[4]; // Not as expected: compilation passed.

TypeScript 支持把值作为类型使用，你可能会临时这么写：

type DirectionValue = 1 | 2;
let direction2: DirectionValue = 3; // As expected: error, TS2322: Type '3' is not assignable to type 'DirectionValue'.

但这要求你每一次修改 Direction 的定义，也需要连带修改 DirectionValue 的定义。大脑需要一直记着这件事，或者写在注释里提醒下一个开发者千万别忘了。其中的风险不言而喻。

2.2 值域受限

不可能所有业务场景下的枚举都是字符串和数值之间的简单映射。能在编译阶段就确定的静态属性，在业务上就可以是枚举，在技术上也应该被实现。

下面的示例代码编译会不通过：

enum BlueLikeColor {
    skyBlue = '#B2FFFF',
    royalBlue = '#002366',
}

enum Color {
    red = 0xff0000,
    green = 'rgb(0, 255, 0)',
    blueLike = [BlueLikeColor.skyBlue, BlueLikeColor.royalBlue], // error, Array is not allowed.
    unset = null, // error, TS2553: Computed values are not permitted in an enum with string valued members.
}

enum ColorDescription {
    [Color.red] = 'description about red', // error, TS1164: Computed property names are not allowed in enums.
    [Color.green] = 'description about red', // error, TS1164: Computed property names are not allowed in enums.
    [BlueLikeColor.skyBlue] = 1234, // error, TS1164: Computed property names are not allowed in enums.
}

注意到编译器的提示信息了吗？"Computed values are not permitted"。

我们刚刚说过 TypeScript 支持把值作为类型使用。理论上，所有字面量、所有在编译阶段就能确定的属性都应该和可以作为枚举值。

如果你对 TypeScript 有一定的了解，并且听信了我上面巧言令色的分析，可能会产生一些想法。

来不及了，你肯定不会不着急往下看 BiEnum 的设计，而打开编辑器自己先动手写写看。

3. BiEnum

3.1 快速上手

安装 bi-enum 包：

npm i bi-enum

这次我们用 toBiEnum 创建出双向枚举对象：

import { toBiEnum } from "bi-enum";

// Create a BiEnum instance
const Direction = toBiEnum({
    Up: 1,
    Down: 2,
} as const); // Don't omit 'as const'

写在冒号左边的作为枚举标签，写在冒号右边作为枚举值。as const 确保 1 和 2 的类型不会被收窄到 number 。

3.2 类型精准

BiEnum 自身是一个枚举标签和枚举值双向映射的对象实例，其原型对象上提供了 allLabels 和 allValues 两个数组，它们的值也直接作为类型。

// Value and type are both ['Up ',' Down ']
Direction.allLabels;

// Value and type are both [1, 2]
Direction.allValues;

// Equivalent to: type Direction = 1 | 2
type Direction = typeof Direction.allValues[number];

因此现在在编译阶段会进行严格的类型检查了：

let direction: Direction;
direction = 1; // ok
direction = true; // As expected: error, TS2322: Type 'true' is not assignable to type '2 | 1'.
direction = 3; // As expected: TS2322: Type '3' is not assignable to type '2 | 1'.

Direction[4]; // As expected: error, TS7053: ... Property '4' does not exist on type ... .

再强调一次, BiEnum 构造参数对象上的所有字面量会直接作为类型。

BiEnum 原型对象上还提供了 isLabel 和 isValue 两个方法来判断入参是否为合法的枚举标签或枚举值。

let test: number = 1;
direction = test; // TS2322: Type 'number' is not assignable to type '2 | 1'.

if (Direction.isValue(test)) {
    direction = test; // ok, compilation passed.
}

3.3 取值自由

现在把之前的 Color 案例从 enum 迁移到 BiEnum：

  • ① 将枚举标签和枚举值之间的等号换成冒号；
  • ② 将 enum 换成对 toBiEnum 的调用；
  • ③ 在构造参数对象结尾加上 as const；
  • ④ 一般来说，还需要为枚举值值域（allValues）定义一个与枚举映射对象同名的类型（以符合开发者对原生 enum 的使用习惯）。
enum BlueLikeColor {
    skyBlue = '#B2FFFF',
    royalBlue = '#002366',
}

const Color = toBiEnum({
    red: 0xff0000,
    green: 'rgb(0, 255, 0)',
    blueLike: [BlueLikeColor.skyBlue, BlueLikeColor.royalBlue],
    unset: null,
} as const);
type Color = typeof Color.allValues[number];

const ColorDescription = toBiEnum({
    [Color.red]: 'description about red',
    [Color.green]: 'description about green',
    [BlueLikeColor.skyBlue]: 1234,
} as const);
type ColorDescription = typeof ColorDescription.allValues[number];

// Value and type are both 'description about red'.
ColorDescription[Color.red];

// Value and type are both 1234.
ColorDescription[BlueLikeColor.skyBlue];

类型系统把所有的字面量也视为了类型，编译器现在不报错了。

native enum bi-enum

4. 其它说明

4.1 枚举元素类型限制

BiEnum 要求枚举标签为经典基础类型（string | number | boolean | null | undefined）。

对枚举值没有要求，不过如果你把值设为了非经典基础类型，BiEnum 只会保留从枚举标签到枚举值的单向映射。

无论是运行时的 BiEnum 对象，还是你在编辑器的提示列表里，都没有保留和不会看到类似 [object Object] 到枚举标签的反向映射。

4.2 枚举元素命中关键词

如果业务上的枚举标签或枚举值和 allLabels, allValues, isLabel, isValue 重名了，不影响创建出双向映射对象，从原型上获取对它们的引用即可。

const HitKeyword = toBiEnum({
    allLabels: 1,
    2: 'isLabel',
});
type HitKeywordLabel = typeof HitKeyword.allLabels[number]; 
type HitKeywordValue = typeof HitKeyword.allValues[number];

if (Reflect.getPrototypeOf(HitKeyword).isLabel(2)) {/* ... */}

for (const label of Reflect.getPrototypeOf(HitKeyword).allLabels) {/* ... */}