Zod Codecs で 'use client' を介した Server-Client 間データ転送を強化する

2025/09/26 内容を大幅に修正しています。

変更前は Zod Codec の encode / decode をテレコにして扱ってしまい、「Underlying に brand スキーマを使っても効果がない」問題がありました。

変更後は正しい順番に戻して、名前の違和感を隠蔽するために wrap / unwrap という別名を付けました。加えて、Underlying には brand スキーマを設定して型チェックを強化しました。

diff は次の折りたたみの中にあります。

Markdown の diff 全体

diff --git a/articles/use-client-and-zod-codec-for-data-transfer.md b/articles/use-client-and-zod-codec-for-data-transfer.md
index 5d21670..f5b0d57 100644
--- a/articles/use-client-and-zod-codec-for-data-transfer.md
+++ b/articles/use-client-and-zod-codec-for-data-transfer.md
@@ -236,9 +236,9 @@ Temporal の日付オブジェクトはどうでしょうか？ここでは `Tem
 
 
 - Server Component 側では、《`'use client'` でシリアライズ可能なデータ型》に変換して、Props に渡す。
-  - エンコード（encode）
+  - wrap
 - Client Component 側では、それを受け取って、元の型に復元する
-  - デコード（decode）
+  - unwrap
 
 という少しの手間を掛けさえすれば、とりあえず対応できます。
 
@@ -265,10 +265,10 @@ sequenceDiagram
 
   S1->>S1: 現在時刻を取得する
   note over S1: Temporal.Now<br/>.plainDateTimeISO()
-  S1->>S2: encode
+  S1->>S2: wrap
   S2-->>C2: 💌 RSC Payload
   note over S2,C2: 'use client' を介して境界を越える
-  C2->>C1: decode
+  C2->>C1: unwrap
 ```
 
 とりあえずこれで目的は果たせますが、しかし、実装するとなると、なんかゴチャッとして使いにくいユーティリティーになる匂いがします。
@@ -277,9 +277,9 @@ JavaScript/TypeScript は名前空間機能がなく、関数の名前は長〜
 
 ```tsx
 // Server Component 側: PlainDateTime -> string
-import { encodeFromPlainDateTime } from "#/utils/react/codecs/plain-date-time";
+import { wrapPlainDateTime } from "#/utils/react/sharable/plain-date-time";
 // Client Component 側: string -> PlainDateTime
-import { decodeIntoPlainDateTime } from "#/utils/react/codecs/plain-date-time";
+import { unwrapIntoPlainDateTime } from "#/utils/react/sharable/plain-date-time";
 
 // 型の情報を SSoT （信頼できる唯一の情報源）として提供したい
 import {
@@ -288,7 +288,7 @@ import {
 } from "#/utils/react/codecs/plain-date-time";
 ```
 
-![VSCode の画面。plainDateTime と入力したところ、ShowPlainDateTime, SharablePlainDatTime, decodeToPlainDateTime, encodeFromPlainDateTime の 4つをimport 補完の候補として見せてくれている。](/images/use-client-and-zod-codec-for-data-transfer/bad-import-interpolation.png)
+![VSCode の画面。plainDateTime と入力している途中で、import 補完の候補として ShowPlainDateTime, wrapPlainDateTime, unwrapIntoPlainDateTime, SharablePlainDatTime の 4つを見せてくれている。カーソルは 2つめの wrapPlainDateTime に合っている。](/images/use-client-and-zod-codec-for-data-transfer/bad-import-interpolation.png)
 _import 自動補完が全く役に立たない訳ではないが…_
 
 「動詞が最初に来て、その後に目的語が来る」このパターンは、UI デザインの文脈では「タスク指向 UI」、つまりユーザーに「作る側の都合」を押し付ける、悪い UI の設計とされるでしょう。
@@ -320,10 +320,10 @@ _import 自動補完が全く役に立たない訳ではないが…_
 
 （ツリーシェイキングは犠牲になりますが、それほど大きなコード量にはならないので妥協することにします。）
 
-```ts:utils/react/codecs/_codec
-export type Codec<in out S, in out U> = {
-  decode: (u: U) => S;
-  encode: (s: S) => U;
+```ts:utils/react/sharable/_sharable
+export type Sharable<in out S, in out U> = {
+  wrap: (s: S) => U;
+  unwrap: (u: U) => S;
 };
 
 export type ShapedType<C> = C extends Codec<infer S, infer _> ? S : never;
