typescript-standards

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to Load

加载时机

Load this skill when the task involves:

Creating or refactoring functions, methods, classes, modules
Typing decisions: interfaces, types, enums, generics, utility types
Domain modeling, boundaries, shared contracts
API design, module boundaries between layers
Design principles: SOLID, KISS, YAGNI, LIFT, SoC
Design patterns (GoF) with real justification

当任务涉及以下内容时加载本技能：

创建或重构函数、方法、类、模块
类型决策：接口、类型、枚举、泛型、工具类型
领域建模、边界定义、共享契约
API设计、各层之间的模块边界
设计原则：SOLID、KISS、YAGNI、LIFT、SoC
有实际依据地使用设计模式（GoF）

Composition

组合使用

This skill is COMPLEMENTARY to framework skills:

When loaded ALONGSIDE
```
angular-standards
```
: applies TypeScript rules to
```
.ts
```
files of Angular Resources
The framework skill prevails for ecosystem-specific organization (Angular DI, signals, etc.)
This skill prevails for general language and design rules (types, boundaries, modules)
Load this skill triggered by
```
angular-standards
```
Composition section — do NOT auto-trigger alone for component tasks that
```
angular-standards
```
already covers

本技能是框架技能的补充：

与
```
angular-standards
```
一同加载时：将TypeScript规则应用于Angular资源的.ts文件
框架技能在生态系统特定组织（Angular DI、信号等）方面具有优先级
本技能在通用语言和设计规则（类型、边界、模块）方面具有优先级
由
```
angular-standards
```
的组合部分触发加载本技能——对于
```
angular-standards
```
已覆盖的组件任务，请勿单独自动触发本技能

Do Not Load When

请勿加载的场景

Exclusive HTML template or SCSS/CSS tasks
Build/deploy/infra tasks
Commits (use
```
git-commit
```
)
CI/CD configuration

仅涉及HTML模板或SCSS/CSS的任务
构建/部署/基础设施任务
提交操作（使用
```
git-commit
```
）
CI/CD配置

TypeScript Standards

TypeScript设计标准

When to Use

适用场景

Creating or refactoring TypeScript files in the project.
Defining interfaces, types, shared contracts, and module boundaries.
Modeling domain, results, errors, collections, and public APIs.
Making design and architecture decisions that are not specific to a framework.

在项目中创建或重构TypeScript文件时。
定义接口、类型、共享契约和模块边界时。
对领域、结果、错误、集合和公共API进行建模时。
做出不特定于某一框架的设计和架构决策时。

Goal

目标

Maintain strong, predictable, and readable typing.
Preserve simplicity, cohesion, and healthy code evolution.
Concentrate detailed rules in local references to avoid duplication and maintain clear precedence.
Apply design principles pragmatically, without overengineering.

保持强类型、可预测且可读性高的代码。
保留简洁性、内聚性，确保代码健康演进。
将详细规则集中在本地参考资料中，避免重复并保持清晰的优先级。
务实应用设计原则，避免过度工程化。

LIFT Principle

LIFT原则

Before creating any new type, helper, module, class, adapter, factory, port, or abstraction, apply the LIFT principle:

Locate: Find existing contracts, types, helpers, patterns, modules, and references.
Identify: Determine what already solves part of the problem and where there is real or potential duplication.
Find: Find the smallest coherent point of reuse, extension, or composition before introducing something new.
Try to be DRY: Eliminate real duplication without creating premature abstractions, overly generic layers, or opaque structures.

在创建任何新类型、工具函数、模块、类、适配器、工厂、端口或抽象之前，应用LIFT原则：

定位（Locate）：查找现有的契约、类型、工具函数、模式、模块和参考资料。
识别（Identify）：确定哪些内容已能部分解决问题，以及存在实际或潜在重复的地方。
探寻（Find）：在引入新内容之前，找到最小的可复用、可扩展或可组合的合理切入点。
力求DRY（Try to be DRY）：消除实际重复，但避免创建过早的抽象、过于通用的层级或不透明的结构。

Integration with Other Skills

与其他技能的集成

