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
- Read the principle knowledge first. Before looking at the code, read the following so that you can cite the canonical principles in your feedback:
../functional-ts-ja/SKILL.md— index of principles../functional-ts-ja/error-handling.md../functional-ts-ja/boundary-defense.md../functional-ts-ja/state-modeling.md- The project's
package.jsonvalidation library guide according to (../functional-ts-ja/validation-libraries/underzod.md/valibot.md/arktype.md) - The project's
package.jsonResult library guide according to (../functional-ts-ja/result-libraries/underneverthrow.md/byethrow.md/fp-ts.md/option-t.md)
- Read the files to be reviewed.
- Scan the following checklist items in the order of the principles (
functional-ts-ja/SKILL.mdmatches the chapter structure). - If you find a violation, point it out with the principle, the reason, and a proposed fix.
- 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
constwith the same name as the type? - Whether the Branded Type validation schema is exposed as a
XxxSchemaproperty 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 like
xxxAssignDriver.
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 symbolpattern). - 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:
- What is the problem: The specific code location (
path:line)。 - Why is it a problem: The principle (with a reference link to
../functional-ts-ja/...) and the risk if violated. - 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 |