@@ -334,11 +334,11 @@ export type UnderlyingType<C> = C extends Codec<infer _, infer U>
 
 ```ts:utils/react/sharable/plain-date-time
 import { Temporal } from "temporal-polyfill";
-import type { Codec } from "./_codec";
+import type { Sharable } from "./_sharable";
 
-export const SharablePlainDateTime: Codec<Temporal.PlainDateTime, string> = {
-  decode: (string) => Temporal.PlainDateTime.from(string),
-  encode: (dateTime) => dateTime.toString(),
+export const SharablePlainDateTime: Sharable<Temporal.PlainDateTime, string> = {
+  wrap: (dateTime) => dateTime.toString(),
+  unwrap: (string) => Temporal.PlainDateTime.from(string),
 } 
 ```
 
@@ -347,9 +347,9 @@ import { type ShapedType, type UnderlyingType } "#/utils/react/sharable";
 import { SharablePlainDateTime } from "#/utils/react/sharable/plain-date-time";
 
 // Server Component 側: PlainDateTime -> string
-SharablePlainDateTime.encode(plainDateTime);
+SharablePlainDateTime.wrap(plainDateTime);
 // Client Component 側: string -> PlainDateTime
-SharablePlainDateTime.decode(underlying);
+SharablePlainDateTime.unwrap(underlying);
 
 // sharable ユーティリティを使って、SSoT としての Codec オブジェクトから型情報を抽出できる
 type Props = {
@@ -360,8 +360,8 @@ type PlainDateTime = ShapedType<typeof SharablePlainDateTime>;
 
 こうすれば、
 
-- エンコード関数
-- デコード関数
+- wrap 関数
+- unwrap 関数
 - Shaped 型の情報
 - Underlying 型の情報
 
@@ -382,7 +382,67 @@ Zod は v4.1 から、Codecs という双方向の型変換をサポートする
 https://zod.dev/codecs
 
 
-この Codec の仕組みは、そのまま今回のユーティリティに採用できます。
+この Codec の仕組みは、そのまま今回のユーティリティを実装するための「型枠」として採用できます。
+
+```ts
+z.codec(in_, out, { decode, encode })
+```
+
+自前実装の Sharable ユーティリティと、codec の機能の対応関係は、以下のようになります。
+
+| Sharable | codec の引数・オプション |
+| :-- | :-- | 
+| Shaped | `_in` |
+| Underlying | `out` |
+| wrap | `decode` |
+| unwrap | `encode` |
+
+unwrap と encode みたいなところが捻れてる感じで難しいですが、Codec の設計思想に合わせるには、こうする必要があります。
+
+### brand を使う
+
+[Zod には、brand という、BrandedType パターンを利用するための機能も用意されています。](https://zod.dev/api#branded-types)
+
+Underlying (`out`) に brand を使ったスキーマを設定してあげれば、`unwrap` するときに、「`wrap` を経たデータ」のみを受け付けて、生の文字列を排除できるようになります。
+
+```ts:_sharable-plain-date-time.ts
+export const SharablePlainDateTime = sharable(
+  z.instanceof(Temporal.PlainDateTime),
+  z.string().brand("SharablePlainDateTime"), // ここで brand を使う
+  {
+    wrap: (dateTime) => dateTime.toString(),
+    unwrap: (string) => Temporal.PlainDateTime.from(string),
+  }
+);
+```
+
+```tsx
+import { SharablePlainDateTime } from "./_sharable-plain-date-time";
+import {
+  unwrap,
+  type ShapedType,
+  type UnderlyingType,
+} from "./_utils/share-value-by-codec";
+
+// ✅️ 正しい使い方
+type Props = {
+  nowPlainDateTime: UnderlyingType<typeof SharablePlainDateTime>;
+};
+
+export function ShowPlainDateTime({
+  nowPlainDateTime: _nowPlainDateTime,
+}: Props) {
+  const nowPlainDateTime = unwrap(SharablePlainDateTime, _nowPlainDateTime);
+
+// 🔴 生のデータは排除してくれる
+  const _1 = unwrap(SharablePlainDateTime, "Raw String");
+  //                                       ^^^^^^^^^^^^
+  // コンパイルエラー: 型 'string' の引数を型 'string & $brand<"SharablePlainDateTime">' のパラメーターに割り当てることはできません。
+}
+```
+
+この BrandedType パターンによる防御は、ケアレスミスの防止に大きく寄与することが期待できます。
+
 
 :::message
 #### 既存のライブラリを使うメリット
@@ -438,35 +498,58 @@ src/app/rsc-date/temporal/
 ```ts:src/app/rsc-date/temporal/_utils/share-value-by-codec.ts
 import * as z from "zod/mini";
 
+export { encode as unwrap, decode as wrap } from "zod/mini";
+
+// encode -> unwrap, decode -> wrap と翻訳する
+type TranslateOptions<Opts> = Opts extends {
+  encode: infer E;
+  decode: infer D;
+}
+  ? { unwrap: E; wrap: D }
+  : Opts;
+
+type SharableParams<
+  S extends z.core.SomeType,
+  U extends z.core.SomeType
+> = TranslateOptions<Parameters<typeof z.codec<S, U>>[2]>;
+
+type SharableCodec<
+  S extends z.core.SomeType,
+  U extends z.core.SomeType
+> = ReturnType<typeof z.codec<S, U>>;
+
 /**
- * - encode: Shaped -> Underlying
- * - decode: Underlying -> Shaped
- *
- * - Shaped: サーバー <-> クライアント 間で共有したいが、直列化が不可能なデータ型
- * - Underlying: "use client" で直列化可能なデータ型
+ * Shaped（"use client" での直列化が不可能なデータ）を、
+ * Underlying（直列化可能なデータ）に wrap する機能と、
+ * その逆方向の変換で元のデータに戻す（unwrap）機能を集約した
+ * Codec スキーマ を提供する。
  */
-export { codec } from "zod/mini";
-export { encode, decode } from "zod/mini";
+export function sharable<
+  S extends z.core.SomeType,
+  U extends z.core.SomeType = z.core.$ZodType
+>(s: S, u: U, params: SharableParams<S, U>): SharableCodec<S, U> {
+  return z.codec(s, u, { encode: params.unwrap, decode: params.wrap });
+}
 
-export type UnderlyingType<T> = z.input<T>;
-export type ShapedType<T> = z.output<T>;
+export type ShapedType<T> = z.input<T>;
+export type UnderlyingType<T> = z.output<T>;
 ```
 
 ```ts:src/app/rsc-date/temporal/_sharable-plain-date-time.ts
-import { z } from "zod/mini";
+import * as z from "zod/mini";
 import { Temporal } from "temporal-polyfill";
-import { codec } from "./_utils/share-value-by-codec";
+import { sharable } from "./_utils/share-value-by-codec";
 
 /**
  * - 表面的に利用可能な型: PlainDateTime
  * - "use client" で直列化するあめの型: string
  */
-export const SharablePlainDateTime = codec(
-  z.string(),
+export const SharablePlainDateTime = sharable(
   z.instanceof(Temporal.PlainDateTime),
+  z.string().brand("SharablePlainDateTime"),
   {
-    decode: (string) => Temporal.PlainDateTime.from(string),
-    encode: (dateTime) => dateTime.toString(),
+    wrap: (dateTime) => dateTime.toString(),
+    unwrap: (string) => Temporal.PlainDateTime.from(string),
   }
 );
 ```
@@ -479,7 +562,7 @@ import Link from "next/link";
 
 import { ShowPlainDateTime } from "./show-plain-date-time";
 import { SharablePlainDateTime } from "./_sharable-plain-date-time";
-import { encode } from "./_utils/share-value-by-codec";
+import { wrap } from "./_utils/share-value-by-codec";
 import styles from "./page.module.scss";
 
 export const metadata: Metadata = {
@@ -501,7 +584,7 @@ export default async function Page({}: PageProps<"/rsc-date/temporal">) {
       <h2>アクセス時のサーバー内部の現在時刻</h2>
       <div className={styles.cluster}>
         <ShowPlainDateTime
-          nowPlainDateTime={encode(SharablePlainDateTime, nowPlain)}
+          nowPlainDateTime={wrap(SharablePlainDateTime, nowPlain)}
         />
       </div>
     </div>
@@ -514,7 +597,7 @@ export default async function Page({}: PageProps<"/rsc-date/temporal">) {
 
 import { SharablePlainDateTime } from "./_sharable-plain-date-time";
 import {
-  decode,
+  unwrap,
   type ShapedType,
   type UnderlyingType,
 } from "./_utils/share-value-by-codec";
@@ -528,7 +611,7 @@ type Props = {
 export function ShowPlainDateTime({
   nowPlainDateTime: _nowPlainDateTime,
 }: Props) {
-  const nowPlainDateTime = decode(SharablePlainDateTime, _nowPlainDateTime);
+  const nowPlainDateTime = unwrap(SharablePlainDateTime, _nowPlainDateTime);
 
   return (
     <div className={styles.card}>
diff --git a/images/use-client-and-zod-codec-for-data-transfer/bad-import-interpolation.png b/images/use-client-and-zod-codec-for-data-transfer/bad-import-interpolation.png
index 4c6eecb..9d1bb27 100644
Binary files a/images/use-client-and-zod-codec-for-data-transfer/bad-import-interpolation.png and b/images/use-client-and-zod-codec-for-data-transfer/bad-import-interpolation.png differ

利用した主なパッケージのバージョン

• "next": 15.5.3 (App Router を利用)
• "react": 19.x 系 (Next.js の事情があるので、具体的なバージョンは敢えて伏せる)
• "temporal-polyfill": 0.3.0
• "zod": 4.1.9

'use client' は、サーバーからクライアントへと、描画用データを送信する境界を表すマーカーである ということは、広く知られています。

https://zenn.dev/yumemi_inc/articles/use-client-directive-explained-with-gssp

上記の記事の中では軽く触れるだけにとどめましたが、実は、 'use client' は「素の JSON」よりも多種多様なデータの転送に対応しています。

RSC が「サーバー側 / ブラウザ側 のコードをシームレスに繋ぎ合わせる」技術であることが良くわかりますね。

サーバコンポーネントからクライアントコンポーネントに渡される props の値は、シリアライズ可能 (serializable) である必要があります。

シリアライズ可能な props には以下のものがあります：

• プリミティブ
  • 文字列
  • 数値
  • bigint
  • ブーリアン
  • undefined
  • null
  • シンボル、ただし Symbol.for を通じてグローバルシンボルレジストリに登録されたシンボルのみ
• シリアライズ可能な値を含んだ Iterable
  • 文字列
  • 配列
  • Map
  • Set
  • TypedArray と ArrayBuffer
• Date
• プレーンなオブジェクト: オブジェクト初期化子で作成され、シリアライズ可能なプロパティを持つもの
• サーバアクション (server action) としての関数
• クライアントまたはサーバコンポーネントの要素（JSX）
• プロミス

出典:

'use client' だけで Date を送れる

先ほど述べた通り、 'use client' でマークされた Client Component に、Server Component から Date オブジェクトを渡すことは可能です。

以下の例では、 Date をサーバーからクライアントに送る口実として、「サーバー側で現在時刻を取得して、ブラウザ側でそれを端末のタイムゾーンに基づいて表示する」という、Client Component 抜きでは実装しづらい機能を実装しています。

実際の画面の様子: 世界協定時の時刻と、PDT（ブラウザ側のタイムゾーンであるサンフランシスコの現地時刻）が表示されている

▼コンポーネント間でデータが受け渡される様子の概略図

(抜粋) src/app/rsc-date/date/page.tsx

// import 一部省略
import { LocaleAwareDate } from "./locale-aware-date";
// 中略
export default async function Page({}: PageProps<"/rsc-date/date">) {
  await connection();

  return (
    <div className={styles.container}>
      {/* 中略 */}
      <section>
        <h2>アクセスした時刻:</h2>
        <LocaleAwareDate value={new Date()} />
      </section>
    </div>
  );
};

(抜粋) src/app/rsc-date/date/locale-aware-date.tsx

"use client";

// import 省略
/** ブラウザ側のタイムゾーンでの日時を表示する */
const formatter = new Intl.DateTimeFormat(undefined, {
  /* 中略 */
});

type Props = {
  value: Date;
};

export function LocaleAwareDate({ value }: Props) {
  // SSR 時: undefined
  // CSR 時には、ブラウザ側のロケールで表示
  const localDate = useSyncExternalStore(
    () => () => {},
    () => formatter.format(value),
    () => undefined
  );
  return (
    <div className={styles.root}>
      {/* 中略 */}
      <div>
        <span className={styles.prefix}>ブラウザ側タイムゾーンでの時刻: </span>
        <span className={styles.time}>{localDate}</span>
      </div>
    </div>
  );
}

ソースコード全文

src/app/rsc-date/date/page.tsx

import { type Metadata } from "next";
import { connection } from "next/server";
import Link from "next/link";

import { LocaleAwareDate } from "./locale-aware-date";
import styles from "./page.module.scss";

export const metadata: Metadata = {
  title: "Date の振る舞いテスト",
};

export default async function Page({}: PageProps<"/rsc-date/date">) {
  await connection();

  return (
    <div className={styles.container}>
      <nav className={styles.nav}>
        <Link href="/rsc-date" className={styles.navLink}>
          ← Back to RSC Date Examples
        </Link>
      </nav>
      <h1>現地時刻の振る舞いテスト</h1>
      <section>
        <h2>アクセスした時刻:</h2>
        <LocaleAwareDate value={new Date()} />
      </section>
    </div>
  );
}

src/app/rsc-date/date/locale-aware-date.tsx

"use client";

import { useSyncExternalStore } from "react";

import styles from "./locale-aware-date.module.scss";

/**
 * ブラウザ側のタイムゾーンでの日時を表示する
 */
const formatter = new Intl.DateTimeFormat(undefined, {
  weekday: "long",
  year: "numeric",
  month: "long",
  day: "numeric",
  hour: "numeric",
  minute: "numeric",
  second: "numeric",
  timeZoneName: "short",
});

type Props = {
  value: Date;
};

export function LocaleAwareDate({ value }: Props) {
  // SSR 時: undefined
  // CSR 時には、ブラウザ側のロケールで表示
  const localDate = useSyncExternalStore(
    () => () => {},
    () => formatter.format(value),
    () => undefined
  );
  // 下は Hydration Error になるのでダメ！
  // const localDate = formatter.format(value);
  return (
    <div className={styles.root}>
      <div>
        <span className={styles.prefix}>ISO: </span>
        <time className={styles.time}>{value.toISOString()}</time>
      </div>
      <div>
        <span className={styles.prefix}>ブラウザ側タイムゾーンでの時刻: </span>
        <span className={styles.time}>{localDate}</span>
      </div>
    </div>
  );
}

Zod Codecs と組み合わせれば Temporal も送れる

Temporal の日付オブジェクトはどうでしょうか？ここでは Temporal.PlainDateTime 型で試してみましょう。

（少なくとも）2025/09/24 現在では、 'use client' でシリアライズ可能なリストに列挙されておらず、そのままでは送信できません。

無理やり渡そうとすると、このようなエラーが表示されます。

（page.tsx は Server Component で、ShowPlainDateTime コンポーネントには 'use client' ディレクティブを設定しています。）

しかし、これで終わりではありません。

シリアライズ可能なデータに変換して送信する

• Server Component 側では、《'use client' でシリアライズ可能なデータ型》に変換して、Props に渡す。
  • wrap
• Client Component 側では、それを受け取って、元の型に復元する
  • unwrap

という少しの手間を掛けさえすれば、とりあえず対応できます。

これ以降、2つの型変数 Shaped / Underlying の名称を使って説明します。

• Shaped（実際にビジネスロジックを書くために利用する型）
  • Temporal.PlainDateTime 型
• Underlying（'use client' でシリアライズ可能なデータ型）
  • string

とりあえずこれで目的は果たせますが、しかし、実装するとなると、なんかゴチャッとして使いにくいユーティリティーになる匂いがします。

JavaScript/TypeScript は名前空間機能がなく、関数の名前は長〜〜い動詞句になってしまい、いろいろな情報を提供しようとすると、それぞれバラバラな名前になってしまうので、こんな感じになってしまいます。

// Server Component 側: PlainDateTime -> string
import { wrapPlainDateTime } from "#/utils/react/sharable/plain-date-time";
// Client Component 側: string -> PlainDateTime
import { unwrapIntoPlainDateTime } from "#/utils/react/sharable/plain-date-time";

// 型の情報を SSoT （信頼できる唯一の情報源）として提供したい
import {
  type PlainDateTime,
  type PlainDateTimeUnderlying, // つまり string
} from "#/utils/react/codecs/plain-date-time";

import 自動補完が全く役に立たない訳ではないが…

「動詞が最初に来て、その後に目的語が来る」このパターンは、UI デザインの文脈では「タスク指向 UI」、つまりユーザーに「作る側の都合」を押し付ける、悪い UI の設計とされるでしょう。

（対義語は「オブジェクト指向 UI」（OOUI）で、作り手の都合を廃して、ユーザーの脳内のイメージに合わせて作る、理想的な設計を指しています。）

ユーティリティ関数のたぐいも、実装者である同僚 etc. をユーザーと考えると一種の UI なので、「よい UI」を目指せるなら目指したいですよね？

最悪なのは 〇〇To▲▲ / ▲▲To〇〇

plainDateTimeToString() / stringToPlainDateTime じゃだめなの？

という疑問もあるかと思います。

僕の意見としては、悪いとまでは言わないが、少し劣っていると思います。 このような名前は目的不在で、手段だけが露出しているからです。

• 目的:「PlainDateTime を Server -> Client でなるべくシームレスに共有して使いたい」
• 手段:「PlainDateTime を string に変換する」（および、その逆方向の変換）

もちろん、手段が大事な場面もありますが、今回のユーティリティは、目的駆動で設計・実装したものなので、名前もそれに追従して「目的」ベースにします。

（もちろん、内部で手段に基づいた名前のユーティリティがあっても良いですが、「表に出す/内部的にとどめる」のようなメリハリが必要です。メリハリがない utils は、どこにどの機能があるのか探しづらく、ユーザーに混乱をもたらします。）

SSoT オブジェクトに全てを集約する

では OOUI 的にするために、1つのオブジェクトに情報を集約して、その SSoT（信頼できる唯一の情報源）から情報を引き出すためのユーティリティと組み合わせて利用できるようにしてみましょう。

（ツリーシェイキングは犠牲になりますが、それほど大きなコード量にはならないので妥協することにします。）

utils/react/sharable/_sharable

export type Sharable<in out S, in out U> = {
  wrap: (s: S) => U;
  unwrap: (u: U) => S;
};

export type ShapedType<C> = C extends Codec<infer S, infer _> ? S : never;
export type UnderlyingType<C> = C extends Codec<infer _, infer U>
  ? U
  : never;

utils/react/sharable/plain-date-time

import { Temporal } from "temporal-polyfill";
import type { Sharable } from "./_sharable";

export const SharablePlainDateTime: Sharable<Temporal.PlainDateTime, string> = {
  wrap: (dateTime) => dateTime.toString(),
  unwrap: (string) => Temporal.PlainDateTime.from(string),
} 

import { type ShapedType, type UnderlyingType } "#/utils/react/sharable";
import { SharablePlainDateTime } from "#/utils/react/sharable/plain-date-time";

// Server Component 側: PlainDateTime -> string
SharablePlainDateTime.wrap(plainDateTime);
// Client Component 側: string -> PlainDateTime
SharablePlainDateTime.unwrap(underlying);

// sharable ユーティリティを使って、SSoT としての Codec オブジェクトから型情報を抽出できる
type Props = {
  now: UnderlyingType<typeof SharablePlainDateTime>,
};
type PlainDateTime = ShapedType<typeof SharablePlainDateTime>;

こうすれば、

• wrap 関数
• unwrap 関数
• Shaped 型の情報
• Underlying 型の情報

が全て、SSoT たる PlainDateTimeCodec オブジェクトから派生的に得られるようになっています。これはかなり OOUI 的でわかりやすいと思います。

"#/utils/react/sharable" ユーティリティの使い方をユーザーが知っておく必要があるのは不便に思われるかもしれませんが、情報がうまく集約されたことと比べれば、必要な学習コストだと割り切っても良いでしょう。

Zod Codecs のパターンに乗っかる

上記では、お手製の Codec ユーティリティを使って、シリアライゼーションのための双方向の型変換にパターンを規定してあげて、取り扱いを容易にしました。

しかし、実は、このパターンを提供してくれるようになったライブラリがあります。

それが Zod です。

Zod は v4.1 から、Codecs という双方向の型変換をサポートする仕組みを提供しています。（従来のスキーマは、単一方向の型変換のみサポートしていました。）

https://zod.dev/codecs

この Codec の仕組みは、そのまま今回のユーティリティを実装するための「型枠」として採用できます。

z.codec(in_, out, { decode, encode })

自前実装の Sharable ユーティリティと、codec の機能の対応関係は、以下のようになります。

Sharable	codec の引数・オプション
Shaped	_in
Underlying	out
wrap	decode
unwrap	encode

unwrap と encode みたいなところが捻れてる感じで難しいですが、Codec の設計思想に合わせるには、こうする必要があります。

brand を使う

Zod には、brand という、BrandedType パターンを利用するための機能も用意されています。

Underlying (out) に brand を使ったスキーマを設定してあげれば、unwrap するときに、「wrap を経たデータ」のみを受け付けて、生の文字列を排除できるようになります。

_sharable-plain-date-time.ts

export const SharablePlainDateTime = sharable(
  z.instanceof(Temporal.PlainDateTime),
  z.string().brand("SharablePlainDateTime"), // ここで brand を使う
  {
    wrap: (dateTime) => dateTime.toString(),
    unwrap: (string) => Temporal.PlainDateTime.from(string),
  }
);

import { SharablePlainDateTime } from "./_sharable-plain-date-time";
import {
  unwrap,
  type ShapedType,
  type UnderlyingType,
} from "./_utils/share-value-by-codec";

// ✅️ 正しい使い方
type Props = {
  nowPlainDateTime: UnderlyingType<typeof SharablePlainDateTime>;
};

export function ShowPlainDateTime({
  nowPlainDateTime: _nowPlainDateTime,
}: Props) {
  const nowPlainDateTime = unwrap(SharablePlainDateTime, _nowPlainDateTime);

// 🔴 生のデータは排除してくれる
  const _1 = unwrap(SharablePlainDateTime, "Raw String");
  //                                       ^^^^^^^^^^^^
  // コンパイルエラー: 型 'string' の引数を型 'string & $brand<"SharablePlainDateTime">' のパラメーターに割り当てることはできません。
}

この BrandedType パターンによる防御は、ケアレスミスの防止に大きく寄与することが期待できます。

既存のライブラリを使うメリット

Codec ユーティリティは、「ユーティリティのためのユーティリティ」と言えるような存在です。#/utils/react/sharable/plain-date-time のような、個々の《具体的なユーティリティ》に制約を加えて、その品質を安定させる働きがあります。

---

「ユーティリティ」とは、アプリケーションのコードの中に繰り返し登場して、1つの部品として成り立つようなカタマリを取り出しててできるモノです。

筋の良いユーティリティは、コード全体の統一感や、ひいては品質の安定に繋がります。

しかし、ユーティリティの設計がヘタクソだと、

• 逆に、ユーザー側のボイラープレートが増える
• 異常系を握りつぶしてしまい、型情報から消えてしまい。ユーザー側からは分かりづらい

ということに繋がり、かえってアプリケーションの品質の低下に繋がります。

---

であれば、 「ユーティリティのためのユーティリティ」の筋が悪いと、コード全体への悪影響は、もっと大きいものになる ことは明らかです。

ライブラリを使おうという話題になると「ロックインしたくない〜」と紋切り型の反発コメントが目につきますが、

「設計力の低い人がユーティリティ or ユーティリティを自作しようとして、切り出し方を間違って筋の悪いのを作り込んでしまい、ソースコードがめちゃくちゃになる」という損失を考えたら、既存のライブラリの使える機能を見つけて、それを使うほうが確実だと思います。

どうしても心配なら、Codec を自作したように、設計意図だけをパクって自前の内部的なユーティリティとして実装しなおしても良いです。

完成品。ブラウザ側のタイムゾーン（「サンフランシスコ」に設定されている）に左右されず、アクセス時のサーバー内部（JST）の現在時刻を表示できている。

比較用: Date の例では、世界協定時の時刻と、PDT（ブラウザ側のタイムゾーンであるサンフランシスコの現地時刻）を表示していた

ソースコード

以下に、ソースコードの配置およびその本文を示します。（CSS Module ファイルについては、省略）

src/app/rsc-date/temporal/
├── _utils/
│   └── share-value-by-codec.ts        # Codec ユーティリティ
├── _sharable-plain-date-time.ts       # Zod Codec の定義
├── page.tsx                           # ページコンポーネント（Server）
├── page.module.scss                   # 同コンポーネントのスタイル
├── show-plain-date-time.tsx           # 日付表示コンポーネント（`'use client'` あり）
└── show-plain-date-time.module.scss   # 同コンポーネントのスタイル

src/app/rsc-date/temporal/_utils/share-value-by-codec.ts

import * as z from "zod/mini";

export { encode as unwrap, decode as wrap } from "zod/mini";

// encode -> unwrap, decode -> wrap と翻訳する
type TranslateOptions<Opts> = Opts extends {
  encode: infer E;
  decode: infer D;
}
  ? { unwrap: E; wrap: D }
  : Opts;

type SharableParams<
  S extends z.core.SomeType,
  U extends z.core.SomeType
> = TranslateOptions<Parameters<typeof z.codec<S, U>>[2]>;

type SharableCodec<
  S extends z.core.SomeType,
  U extends z.core.SomeType
> = ReturnType<typeof z.codec<S, U>>;

/**
 * Shaped（"use client" での直列化が不可能なデータ）を、
 * Underlying（直列化可能なデータ）に wrap する機能と、
 * その逆方向の変換で元のデータに戻す（unwrap）機能を集約した
 * Codec スキーマ を提供する。
 */
export function sharable<
  S extends z.core.SomeType,
  U extends z.core.SomeType = z.core.$ZodType
>(s: S, u: U, params: SharableParams<S, U>): SharableCodec<S, U> {
  return z.codec(s, u, { encode: params.unwrap, decode: params.wrap });
}

export type ShapedType<T> = z.input<T>;
export type UnderlyingType<T> = z.output<T>;

src/app/rsc-date/temporal/_sharable-plain-date-time.ts

import * as z from "zod/mini";
import { Temporal } from "temporal-polyfill";
import { sharable } from "./_utils/share-value-by-codec";

/**
 * - 表面的に利用可能な型: PlainDateTime
 * - "use client" で直列化するあめの型: string
 */
export const SharablePlainDateTime = sharable(
  z.instanceof(Temporal.PlainDateTime),
  z.string().brand("SharablePlainDateTime"),
  {
    wrap: (dateTime) => dateTime.toString(),
    unwrap: (string) => Temporal.PlainDateTime.from(string),
  }
);

src/app/rsc-date/temporal/page.tsx

import { Temporal } from "temporal-polyfill";
import { type Metadata } from "next";
import { connection } from "next/server";
import Link from "next/link";

import { ShowPlainDateTime } from "./show-plain-date-time";
import { SharablePlainDateTime } from "./_sharable-plain-date-time";
import { wrap } from "./_utils/share-value-by-codec";
import styles from "./page.module.scss";

export const metadata: Metadata = {
  title: "Temporal.PlainDateTime の振る舞いテスト",
};

export default async function Page({}: PageProps<"/rsc-date/temporal">) {
  await connection();
  const nowPlain = Temporal.Now.plainDateTimeISO();

  return (
    <div className={styles.container}>
      <nav className={styles.nav}>
        <Link href="/rsc-date" className={styles.navLink}>
          ← Back to RSC Date Examples
        </Link>
      </nav>
      <h1>Temporal.PlainDateTime の振る舞いテスト</h1>
      <h2>アクセス時のサーバー内部の現在時刻</h2>
      <div className={styles.cluster}>
        <ShowPlainDateTime
          nowPlainDateTime={wrap(SharablePlainDateTime, nowPlain)}
        />
      </div>
    </div>
  );
}

src/app/rsc-date/temporal/show-plain-date-time.tsx

"use client";

import { SharablePlainDateTime } from "./_sharable-plain-date-time";
import {
  unwrap,
  type ShapedType,
  type UnderlyingType,
} from "./_utils/share-value-by-codec";

import styles from "./show-plain-date-time.module.scss";

type Props = {
  nowPlainDateTime: UnderlyingType<typeof SharablePlainDateTime>;
};

export function ShowPlainDateTime({
  nowPlainDateTime: _nowPlainDateTime,
}: Props) {
  const nowPlainDateTime = unwrap(SharablePlainDateTime, _nowPlainDateTime);

  return (
    <div className={styles.card}>
      <span>フォーマット済み: </span>
      <span>{formatDateTime(nowPlainDateTime)}</span>
    </div>
  );
}

const formatDateTime = (d: ShapedType<typeof SharablePlainDateTime>) => {
  const year = d.year;
  const month = d.month;
  const day = d.day;
  const hour = d.hour.toString().padStart(2, "0");
  const minute = d.minute.toString().padStart(2, "0");
  const second = d.second.toString().padStart(2, "0");
  return `${year}年${month}月${day}日 ${hour}:${minute}:${second}`;
};

他にもいろいろな Codec があるよ

Zod の Codec としては、他にもいろいろなモノがあります。

https://zod.dev/codecs?id=stringtourl#useful-codecs

先述の通り、'use client' は Date とかもサポートしているので、Codec が必要になるケースは多くないと思いますが、URL を string にシリアライズする codec なんかは 'use client' と合わせて使えるかもしれません。

Codec、面白そうなので、必要な場面があれば使ってみたいところですね！

まとめ

'use client' でのシリアライズ処理においては、Date など、JSON よりも広い範囲のデータがサポートされており、RSC の「サーバー側 / ブラウザ側 のコードをシームレスに繋ぎ合わせる」というコンセプト を体現しています。

Temporal の各型のように、サポートされていないデータ型もありますが、Zod の Codecs 機能 を使えば、わずかなボイラープレートだけで「シリアライズ可能な形に変換 / そこからもとに戻す」処理を追記できるようになり、ある程度の「シームレスさ」をキープできます。

もっと広い視点でみると、Zod や Valibot のようなスキーマライブラリは、単なるフォームやJSONオブジェクトの検証だけでなく、「Opaque Type のように、単一の値をラップする」みたいな使い方まで可能だと考えています。

いわゆる "Parse, don't validate" 原則に従って運用することよって、生の TS の型チェックよりも強力な「静的なチェック」を導入して、実行時エラーの発生しうる範囲を限定することによって、ソースコードを読みやすくする力があると考えています。

Codecs に限らず、スキーマライブラリのポテンシャルが最大限に活用され、世界中のコードがもっと堅牢になることを願って、この記事を締めくくります。

個人的には valibot 派なので、valibot にも Codecs 機能が付くのを期待していますが、Issue が立っているものの、まだ調査中のようです

関連記事

https://zenn.dev/terrierscript/articles/2023-06-05-temporal

https://zenn.dev/terrierscript/books/2023-01-typed-zod