This skill is cross-cutting and language-level: frameworks like Angular and Vue should continue dictating framework-specific architecture.
```
typescript-standards
```
defines modeling, contracts, module design, boundary validation, and pragmatic design in TypeScript.
In case of conflict, the framework skill prevails for ecosystem-specific organization and
```
typescript-standards
```
prevails for general language and design rules.

本技能是跨领域的语言层技能：Angular和Vue等框架仍应主导特定于框架的架构设计。
```
typescript-standards
```
定义了TypeScript中的建模、契约、模块设计、边界验证和务实设计规则。
若出现冲突，框架技能在生态系统特定组织方面具有优先级，而
```
typescript-standards
```
在通用语言和设计规则方面具有优先级。

Main Rules

核心规则

Apply LIFT before introducing new types, modules, classes, helpers, adapters, factories, or patterns.
Never use
```
any
```
; when the type is uncertain, use
```
unknown
```
.
Always use path aliases for imports. Deep relative imports (
../../
or deeper) are strictly forbidden.
- Use
```
@<app-name>/<feature>/*
```
  for app-internal cross-module imports (e.g.,
```
@vendas/services/some.service
```
  ).
- Use
```
@lib/<lib-name>
```
  for shared library imports (e.g.,
```
@lib/data-access
```
  ,
```
@lib/ui
```
  ,
```
@lib/utils
```
  ,
```
@lib/pipes
```
  ).
- Use
```
@lib/<lib-name>/<sub-path>
```
  for sub-path aliases when available (e.g.,
```
@lib/data-access/config
```
  ,
```
@lib/data-access/enums
```
  ).
- Relative imports (
```
./
```
  or
```
../
```
  ) are only acceptable within the same feature folder (1 level maximum).
Interfaces must start with
```
I
```
.
Do not create interfaces inside files that are not dedicated to the interface.
Every interface must have a corresponding generator using
```
faker.js
```
.
The interface generator must live in a dedicated file and respect the folder hierarchy adopted by the project.
The generator must create or receive a single random seed per execution and derive all contract data from it.
Do not create enums inside files that are not dedicated to the enum.
Keep only one enum per file.
Every enum must have in the same file a mapping structure for its value labels.
Prefer functions and modules over classes.
Prefer composition over inheritance.
Apply KISS, YAGNI, and SoC by default.
Treat SOLID as pragmatic heuristics, not as a dogmatic checklist.
Treat Object Calisthenics as optional design pressure, not as law.
Use GoF patterns only when there is real pressure for change, repetition, or decoupling.
Prefer
```
Record
```
over
```
Map
```
when object keys are sufficient.
Use
```
Map
```
only when its specific API or support for non-serializable keys is truly needed.
Prefer one contract per file, unless the types are strongly related.
Before introducing new types, check if an equivalent contract already exists in the domain.
Validate runtime boundaries when data enters from outside the system.
Use single quotes and semicolons.

在引入新类型、模块、类、工具函数、适配器、工厂或模式之前，先应用LIFT原则。
绝不使用
```
any
```
；当类型不确定时，使用
```
unknown
```
。
始终使用路径别名进行导入。严格禁止深层相对导入（
../../
或更深层级）。
- 应用内跨模块导入使用
```
@<app-name>/<feature>/*
```
  （例如：
```
@vendas/services/some.service
```
  ）。
- 共享库导入使用
```
@lib/<lib-name>
```
  （例如：
```
@lib/data-access
```
  、
```
@lib/ui
```
  、
```
@lib/utils
```
  、
```
@lib/pipes
```
  ）。
- 当存在子路径别名时，使用
```
@lib/<lib-name>/<sub-path>
```
  （例如：
```
@lib/data-access/config
```
  、
```
@lib/data-access/enums
```
  ）。
- 相对导入（
```
./
```
  或
```
../
```
  ）仅在同一功能文件夹内（最多1层级）是可接受的。
