functional-ts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Functional Domain Modeling in TypeScript

TypeScript中的函数式领域建模

Principles for writing domain models in server-side TypeScript. Instead of class-based OOP, this approach maximizes the TypeScript type system through a functional style.

编写服务端TypeScript领域模型的原则。该方法摒弃基于类的OOP，通过函数式风格充分利用TypeScript的类型系统。

1. Type-Driven Domain Modeling

1. 类型驱动的领域建模

Represent states with discriminated unions using

kind

as the unified discriminant. Use

type

(not

interface

), companion objects, branded types,

Readonly<>

, function property notation, and one-concept-per-file structure.

Validation library detection: Check

dependencies

devDependencies

in the project's

package.json

for branded type syntax:

```
zod
```
→ validation-libraries/zod.md
```
valibot
```
→ validation-libraries/valibot.md
```
arktype
```
→ validation-libraries/arktype.md

Details: domain-modeling.md

使用

kind

作为统一判别符，通过判别联合表示状态。使用

type

（而非

interface

）、伴生对象、品牌类型、

Readonly<>

、函数属性表示法，以及“一个概念对应一个文件”的结构。

验证库检测： 检查项目

package.json

中的

dependencies

devDependencies

，识别品牌类型语法对应的库：

```
zod
```
→ validation-libraries/zod.md
```
valibot
```
→ validation-libraries/valibot.md
```
arktype
```
→ validation-libraries/arktype.md

详情：domain-modeling.md

2. State Transitions via Functions

2. 基于函数的状态转换

Express state transitions with pure functions. The argument type constrains valid source states, and the return type makes the target state explicit. Invalid transitions become compile errors. Use

assertNever

for exhaustiveness checking.

Details: state-modeling.md

使用纯函数表达状态转换。参数类型约束有效的源状态，返回类型明确目标状态。无效转换会成为编译错误。使用

assertNever

进行穷尽性检查。

详情：state-modeling.md

3. Error Handling — Railway Oriented Programming

3. 错误处理——面向铁路编程

Do not throw exceptions; treat errors as values using the Result type. Define error types as discriminated unions so callers can handle them exhaustively.

Library detection: Check

dependencies

devDependencies

in the project's

package.json

```
neverthrow
```
→ result-libraries/neverthrow.md
```
byethrow
```
→ result-libraries/byethrow.md
```
fp-ts
```
→ result-libraries/fp-ts.md
```
option-t
```
→ result-libraries/option-t.md

Details: error-handling.md

不要抛出异常；使用Result类型将错误视为值。将错误类型定义为判别联合，以便调用者可以穷尽地处理它们。

库检测： 检查项目

package.json

中的

dependencies

devDependencies

：

```
neverthrow
```
→ result-libraries/neverthrow.md
```
byethrow
```
→ result-libraries/byethrow.md
```
fp-ts
```
→ result-libraries/fp-ts.md
```
option-t
```
→ result-libraries/option-t.md

详情：error-handling.md

4. Boundary Defense

4. 边界防护

Validate external inputs (API requests, DB results, file reads) with validation library schemas at runtime. Trust types inside the domain layer. Do not use type assertions (

as

). Apply

Sensitive<T>

wrapper to PII fields.

Details: boundary-defense.md

在运行时使用验证库模式验证外部输入（API请求、数据库结果、文件读取）。信任领域层内部的类型。不要使用类型断言（

as

）。对PII字段应用

Sensitive<T>

包装器。

详情：boundary-defense.md

5. Declarative Style

5. 声明式风格

Write array transformations declaratively using

filter

map

reduce

with companion object predicates. Model domain events as immutable records.

Details: declarative-style.md

使用

filter

map

reduce

结合伴生对象谓词，以声明式方式编写数组转换。将领域事件建模为不可变记录。

详情：declarative-style.md

6. Test Data

6. 测试数据

Define test data with

as const satisfies Type

to preserve discriminant literal types and prevent widening.

Details: test-data.md

使用

as const satisfies Type

定义测试数据，以保留判别符字面量类型并防止类型拓宽。

详情：test-data.md

Applying These Principles

这些原则的应用

These are recommendations, not strict rules. You may use your judgment based on context, but if you deviate from a principle, explicitly state the reason in a comment.

Typical justified reasons to deviate:

An external library requires class inheritance
Immutable object creation cost is a performance concern
A different pattern has been adopted by team agreement

这些是建议，而非严格规则。你可以根据上下文做出判断，但如果偏离某个原则，请在注释中明确说明原因。

合理偏离的典型原因：

外部库要求类继承
不可变对象创建成本存在性能问题
团队已一致采用其他模式