SuperAPI AI Directory

functional-ts-review-ja

General & other

View repository

Updated 10-16 08:40

About this skill

Functional TypeScript Code Review

functional-ts-ja Review server-side TypeScript code against the functional domain modeling principles defined by the skill. This skill functional-ts-ja とrefers to the same knowledge. Each checklist item corresponds one-to-one with a chapter there, and the location of the rationale is made explicit with a relative link.

Review procedure

  1. Read the principle knowledge first. Before looking at the code, read the following so that you can cite the canonical principles in your feedback:
  2. Read the files to be reviewed.
  3. Scan the following checklist items in the order of the principles (functional-ts-ja/SKILL.md matches the chapter structure).
  4. If you find a violation, point it out with the principle, the reason, and a proposed fix.
  5. If there is room for improvement even though it is not a violation, communicate it as a suggestion.

Checklist items

The checklist items are ../functional-ts-ja/SKILL.md directly reflect the structure of. Each item links to the canonical chapter.

1. Domain modeling with types

1.1 Is the domain state modeled with a Discriminated Union?

Reference: ../functional-ts-ja/SKILL.md §1 "Express state with a Discriminated Union"

Signs: a single type with many optional properties and a string status field (e.g., { state: string; driverId?: string; startTime?: Date }). Suggest splitting types per state into a union and making state-specific properties required.

1.2 discriminant が kind is it unified with

Reference: ../functional-ts-ja/SKILL.md §1「discriminantは kind unify with"

Signs: type, status, state, _tag etc., kind discriminant names other than. For codebase consistency, kind suggest changing to.

1.3 Are you not using class for the domain model?

Reference: ../functional-ts-ja/SKILL.md §1 "Express state with a Discriminated Union" and the Companion Object pattern.

For defining domain entities and value objects, class if you are using, suggest changing to the Discriminated Union + Companion Object pattern. If an external library requires class inheritance, that is a legitimate deviation.

1.4 Does it follow the Companion Object pattern?

Reference: ../functional-ts-ja/SKILL.md §1 "Companion Object pattern"

Check the following:

  • Are the operations related to the type consolidated in the const with the same name as the type?
  • Whether the Branded Type validation schema is exposed as a XxxSchema property of the companion object rather than a standalone .schema .
  • Whether domain logic that should be placed in a companion object is scattered as independent functions likexxxAssignDriver .

1.5 Whether interface is not used for domain types

Reference: ../functional-ts-ja/SKILL.md §1「type use (notinterface )"

There is a risk that declaration merging implicitly changes the shape of the type. Define domain types with type .interface is allowed only for library type augmentation.

1.6 Whether method notation is not used within type definitions

Reference: ../functional-ts-ja/SKILL.md §1 "Use function property notation (not method notation)"

Method notation (save(task: Task): Promise<void>) makes parameters bivariant, and during dependency injection an implementation with a narrower type (save(task: DoingTask): …) passes type checking. Propose changing to function property notation (save: (task: Task) => Promise<void>).

1.7 Whether Branded Types are applied to primitives with different meanings

Reference: ../functional-ts-ja/SKILL.md §1 "Distinguish meanings with Branded Types". Also refer to the project's validation library guide (../functional-ts-ja/validation-libraries/).

Signs: IDs or values with different meanings (UserId, OrderId, Email, amounts, etc.) are handled as plain string / number . If a validation library is available, check whether they are defined using its brand feature (noas cast); if not, check whether they are defined using the unique symbol pattern.

1.8 Whether domain objects are Readonly<> か

Reference: ../functional-ts-ja/SKILL.md §1「Readonly<> guarantee immutability"

Signs: The type definition of a domain object is not protected by Readonly<…>(or by readonlyon each property). Express state changes by creating new objects.

1.9 Whether the structure follows "1 concept 1 file"

Reference: ../functional-ts-ja/SKILL.md §1 "File structure: 1 concept 1 file"

Signs: Many domain types are aggregated in a catch-all file like types.ts, models.ts, domain.ts , especially when companion objects are in separate files. Barrel files (index.ts) should only re-export.

2. State transitions via functions

Reference: ../functional-ts-ja/SKILL.md §2 and ../functional-ts-ja/state-modeling.md

2.1 Whether state transition functions constrain the source state via the argument type

Signs: The argument type of the transition function is not an individual state (Waiting) but a union (TaxiRequest). Accepting a wide type allows calls from invalid source states.

2.2 Discriminated Union の switch に assertNever exists

Reference: ../functional-ts-ja/SKILL.md §2 "Exhaustiveness checking"

Signs: There is no kind that branches on switch に default: return assertNever(x) . When a new variant is added, it can no longer be detected as a compile error.

3. Error Handling — Railway Oriented Programming

Reference: ../functional-ts-ja/SKILL.md §3, ../functional-ts-ja/error-handling.md, the project's Result library guide (../functional-ts-ja/result-libraries/)。

3.1 Are exceptions being thrown in the domain layer?

Signs: Within entities, value objects, and use cases, throw。Result propose a change to a type. Allowed: assertNever throws within (unreachable), unexpected failures in the infrastructure layer.

