型安全に URL を構築できる
ライブラリ routopia を作った話

自己紹介

目次

1. 開発の背景
2. routopia とは
3. 実現方法
4. まとめ

URL 構築における課題

• typo、手打ちミス
• パラメータの渡し忘れ、型の不一致
• 更新漏れ、実装との乖離
• エンコード漏れ

既存のアプローチ

身の上話

内製ライブラリの利用イメージ

export const api = {
  /** エンドポイントの説明 */
  ...createApiRoute("/path/[slug]")<{
    /** エンドポイント+メソッドの説明 */
    GET: {
      segments: {
        /** パスパラメータ slug の説明 */
        slug: string;
      };
      queries: {
        /** クエリパラメータ q の説明 */
        q: boolean;
      }
    };
  }>(),
} as const;

import { api } from "./path/to/api";

api["/path/[slug]"].get({
  segments: { slug: "to" },
  queries: { q: "test" }
});
// => https://api.example.com/path/to?q=test

api["/path/[slug]"].get();
//                  ^^^^^
// segment.slug が足りないよエラー

内製ライブラリ

要件

• 型安全に URL を構築したい
• ベースの使い心地はそのままがいい
• JSDocがエディタに認識されてほしい
• コードジャンプできるようにしたい
• 定義時にある程度補完が効いてほしい

定義したスキーマに従って
型安全に URL を構築できるビルダー

基本的な使い方

import { routes, type, empty } from 'routopia';

export const api = routes({
  "/path": {
    // No parameters
    get: empty,
  },
  "/path/[id]": {
    get: {
      params: {
        id: type as number,
      },
      queries: {
        // Queries can be optional
        q: type as string | undefined,
      },
    },
  },
});

import { api } from "./path/to/api";

api["/path"].get();
// => "/path"

api["/path/[id]"].get({ 
  params: { id: 123 }, 
  queries: { q: "query" },
});
// => "/path/123?q=query"

api["/path/[id]"].get({ 
  params: { id: 123 },
});
// => "/path/123"

api["/path/[id]"].get();
//                  ^^^^^
// params が足りないよエラー

特徴

Best Practice

import { routes, ExpectedSchema, empty, type } from 'routopia';

export function createMyApiRoutes<T extends ExpectedSchema<T>>(schema: T) {
  return routes("https://api.example.com", schema);
}

export const schema = { empty, type };

import { createMyApiRoutes, schema } from './path/to/createMyApiRoutes';

export const usersApiRoutes = createMyApiRoutes({
  "/users": {
    get: schema.empty,
  },
});

import { usersApiRoutes } from './path/to/usersApiRoutes';

usersApiRoutes["/users"].get();
// => "https://api.example.com/users"

ひたすら型パズル

すべてを解説している余裕はないので一部抜粋して紹介します

Case1: パスパラメータの抽出

• /path/[param] という文字列から param を抽出したい
• これを { param: string | number } としたい
• 可変長な [...param] や [[...param]] も考慮したい
• infer や Conditional Types(extends ? : ) を駆使して実現する

パスパラメータの抽出パズル

type ExtractParams<Endpoint extends string> =
  Endpoint extends `${infer Before}[[...${infer Param}]]${infer After}`
  ? { [K in Param]: (string | number)[] | undefined } & ExtractParams<Before> & ExtractParams<After>
  : Endpoint extends `${infer Before}[...${infer Param}]${infer After}`
    ? { [K in Param]: (string | number)[] } & ExtractParams<Before> & ExtractParams<After>
    : Endpoint extends `${string}[${infer Param}]${infer After}`
      ? { [K in Param]: string | number } & ExtractParams<After>
      : unknown;

ExtractParams<"/users/[userId]/posts/[postId]">
// => { userId: string | number, postId: string | number }

ExtractParams<"/path/[...params]">
// => { params: (string | number)[] }

パスパラメータの抽出結果

• パス文字列から期待するパラメータの型を抽出できた
• これを使って typo や 渡し忘れを検知できるようになる
• 同時に補完も効くようになる

Case2: 呼び出し時の引数の省略可否

• 呼び出し時の引数を必須じゃないなら省略可能にしたい
• 定義時に undefined を許容したプロパティを省略可能にしたい
• 再帰的な必須プロパティチェックとオプショナル化が必要

必須プロパティの存在チェック

type PickRequired<T> = {
  [P in keyof T as T[P] extends undefined ? never : P]: T[P];
};

type HasRequired<T> = (
  T extends unknown[]
    ? false
    : T extends object
      ? keyof PickRequired<T> extends never
        ? HasRequired<T[keyof T]>
        : true
      : false
) extends false ? false : true;

必須でないプロパティのオプショナル化

type PickNullable<T> = {
  [P in keyof T as T[P] extends undefined ? P : never]: T[P];
};

type Optional<T> = {
  [K in keyof PickNullable<T>]?: T[K];
} & {
  [K in keyof PickRequired<T>]: T[K];
};

組み合わせていった結果

• undefined を許容するプロパティだけか再帰的に判別
• 当てはまるオブジェクトに ? を付与できた
• つまり必須パラメータがなければ引数から省略可能になった
• これにより呼び出し時に余計な引数を省略できるようになった

難解な型パズルはメンテナンス性が悪いので
マジでおすすめはしませんが
小手先のテクニックは役立つかもしれません

手っ取り早くテクニックを学ぶ・調べるなら
type-challenges が参考になるかも

まとめ

見返す用

EOF