接口必须以
```
I
```
开头。
请勿在非专门用于接口的文件中创建接口。
每个接口必须有一个使用
```
faker.js
```
的对应生成器。
接口生成器必须位于专门的文件中，并遵循项目采用的文件夹层级结构。
生成器每次执行必须创建或接收一个随机种子，并从中派生所有契约数据。
请勿在非专门用于枚举的文件中创建枚举。
每个文件仅保留一个枚举。
每个枚举必须在同一文件中包含其值标签的映射结构。
优先使用函数和模块而非类。
优先使用组合而非继承。
默认应用KISS、YAGNI和SoC原则。
将SOLID视为务实的启发式规则，而非教条式的检查清单。
将Object Calisthenics视为可选的设计约束，而非必须遵守的规则。
仅当存在实际的变更、重复或解耦需求时，才使用GoF模式。
当对象键足够时，优先使用
```
Record
```
而非
```
Map
```
。
仅当确实需要其特定API或对不可序列化键的支持时，才使用
```
Map
```
。
优先每个文件一个契约，除非类型之间存在强关联。
在引入新类型之前，检查领域中是否已存在等效的契约。
当数据从系统外部进入时，验证运行时边界。
使用单引号和分号。

Procedure

流程步骤

Apply LIFT before creating new types, modules, or abstractions.
Identify the contracts, types, and boundaries truly needed for the change.
If there is an interface, also plan the corresponding generator in the correct project hierarchy.
Reuse existing types before creating new ones.
Model with the most restrictive, clear, and simple option possible.
If there is uncertainty, use
```
unknown
```
and perform explicit narrowing.
Choose between function, module, object, or class based on the real need for state, identity, lifecycle, or polymorphism.
If considering a GoF pattern, first check if simple composition solves the case.
Review the result with KISS, YAGNI, SoC, and domain readability.

在创建新类型、模块或抽象之前，先应用LIFT原则。
确定变更真正需要的契约、类型和边界。
若涉及接口，同时规划在正确的项目层级结构中创建对应的生成器。
在创建新类型之前，先复用现有类型。
使用最具限制性、清晰且简单的选项进行建模。
若存在不确定性，使用
```
unknown
```
并执行显式类型收窄。
根据对状态、标识、生命周期或多态性的实际需求，选择使用函数、模块、对象或类。
若考虑使用GoF模式，首先检查简单组合是否能解决问题。
使用KISS、YAGNI、SoC和领域可读性原则审查结果。

Quality Checklist

质量检查清单

LIFT applied before introducing new structures.
No
```
any
```
was introduced.
No deep relative imports (
```
../../
```
or deeper) — all cross-module imports use path aliases.
Interfaces follow the
```
I
```
prefix.
Interfaces live in dedicated files.
Interfaces have a corresponding generator.
The interface generator uses
```
faker.js
```
.
The interface generator respects the project's folder hierarchy.
The interface generator uses a single random seed per execution.
Enums live in dedicated files.
Only one enum per file.
Every enum has a label mapping structure in the same file.
The simplest solution that meets the case was preferred.
No speculative abstraction.
```
Record
```
was preferred when sufficient.
```
Map
```
was only used with real technical justification.
External boundaries were treated with proper validation when needed.
The file uses single quotes and semicolons.
No unnecessary proliferation of types, classes, or patterns.

在引入新结构之前已应用LIFT原则。
未引入
```
any
```
类型。
无深层相对导入（
```
../../
```
或更深层级）——所有跨模块导入均使用路径别名。
接口遵循
```
I
```
前缀规则。
接口位于专门的文件中。
接口有对应的生成器。
接口生成器使用
```
faker.js
```
。
接口生成器遵循项目的文件夹层级结构。
接口生成器每次执行使用单个随机种子。
枚举位于专门的文件中。
每个文件仅包含一个枚举。
每个枚举在同一文件中包含标签映射结构。
选择了满足需求的最简单解决方案。
无投机性抽象。
在适用时优先使用
```
Record
```
。
仅在有实际技术依据时使用
```
Map
```
。
必要时对外部边界进行了适当验证。
文件使用单引号和分号。
无不必要的类型、类或模式泛滥。

Notes

注意事项

This skill does not require object-oriented design as default; in TypeScript, functions, modules, and composition are usually the best starting point.
SOLID, GoF, and Object Calisthenics exist here to improve design and maintainability, not to justify extra complexity.
When the framework skill defines a specific structure, follow the framework and apply this skill at the language and design layer.

本技能不要求默认采用面向对象设计；在TypeScript中，函数、模块和组合通常是最佳起点。
SOLID、GoF和Object Calisthenics的存在是为了提升设计和可维护性，而非为额外复杂性提供理由。
当框架技能定义了特定结构时，遵循框架要求，并在语言和设计层应用本技能。

