TypeScriptで関数型DDDをやってみた
参考資料
本記事は以下の資料を多大に参考にしています。
また、以下の資料も参考にさせていただきました。
本記事のサンプルコードは GitHub リポジトリで公開しています。
1. なぜ関数型DDDなのか?
従来のクラスベースDDD
// 従来のクラスベースアプローチ
class Invitation {
private status: "active" | "expired" | "accepted" | "revoked";
private acceptedAt?: Date;
private revokedAt?: Date;
accept(): void {
if (this.status !== "active") {
throw new Error("Cannot accept non-active invitation");
}
this.status = "accepted";
this.acceptedAt = new Date();
}
}
上記のコードだと
-
不正な状態が表現可能 -
status === "active"なのにacceptedAtが設定されている、といった矛盾が型レベルで防げない - 例外の伝播が不透明 - どこで何が throw されるか、呼び出し側は型から読み取れない
本記事のアプローチ
型による不正状態の排除
不正な状態をそもそも型レベルで表現不可能にする設計。「期限切れの招待に acceptedAt がある」といった矛盾をコンパイル時に防ぐ。
Railway Oriented Programming
正常系と異常系を「線路」のように分岐させる処理フロー。Result<T, E> 型で成功・失敗を表現し、エラーを値として扱う。
主な使用技術
- TypeScript
- neverthrow
- Drizzle ORM
- Hono
2. 全体アーキテクチャとディレクトリ構成
具体的なコードに入る前に、プロジェクトの全体像を共有します。ディレクトリ構成自体は、DDD でよく見られる標準的なレイヤードアーキテクチャを採用しています。
src/
├── domain/ # [純粋] ドメインロジック (型定義、ルール、ワークフロー)
│ ├── company/
│ ├── invitation/ # 今回の主役
│ └── shared/ # 共通エラー型など
├── infrastructure/ # [不純] 外部との接続 (DB, メール送信)
├── presentation/ # [不純] HTTPハンドリング (Honoのルーター)
└── db/ # DB設定 (Drizzle ORM)
依存の方向
domain ディレクトリはいかなる外部ライブラリ(DB やフレームワーク)にも依存しません。infrastructure や presentation が domain を利用します。
純粋性
domain ディレクトリ内は、基本的に副作用のない「純粋関数」と「型定義」のみで構成します。DB アクセスなどの副作用はすべて infrastructure に閉じ込め、依存性の注入(後述)によって解決します。
3. 型で表現する
状態を型で表現する
従来の「1 つのクラスに status フィールドを持たせる」アプローチではなく、状態ごとに別の型を定義します。
それぞれの状態に必要な要素のみを定義します。
例:AcceptedInvitationのacceptedAtなど
TypeScriptが構造的型付けを採用しているため、kindのようなタグがないとswitch文などでの型ガードや網羅性チェックが難しくなります
// domain/invitation/models.ts
// 共通プロパティ
type InvitationBase = Readonly<{
invitationId: InvitationId;
companyId: CompanyId;
inviteeEmail: InviteeEmail;
tokenHash: InvitationTokenHash;
}>;
// 各状態の型定義
export type ActiveInvitation = Readonly<
InvitationBase & {
kind: "ActiveInvitation";
expiresAt: InvitationExpiresAt;
}
>;
export type ExpiredInvitation = Readonly<
InvitationBase & {
kind: "ExpiredInvitation";
expiresAt: InvitationExpiresAt;
}
>;
export type AcceptedInvitation = Readonly<
InvitationBase & {
kind: "AcceptedInvitation";
acceptedAt: InvitationAcceptedAt;
}
>;
export type RevokedInvitation = Readonly<
InvitationBase & {
kind: "RevokedInvitation";
revokedAt: InvitationRevokedAt;
}
>;
// Union型として集約
export type Invitation =
| ActiveInvitation
| ExpiredInvitation
| AcceptedInvitation
| RevokedInvitation;
このアプローチのメリット
不正な状態が型レベルで表現不可能
-
AcceptedInvitationにはexpiresAtがない(必要ない) -
ActiveInvitationにはacceptedAtがない(まだ承諾されていない)
値オブジェクト(Value Objects)の実装
Branded Types を採用。
// domain/invitation/valueObjects.ts
// Branded Type の定義
declare const __brand: unique symbol;
type Brand<T, B> = T & { readonly [__brand]: B };
// InviteeEmail の型定義
export type InviteeEmail = Brand<string, "InviteeEmail">;
// ファクトリ関数(Result を返す)
export const InviteeEmail = (
input: string
): Result<InviteeEmail, DomainValueError> =>
/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(input)
? ok(input as InviteeEmail)
: err({
kind: "DomainValueError",
message: `InviteeEmail: 有効なメールアドレス形式である必要があります (value: ${input})`,
});
ポイント
-
型エイリアスと同名のファクトリ関数
- TypeScript では型と値は別の名前空間なので、同じ名前を使える
-
InviteeEmail型とInviteeEmail()関数を同時に export
-
asキャストの隔離-
as InviteeEmailはvalueObjects.ts内でのみ使用 - バリデーションを通過した値だけがブランド化される
-
-
Result 型を返す
- 不正な入力は例外ではなく
errとして返す
- 不正な入力は例外ではなく
4. ワークフロー
処理のチェーン
ワークフローは、手続き的な if (error) throw ... ではなく、関数合成で記述します。andThen や map を使って小さな関数を繋げています。
// domain/invitation/workflows/create/index.ts
export const workflow: Workflow = (deps) => (command) => {
return okAsync(command)
.andThen(validateCommand) // 入力値検証
.andThen(
checkDuplicate(
// 重複チェック
deps.findLatestInvitation,
deps.checkAlreadyMember,
deps.now
)
)
.map(createInvitation(deps.hashToken, deps.now)) // モデル生成
.andThen(createSendEmailCommand(deps.getCompanyName)); // メール送信準備
};
create の処理の流れは下記です
- コマンドを受け取る
- 入力値を検証する
- 重複をチェックする
- 招待を作成する
- メール送信コマンドを生成する
どこかでエラーが発生すると、後続の処理は自動的にスキップされ、エラーが最終結果として返されます。
パイプラインのポイント:
-
andThen: 重複チェック (checkDuplicate) のように、実行結果がエラーになる可能性がある(Result 型を返す)場合に使用します。 -
map: モデル生成 (createInvitation) のように、バリデーション済みの値を使って確実に成功する処理に使用します。 -
asyncAndThen:andThenの非同期版。Resultを返す関数ではなく、ResultAsyncを返す非同期関数を繋げる場合に使用します。DB アクセスなど I/O を伴う処理で使います。
状態遷移を型で表現する
ワークフロー内部では、処理の各段階を明確な型で表現します。
// 入力(まだ検証されていない)
export type Unvalidated = Readonly<{
kind: "Unvalidated";
input: Readonly<{
invitationId: string;
companyId: string;
email: string;
token: string;
}>;
}>;
// 検証済み(値オブジェクトに変換済み)
type Validated = Readonly<{
kind: "Validated";
input: Readonly<{
invitationId: InvitationId;
companyId: CompanyId;
inviteeEmail: InviteeEmail;
tokenPlain: InvitationTokenPlain;
}>;
}>;
// 重複チェック完了
type DuplicateChecked = Readonly<{
kind: "DuplicateChecked";
input: Readonly<{
invitationId: InvitationId;
companyId: CompanyId;
inviteeEmail: InviteeEmail;
tokenPlain: InvitationTokenPlain;
}>;
}>;
// 招待作成完了
type InvitationCreated = Readonly<{
kind: "InvitationCreated";
invitation: ActiveInvitation;
tokenPlain: InvitationTokenPlain;
}>;
各関数は「入力の型」と「出力の型」が明確です。
-
validateCommand:Unvalidated → Validated -
checkDuplicate:Validated → DuplicateChecked -
createInvitation:DuplicateChecked → InvitationCreated
依存性の注入(DI)も関数で
DI コンテナやクラスのコンストラクタを使わず、**高階関数(カリー化)**で依存を注入します。
// 高階関数による依存注入
const checkDuplicate =
(
findLatestInvitation: FindLatestInvitation, // DB検索(注入される)
checkAlreadyMember: CheckAlreadyMember, // メンバー確認(注入される)
now: Date
) =>
(command: Validated): ResultAsync<DuplicateChecked, CheckDuplicateError> => {
const { companyId, inviteeEmail } = command.input;
return ResultAsync.combine([
findLatestInvitation(companyId, inviteeEmail, now),
checkAlreadyMember(companyId, inviteeEmail),
]).andThen(([latestInvitation, isMember]) => {
if (latestInvitation && latestInvitation.kind === "ActiveInvitation") {
return errAsync({
kind: "AlreadyInvitedError" as const,
message: "Already invited",
});
}
if (isMember) {
return errAsync({
kind: "AlreadyMemberError" as const,
message: "Already member",
});
}
return okAsync({
kind: "DuplicateChecked" as const,
input: command.input,
});
});
};
findLatestInvitation と checkAlreadyMember は、ドメイン層で定義された「ポート」(インターフェース)です。実際の DB アクセスはインフラ層で実装され、ワークフロー実行時に注入されます。
テスト時に依存関係を簡単に差し替えられます。
補足:データ取得のタイミングについて(IOサンドイッチとの兼ね合い)
関数型DDDの本では、すべてのIO(入出力)を処理の両端に寄せることが推奨されていました。しかし、今回は入力(Read)に関しては行っていません。
事前にすべての必要なデータを取得して純粋関数に渡すアプローチは、仕様が複雑になると「どのデータをどの条件で事前に取っておくか」の判断が難しくなりそうだと感じたので、参照系の副作用はワークフロー内での実行(DIによる注入)を許容し、更新系の副作用(保存など)のみを最後に回す方針で統一しました。
5. エラーハンドリング:すべての失敗を型定義する
エラーの Union 型
何が起こり得るかは、型定義を見てわかるようにしている。
// domain/invitation/workflows/create/index.ts
const checkDuplicate =
(
findLatestInvitation: FindLatestInvitation,
checkAlreadyMember: CheckAlreadyMember,
now: Date
) =>
(command: Validated):
// CheckDuplicateErrorが返ってくることが明示
ResultAsync<DuplicateChecked, CheckDuplicateError> => {
type CheckDuplicateError =
| AlreadyInvitedError
| AlreadyMemberError
| FindLatestInvitationError;
Presentation 層での扱い
エラーの型に応じて HTTP ステータスコードを振り分けます。
// presentation/invitation/createInvitation.ts
return result.match(
(saved) =>
c.json<CreateInvitationResponse>(
{ id: saved.invitation.invitationId },
201
),
(error) => {
switch (error.kind) {
case "ValidationError":
return c.json({ message: error.message }, 400);
case "CompanyNotFoundError":
return c.json({ message: error.message }, 404);
case "AlreadyInvitedError":
case "AlreadyMemberError":
return c.json({ message: error.message }, 409);
case "RepositoryError":
case "DataInconsistencyError":
return c.json({ message: "Internal Server Error" }, 500);
}
}
);
6. インフラ層
データの復元(Reconstruction)
DB の生の値をドメインモデル(Union 型)に変換する処理は、Invitation ファクトリ関数で行います。
// domain/invitation/models.ts
export const Invitation = (
record: InvitationRecord,
now: Date
): Result<Invitation, InvitationValidationError> => {
return safeTry(function* () {
// 1. 共通項目のバリデーション
const base: InvitationBase = {
invitationId: yield* InvitationId(record.id),
companyId: yield* CompanyId(record.companyId),
inviteeEmail: yield* InviteeEmail(record.email),
tokenHash: yield* InvitationTokenHash(record.tokenHash),
};
// 2. 不整合チェック
if (record.revokedAt && record.acceptedAt) {
return err({
kind: "DataInconsistencyError" as const,
message: `Invitation has both revokedAt and acceptedAt: ${record.id}`,
});
}
// 3. 状態判定とオブジェクト生成
if (record.revokedAt) {
const revokedAt = yield* InvitationRevokedAt(record.revokedAt);
return ok({
kind: "RevokedInvitation" as const,
...base,
revokedAt,
});
}
if (record.acceptedAt) {
const acceptedAt = yield* InvitationAcceptedAt(record.acceptedAt);
return ok({
kind: "AcceptedInvitation" as const,
...base,
acceptedAt,
});
}
const expiresAt = yield* InvitationExpiresAt(record.expiresAt);
if (record.expiresAt <= now) {
return ok({
kind: "ExpiredInvitation" as const,
...base,
expiresAt,
});
}
return ok({
kind: "ActiveInvitation" as const,
...base,
expiresAt,
});
});
};
safeTry のポイント
safeTry は neverthrow が提供するジェネレーター関数です。yield* を使うと、Result から値を取り出せます。エラーの場合は即座に関数全体がエラーを返します。
なお、Invitation は型エイリアスとファクトリ関数で同じ名前を使用しています。TypeScript では型と値は別の名前空間に存在するため、この命名が可能です。
// ok の場合: 値が取り出される
// err の場合: 関数全体が即座にその err を返す
const vInvitationId = yield * InvitationId(record.id);
const vCompanyId = yield * CompanyId(record.companyId);
ポート定義とインフラ層の分離
ドメイン層では「必要な操作」を型として定義します(ポート)。
// domain/invitation/ports.ts
export type FindLatestInvitation = (
companyId: CompanyId,
inviteeEmail: InviteeEmail,
now: Date
) => ResultAsync<Invitation | null, FindLatestInvitationError>;
export type SaveInvitation = (
command: EmailCommandAttached
) => ResultAsync<InvitationSaved, RepositoryError>;
インフラ層ではこのポートの型を使って実装します。
// infrastructure/invitation/repository.ts
import type { FindLatestInvitation } from "../../domain/invitation/ports.js";
export const findLatestInvitation =
(db: DbClient): FindLatestInvitation =>
(companyId, inviteeEmail, now) => {
return ResultAsync.fromPromise(
db
.select()
.from(schema.invitations)
.where(
and(
eq(schema.invitations.companyId, companyId),
eq(schema.invitations.email, inviteeEmail)
)
)
.orderBy(desc(schema.invitations.createdAt))
.limit(1),
(error) => ({
kind: "RepositoryError" as const,
message: error instanceof Error ? error.message : "Unknown error",
})
).andThen((rows) => {
const row = rows[0];
if (!row) return okAsync(null);
return reconstructInvitation(row, now).mapErr((e) =>
e.kind === "DomainValueError" ? mapDomainValueToDataInconsistency(e) : e
);
});
};
DomainValueError から DataInconsistencyError への変換
上記コードで .mapErr() を使ってエラーを変換しています。
return Invitation(row, now).mapErr((e) =>
e.kind === "DomainValueError" ? mapDomainValueToDataInconsistency(e) : e
);
Invitation ファクトリ関数は、DB から取得したレコードを値オブジェクトに変換する際、バリデーションエラーとして DomainValueError を返すことがあります。しかし、DB に保存されているデータがバリデーションに失敗するということは、データの整合性が壊れていることになります。
そのため、インフラ層でこのエラーを DataInconsistencyError に変換しています。
// infrastructure/shared/errorMapping.ts
export const mapDomainValueToDataInconsistency = (
error: DomainValueError
): DataInconsistencyError => ({
kind: "DataInconsistencyError",
message: error.message,
});
呼び出し側は「入力バリデーションの失敗」と「データ整合性の問題」を明確に区別します。
ポイント
-
ResultAsync.fromPromise: Promise の例外をResult型に閉じ込める -
ポート型の使用: 関数の返り値は
FindLatestInvitation型に従う - 依存性逆転: ドメイン層がインフラ層に依存しない
-
エラーの文脈変換:
DomainValueError→DataInconsistencyErrorでエラーの意味を明確化
システム生成値での _unsafeUnwrap() の使用
ハッシュトークンの生成処理において_unsafeUnwrap() を使用しています。
// infrastructure/invitation/hashToken.ts
export const hashToken: HashToken = (tokenPlain) => {
const hash = createHash("sha256").update(tokenPlain).digest("hex");
return InvitationTokenHash(hash)._unsafeUnwrap();
};
理由:システムが生成する値は、バリデーションに失敗しないことが保証されている
createHash("sha256").digest("hex") は必ず 64 文字の 16 進数文字列を返します。InvitationTokenHash のバリデーションルール(64 文字の 16 進数)を満たすことがアルゴリズム上保証されているため、err になることはありません。
このような「システムが生成する値」に対しては、ポートの型定義自体を Result を返さない形にしています。
// domain/invitation/ports.ts
// システム生成用(失敗しない前提)
export type HashToken = (
tokenPlain: InvitationTokenPlain
) => InvitationTokenHash;
これにより、呼び出し側は Result のハンドリングを省略でき、発生しないエラーを型に表現しなくて良くなります。
_unsafeUnwrap()を使って消しても、失敗した場合エラーがスローされるので、ここではハンドリング済みのエラーではなくパニックとして扱うようにしています。
7. テストの容易性
モックが簡単
依存関係がただの関数なので、テスト時に簡単に差し替えられます。
// domain/invitation/workflows/create/index.test.ts
// 依存関係のファクトリ関数
const createDeps = (overrides: Partial<WorkflowDeps> = {}): WorkflowDeps => ({
findLatestInvitation: () => okAsync(null), // 過去の招待なし
checkAlreadyMember: () => okAsync(false), // メンバーではない
getCompanyName: () => okAsync(CompanyName("株式会社テスト")._unsafeUnwrap()),
hashToken: () => InvitationTokenHash("a".repeat(64))._unsafeUnwrap(),
now: new Date("2023-01-01T10:00:00Z"),
...overrides, // 上書きしたい依存だけ渡す
});
おわりに
正直、招待ドメインあんまりロジックないので、普通に注文とかにすればよかったなと思ってます。ユニオンでの表現とか色々多そうですし...
こちら、私がやってみた方法で、間違っているところなど多々あるはずですのでそれを念頭に読んでいただければと思います。
サンプルコードの方に色々載っているのでそちらも見てもらえると嬉しいです。
間違いや自分の認識のアップデートがあれば更新したいし、eslintとかもうちょい追加したいなとは思ってますが、直近あまり時間取れなさそうなのであまり触れないかもです。
Discussion