functional-ts-review

Functional TypeScript Code Review

Review server-side TypeScript code against functional domain modeling principles.

Review Procedure

1. Read the files to be changed
2. Scan the following checklist items in order
3. If a violation is found, point it out along with the principle and the reason
4. If it is not a violation but there is room for improvement, communicate it as a suggestion

Checklist

1. Are classes used in the domain model?

If class is used in the definition of domain entities or value objects, propose changing to the Discriminated Union + Companion Object pattern.

If an external library requires class inheritance, that is a legitimate deviation.

2. Are method notations used?

If a function in a type definition uses method notation (save(task: Task): Promise<void>), point out the change to function property notation (save: (task: Task) => Promise<void>).

Method notation makes parameter types bivariant, so when doing dependency injection, an implementation with a narrower type passes the type check.

3. Is interface used in domain types?

interface The declaration merging of type implicitly changes the shape of a type just by declaring an interface with the same name in another file. Define domain types with

For library type augmentation, interface is necessary. This is a legitimate use.

4. as Are there type assertions using

as bypasses type checking. Check the following:

• External data: Is it parsed with a Zod schema?
• The asinside a Branded Type generation function: acceptable (the only exception)
• Otherwise: consider whether it can be resolved by type inference

5. Are exceptions thrown in the domain layer?

If throw is used in the domain layer (entities, use cases), propose changing to theResult type.

The following are acceptable:

• assertNever throw inside
• Unexpected failures in the infrastructure layer

6. Is there assertNever in switch statements?

Discriminated Unionを switch If there is no default: return assertNever(x) , point out that it should be added. When a new variant is added, it can no longer be detected by a compile error.

7. Is there Zod validation at external boundaries?

At external boundaries such as API handlers, conversion of DB results, and loading of configuration files, check whether raw data is being treated as a domain type without type assertion.

8. Whether PII fields have a Sensitive wrapper

Check whether fields containing personal information (name, email address, phone number, diagnostic information, etc.) are wrapped with Sensitive<T> . In particular, focus on checking objects that may be output to logs.

How to Write Feedback

Each piece of feedback should include the following:

1. What the problem is: Specific code location
2. Why it is a problem: The principle and the risks of violating it
3. How to fix it: Code example of the fix

### メソッド記法の使用

`src/repository/task-repository.ts:15`

`save(task: Task): Promise<void>` はメソッド記法です。メソッド記法ではパラメータ型がbivariantになり、
`save(task: DoingTask): Promise<void>` のような狭い型の実装が型チェックを通過します。

修正案:
\`\`\`typescript
type TaskRepository = {
  save: (task: Task) => Promise<void>;
};
\`\`\`

Severity

Check items have the following severities:

Severity	Item	Reason
High	as Type assertion	Direct cause of runtime errors
High	PII unprotected	Risk of compliance violation
High	Insufficient validation at external boundaries	Direct cause of runtime errors
Medium	Use of class	Reduced type safety when extending
Medium	Use of throw	Consistency of error handling
Medium	Lack of assertNever	Oversight when adding a new variant
Low	Method notation	Problem manifests only under specific conditions
Low	Use of interface	Declaration merging accidents are rare