Typing Decisions

类型决策

Consult when defining interfaces, types, enums, generics, or modeling domain contracts.

Interface vs type: references/types-interface-vs-type.md
Interface generators: references/types-interface-generators.md
Enums: references/types-enums.md
Domain modeling: references/types-domain-modeling.md
Generics: references/types-generics.md
Utility types: references/types-utility-types.md
Unions vs class hierarchies: references/types-unions-vs-class-hierarchies.md
Narrowing and unknown: references/types-narrowing-and-unknown.md
Readonly and immutability: references/types-readonly-and-immutability.md
Record vs Map: references/types-record-vs-map.md
Errors and result shapes: references/types-errors-and-result-shapes.md
Runtime validation: references/types-runtime-validation.md

定义接口、类型、枚举、泛型或建模领域契约时参考以下内容：

接口vs类型：references/types-interface-vs-type.md
接口生成器：references/types-interface-generators.md
枚举：references/types-enums.md
领域建模：references/types-domain-modeling.md
泛型：references/types-generics.md
工具类型：references/types-utility-types.md
联合类型vs类层级：references/types-unions-vs-class-hierarchies.md
类型收窄与unknown：references/types-narrowing-and-unknown.md
只读与不可变性：references/types-readonly-and-immutability.md
Record vs Map：references/types-record-vs-map.md
错误与结果形状：references/types-errors-and-result-shapes.md
运行时验证：references/types-runtime-validation.md

Architecture and Module Design

架构与模块设计

Consult when designing functions, classes, modules, boundaries, or API surfaces.

Functions vs classes: references/architecture-functions-vs-classes.md
Modules and boundaries: references/architecture-modules-and-boundaries.md
DI and composition: references/architecture-dependency-injection-and-composition.md
Side effects and ports: references/architecture-side-effects-and-ports.md
API design: references/architecture-api-design.md
File organization: references/architecture-file-organization.md

设计函数、类、模块、边界或API表面时参考以下内容：

函数vs类：references/architecture-functions-vs-classes.md
模块与边界：references/architecture-modules-and-boundaries.md
依赖注入与组合：references/architecture-dependency-injection-and-composition.md
副作用与端口：references/architecture-side-effects-and-ports.md
API设计：references/architecture-api-design.md
文件组织：references/architecture-file-organization.md

Design Principles

设计原则

Consult when making structural or design decisions that affect maintainability.

LIFT: references/principles-lift.md
SOLID: references/principles-solid.md
KISS and YAGNI: references/principles-kiss-yagni.md
Separation of Concerns: references/principles-separation-of-concerns.md
Object Calisthenics: references/principles-object-calisthenics.md

做出影响可维护性的结构或设计决策时参考以下内容：

LIFT：references/principles-lift.md
SOLID：references/principles-solid.md
KISS与YAGNI：references/principles-kiss-yagni.md
关注点分离：references/principles-separation-of-concerns.md
Object Calisthenics：references/principles-object-calisthenics.md

Design Patterns

设计模式

Consult only when there is real pressure for change, repetition, or decoupling.

Patterns overview: references/patterns-overview.md
Creational: references/patterns-creational.md
Structural: references/patterns-structural.md
Behavioral: references/patterns-behavioral.md
When not to use patterns: references/patterns-when-not-to-use.md

仅当存在实际的变更、重复或解耦需求时参考以下内容：

模式概述：references/patterns-overview.md
创建型模式：references/patterns-creational.md
结构型模式：references/patterns-structural.md
行为型模式：references/patterns-behavioral.md
何时不使用模式：references/patterns-when-not-to-use.md

Pragmatic Design

务实设计

Consult when evaluating duplication, abstraction trade-offs, or refactoring triggers.

Duplication vs abstraction: references/pragmatic-duplication-vs-abstraction.md
Refactoring triggers: references/pragmatic-refactoring-triggers.md

评估重复、抽象权衡或重构触发因素时参考以下内容：

重复vs抽象：references/pragmatic-duplication-vs-abstraction.md
重构触发因素：references/pragmatic-refactoring-triggers.md