feat(next-typed-href): require explicit type arguments on routes()

[akameco]

Summary

• defineTypedHref.routes() / defineTypedHrefWithNuqs.routes() を型引数なしで呼べないように変更
• エラーは .routes() 呼び出し行自体 に出る (downstream の .$href(...) ではなく)
• 型レベルのみの変更 — ランタイム挙動は変わらない

背景

.routes() には型引数 <Routes, RouteParamsMap> が必要だが、省略しても TypeScript は Routes を制約上限 string として推論し、結果的に型安全性が静かに失われていた。

// before: 動くが型安全性ゼロ
const { $href } = defineTypedHref.routes();
$href({ route: "/anything-goes" });  // ✅ コンパイル通る (悪い意味で)

このPRで .routes() 行に直接エラーを出して早期検知する。

// after
defineTypedHref.routes();
// ❌ Expected 1 arguments, but got 0.   ← この行で停止

実装

common/types.ts に汎用ヘルパを追加:

export type RequireExplicitRoutesArgs<Routes extends string> = string extends Routes
  ? [
      pass_Routes_and_RouteParamsMap_as_type_arguments:
        "routes<Routes, RouteParamsMap>() requires explicit type arguments",
    ]
  : [];

routes のシグネチャに conditional rest parameter として適用:

type TypedHrefBuilder = {
  routes: <R extends string, M extends Record<R, ...>>(
    ...args: RequireExplicitRoutesArgs<R>
  ) => { $href: ... };
};

仕組み:

• ユーザーが .routes<MyRoutes, MyMap>() と書く → Routes = MyRoutes → rest tuple が [] → 引数 0 で OK
• ユーザーが .routes() と書く → Routes = string (制約上限) → rest tuple が [phantom_arg] → 引数 0 で "Expected 1 arguments, but got 0"

なぜ rest parameter にしたか

最初は returns 型を error brand object に置き換える案 (RequireExplicitRoutes<R, B> → { __error: "..." }) を試したが、以下の欠点があった:

• エラーが downstream の .$href(...) で発火するため、ユーザーは .routes() まで OK と誤解しがち
• ランタイム impl との型ズレを埋めるため as unknown as TypedHrefBuilder["routes"] のキャストが必要

rest parameter 案ではエラーが .routes() 行に出る上、ランタイム impl のシグネチャと型宣言が自然に一致するためキャスト不要。

IDE 体験

ホバーすると以下が見える:

routes<R, M>(
  pass_Routes_and_RouteParamsMap_as_type_arguments:
    "routes<Routes, RouteParamsMap>() requires explicit type arguments"
): { $href: ... }

パラメータ名が指示、パラメータ型 (string literal) がメッセージという役割分離。

Breaking change?

技術的には型レベルの破壊的変更だが、.routes() を型引数なしで呼んでいたコードは型安全性が崩れた状態だったので、修正されるべきもの。changeset は minor 扱い。

Test plan

• pnpm --filter @plainbrew/next-typed-href test run — 52テスト全通過
• defineTypedHref.routes() で // @ts-expect-error が成立すること (TS2554: Expected 1 arguments, but got 0)
• defineTypedHref.routes<R, M>() 明示時に通常の builder が返ること
• defineTypedHrefWithNuqs 側も同様の挙動

🤖 Generated with Claude Code

[amotarao]

ちょいコメント

[amotarao]

型エラーメッセージが意図通りでてなさそうな気がする

src/index.test.ts:139:21 - error TS2554: Expected 1 arguments, but got 0.

139     defineTypedHref.routes();
                        ~~~~~~

  src/index.ts:28:5
    28     ...args: RequireExplicitRoutesArgs<Routes>
           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Arguments for the rest parameter 'args' were not provided.

[akameco]

ご指摘ありがとうございます！

当初 ...args: だったため tsc が args という generic 名しか出力せず、せっかくの説明が埋もれていました。rest パラメータ名自体を説明的にする形で解消しています。

routes: <Routes, RouteParamsMap>(
  ...typeArguments: RequireExplicitRoutesArgs<Routes>
) => ...

実際の tsc --pretty 出力:

check.ts:4:17 - error TS2554: Expected 1 arguments, but got 0.

4 defineTypedHref.routes();
                  ~~~~~~

  src/index.ts:63:5
    63     ...typeArguments: RequireExplicitRoutesArgs<Routes>
           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Arguments for the rest parameter 'typeArguments' were not provided.

詳細な指示メッセージ ("routes<Routes, RouteParamsMap>() requires explicit type arguments") は型リテラルとして残し、IDE hover で参照できる形にしています。

将来の degrade 防止に、TS Compiler API でコンパイルしてエラーテキストを assert するテストも追加しました (src/routes-error-message.test.ts)。こちらは不要であれば削除してもいいかなと思います。