Zod v4 Codec でスキーマに型変換を埋め込む REST API 設計 #TSKaigi2026

by Ryutaro Yako

Embed

Start on current slide

Slide 1

Slide 1 text

Slide 2

Slide 2 text

Slide 3

Slide 3 text

Slide 4

Slide 4 text

当社はソーシャルメディアを利用した、ソーシャルメディア総合管理ツールや X・LINE・Instagram・TikTokなどSNSマーケティングツールを多数提供しています。 Belugaスタジオ X/Facebook/Instagramなどのアカウントを一元管理できるソーシャルメディア総合管理ツールです。企業のSNS運用をサポートします。 Beluga キャンペーンフォロー&リポストに代表されるXのインスタントウィンをはじめとしたキャンペーンを複数展開しています。質の高いキャンペーンの実施を支援しています。その他 SNSキャンペーンに連動した、生成AIを活用したシステムやプラットフォームが提供する独自ツールやシステム開発も順次行っています。 Copyright ©Unique Vision Company. All Rights Reserved. 事業内容

Slide 5

Slide 5 text

Slide 6

Slide 6 text

Slide 7

Slide 7 text

フルスタック TypeScript の開発プロジェクト API サーバは REST API として実装社内の他のプロジェクトでは Rust で API を開発しており、設計を REST API に統一 tRPC などの利用は見送ることになった技術スタックアプリ技術スタック API サーバ Hono / @hono/zod-openapi フロントエンド Vue.js / hono/client Copyright ©Unique Vision Company. All Rights Reserved. 背景

Slide 8

Slide 8 text

モノレポを生かしてスキーマを共有している型定義バリデーションロジックしかし日時の表現が各層で異なり、変換が必要アプリケーション: Dayjs オブジェクト API 通信: ISO 文字列日時の変換を毎回手動で行うのは大変変換ロジックもスキーマに集約したい apps/ ├── api/ # バックエンド └── client/ # フロントエンド packages/ └── schema/ # 共有スキーマ共有スキーマ共有共有バックエンド API 通信フロントエンド共有スキーマ共有共有バックエンド Dayjs API 通信 string（ISO 文字列）フロントエンド Dayjs Copyright ©Unique Vision Company. All Rights Reserved. 課題

Slide 9

Slide 9 text

日時の変換を毎回手動で行うのは大変 const startAt = dayjs(body.startAt); // ← 手動で string → Dayjs に変換 const endAt = dayjs(body.endAt); startAt: inserted.startAt.toISOString(), // ← 手動で Dayjs → string に変換 endAt: inserted.endAt.toISOString(), app.openapi(postCampaignRoute, async (c) => { const body = c.req.valid("json"); const [inserted] = await db .insert(campaigns) .values({ name: body.name, startAt, endAt }) .returning(); return c.json( response.detail({ uuid: inserted.uuid, name: inserted.name, }), ); }); Copyright ©Unique Vision Company. All Rights Reserved. 課題 — 日時の変換を楽にしたい

Slide 10

Slide 10 text

Slide 11

Slide 11 text

Zod v4.1 から導入された機能 Zod のスキーマでデータを双方向変換できる従来の preprocess / transform は単方向の変換しかできない transform ⼊⼒の型単⽅向のみ出⼒の型 Codec ⼊⼒の型 Dayjs encode decode 出⼒の型 string（ISO 文字列） Copyright ©Unique Vision Company. All Rights Reserved. Zod v4 Codec とは

Slide 12

Slide 12 text

Slide 13

Slide 13 text

日時を双方向変換するスキーマ変換ロジックをスキーマに集約できる利用例変換ロジックを意識せずに使える export const datetimeSchema = () => z.codec( z.iso.datetime(), z.custom((val) => dayjs.isDayjs(val)), { decode: (val) => dayjs(val), encode: (val) => val?.toISOString(), }, ); export const campaignSchema = z.object({ uuid: z.uuid(), name: z.string(), startAt: datetimeSchema(), endAt: datetimeSchema(), }); export const campaignCreateSchema = campaignSchema.omit({ uuid: true }); Copyright ©Unique Vision Company. All Rights Reserved. Zod スキーマの設計

Slide 14

Slide 14 text

Slide 15

Slide 15 text

@hono/zod-openapi でルートを定義するリクエスト・レスポンス両方に Zod スキーマを指定する body: { content: { "application/json": { schema: campaignCreateSchema } } }, "application/json": { schema: detailResponse(campaignSchema) }, export const postCampaignRoute = createRoute({ method: "post", path: "/api/v1/campaigns", request: { }, responses: { 200: { description: "キャンペーン", content: { }, }, }, }); Copyright ©Unique Vision Company. All Rights Reserved. バックエンドでの利用方法

Slide 16

Slide 16 text

ハンドラー実装例 — Codec 導入によりボイラープレート削減 @hono/zod-openapi がリクエストのバリデーションと日時の変換をする @hono/zod-openapi はレスポンスに対しては何もしないユーティリティ response.detail を作成して encode 呼び出しを共通化 encode はスキーマに未定義のプロパティを除去する（ inserted をそのまま渡せる） app.openapi(postCampaignRoute, async (c) => { const body = c.req.valid("json"); const [inserted] = await c.var.db .insert(campaigns) .values({ name: body.name, startAt: body.startAt, endAt: body.endAt }) .returning(); return c.json(response.detail(campaignSchema, inserted)); }); Copyright ©Unique Vision Company. All Rights Reserved. バックエンドでの利用方法

Slide 17

Slide 17 text

Slide 18

Slide 18 text

API クライアントを作成 hc （ hono/client ）を利用する encode / decode をおこなう薄いラッパーを作成 export class Api { client = hc("").api.v1; async postCampaign(data: CampaignCreate): Promise { return requestData( this.client.campaigns.$post, { json: data }, { request: campaignCreateSchema, // encode: Dayjs → string response: campaignSchema, // decode: string → Dayjs }, ); } } Copyright ©Unique Vision Company. All Rights Reserved. フロントエンドでの利用方法

Slide 19

Slide 19 text

フォームでバリデーションするときの注意点 — parse ではなく encode を使うフォームの値は Dayjs オブジェクト parse 方向は string を期待するためエラーになる encode 方向でバリデーションする Vue.js のコンポーザブルで共通化 Dayjs encode parse（decode 方向） string （ISO ⽂字列） const validate = ( schema: T, data: Partial>, ): z.output => { schema.encode(data as z.output); return data as z.output; }; Copyright ©Unique Vision Company. All Rights Reserved. フロントエンドでの利用方法

Slide 20

Slide 20 text

Slide 21

Slide 21 text

Zod v4 Codec を使うと、スキーマに型変換ロジックを埋め込めるハンドラーや API クライアントで変換を意識せずに使える Hono・日時変換を題材にしたが、他のフレームワークやデータ型にも応用できる Zod スキーマ（Codec）共有共有バックエンド Dayjs encode decode API 通信 string（ISO 文字列） decode encode フロントエンド Dayjs Copyright ©Unique Vision Company. All Rights Reserved. まとめ