3.2 Are error types implemented as a Discriminated Union?

Signs: Error subclasses, free-form string error codes,Result<T, string>。Discriminated Union({ kind: "DriverNotAvailable"; driverId } | { kind: "RequestAlreadyAssigned" }), and enable callers to branch exhaustively.

3.3 Are you composing using Result chains (not immediately unwrapping)?

Check whether chaining composition is done with the Result library API corresponding to the project (.map, .andThen, Result.do , etc.). If it is immediately unwrapped and expanded into if/else,../functional-ts-ja/result-libraries/ cite the relevant guide under and propose an appropriate combinator.

4. Boundary Defense

Reference: ../functional-ts-ja/SKILL.md §4, ../functional-ts-ja/boundary-defense.md, the project's validation library guide (../functional-ts-ja/validation-libraries/)。

4.1 Is there schema validation at all external boundaries?

Signs: API handlers, DB result mapping, queue/message handlers, file/config loading, environment variable reading, etc. treat raw data as domain types without parsing it with a validation library (Zod / Valibot / ArkType).

4.2 as Are there any type assertions via

Reference: ../functional-ts-ja/SKILL.md §4 "Type assertions (as) are not used"

All as identify all of them and check whether they fall under any of the following:

  • External data: should be replaced with schema parsing.
  • Inside a Branded Type generation function, as: allowed only when not using a validation library (unique symbol pattern).
  • Internal data: should be resolvable by type inference. If it cannot be resolved, the type design is likely incorrect.

4.3 Are PII fields wrapped with Sensitive<T> ?

Reference: ../functional-ts-ja/SKILL.md §4 "PII Defense", ../functional-ts-ja/boundary-defense.md

Signs: Fields that may contain personal information (name, email address, phone number, address, various IDs, payment information, health/diagnostic information, IP address, etc.) remain as raw string / number . Especially focus on checking objects that may be output to logs or error messages. Also check whether the validation schema performs automatic wrapping via Sensitive.of .

5. Declarative Style

Reference: ../functional-ts-ja/SKILL.md §5, ../functional-ts-ja/state-modeling.md

5.1 Are array operations declarative?

Signs: filter / map / reduce transformations expressible with,for / for…of are built imperatively with loops. Define predicate functions in the companion object andtasks.filter(Task.isActive) It is suggested to write as follows.

5.2 Are domain events published as immutable records?

Signs: State-changing code mutates a shared event log, or domain events are not published in situations required by the state-modeling guide.Readonly<{ eventId; eventAt; eventName; payload; aggregateId }> Record it separately from the repository as

6. Test Data

Reference: ../functional-ts-ja/SKILL.md §6

6.1 Are fixtures defined with as const satisfies Type ?

Signs: Test fixtures are typed with : Type = や as Type , and the literal type of the discriminant is widened to string . Propose a change toas const satisfies Type , andkind preserve the literal type of

How to Write Findings

Each finding should include the following:

  1. What is the problem: The specific code location (path:line)。
  2. Why is it a problem: The principle (with a reference link to../functional-ts-ja/... ) and the risk if violated.
  3. How to fix it: A code example of the proposed fix.
### メソッド記法の使用

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

`save(task: Task): Promise<void>` はメソッド記法です。
[`../functional-ts-ja/SKILL.md` §1「関数プロパティ記法を使う」](../functional-ts-ja/SKILL.md)
にあるとおり、メソッド記法ではパラメータが bivariant になり、
`save(task: DoingTask): Promise<void>` のような狭い型の実装が依存注入時に型チェックを通過します。

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

Severity

Severity Item Reason
High as type assertion (4.2) Direct cause of runtime errors
High Unprotected PII (4.3) Risk of compliance violation
High Insufficient schema validation at external boundaries (4.1) Direct cause of runtime errors
High Lack of Branded Types for semantically distinct primitives (1.7) Confusion of heterogeneous IDs occurs at runtime
Medium Use of class (1.3) Decline in type safety when extending
Medium State modeling with optional properties (1.1) Invalid states can be represented
Medium In the domain layer, throw (3.1) Lack of consistency in error handling
Medium Error types that are not Discriminated Unions (3.2) Callers cannot branch exhaustively
Medium assertNever Missing (2.2) Oversight when adding new variants
Medium State transition functions that accept union types (2.1) Invalid transitions pass compilation
Medium Catch-all type file (1.9) Circular dependencies, separation of types and behavior
Medium Companion Object pattern violation / Schema-only export (1.4) Leakage of implementation details
Low Method notation (1.6) Problem becomes apparent only under specific conditions
Low Domain type interface usage (1.5) Declaration merging accidents are rare
Low Readonly<> Unused domain type (1.8) Mutations are often noticeable in review
Low discriminant が kind Other than (1.2) Style inconsistency rather than a bug
Low Imperative array loop (5.1) Readability rather than correctness
Low Domain event not emitted (5.2) Depends on whether event sourcing is adopted
Low There is no as const satisfies in the fixture (6.1) In practice, detected by tests