kouno.log

    ↑↓ で移動 · Enter で開く

    forteeの非公式TypeScriptスキーマをJSRに公開した

    TypeScriptJSR

    forteeの非公式TypeScriptスキーマをJSRに公開した

    技術カンファレンス支援プラットフォーム「fortee」のAPI型定義を、非公式のTypeScriptスキーマとしてJSRに公開した。

    ##forteeとは

    forteeは技術カンファレンスの運営を支援するプラットフォームで、プロポーザル管理やタイムテーブル公開などの機能を提供している。APIも公開されているが、公式の型定義は存在しない。

    ##作ったもの

    fortee APIのレスポンスに対応するTypeScriptの型定義パッケージ。以下のスキーマを提供している。

    • common – スピーカー、フィードバックなど共通型
    • proposals – プロポーザル一覧
    • sponsors – スポンサー情報
    • staff – スタッフリスト
    • timetable – タイムテーブル
    • tracks – トラック情報

    ##3つの使い方

    用途に合わせて3パターンの利用方法を用意した。

    1. JSRからインストール（推奨）：Zodスキーマとしてバリデーション付きで利用
    2. ピュアTypeScript型定義をコピー：Zodに依存せず型だけ使いたい場合
    3. Zodスキーマを直接利用：バリデーションロジックが必要な場合

    ##技術的なポイント

    • Zodスキーマから型を生成: src/schemas/ にZodスキーマを定義し、zod-to-ts + ts-morph でピュアなTypeScript型定義を dist-types/ に出力する構成
    • マルチランタイム対応: Cloudflare Workers、Node.js、Deno、Bun、ブラウザで動作
    • JSRスコア100%: ドキュメント・型定義・互換性すべて満点

    ##開発を支えるスクリプト群

    スキーマの品質を担保するために、4つのスクリプトを用意した。

    ###fetch-sample – 実データの取得

    forteeのAPIからサンプルデータを取得するスクリプト。Cookie認証でアクセスし、proposals・timetable・sponsorsなど各エンドポイントのJSONを sample/<event-slug>/ に保存する。

    FORTEE_COOKIE='_session=abc123' tsx scripts/fetch-sample.ts kinoko-2026

    取得した実データは個人情報を含むため .gitignore に追加してある。

    ###mask – faker.jsによるデータマスキング

    サンプルデータの個人情報をダミーデータに置換するスクリプト。@faker-js/faker を使い、スピーカー名・Twitterアカウント・スポンサー情報などをマスキングして sample/masked/ に出力する。

    ポイントはUUIDからseedを決定的に生成している点。同じUUIDのスピーカーは何度マスキングしても同じダミー名になるため、差分を追いやすい。マスク後のデータに対してもZodスキーマでバリデーションを実行し、マスキングで型が壊れていないことを保証している。

    ###validate – Zodスキーマによるバリデーション

    サンプルデータがZodスキーマに適合するかを一括検証する。APIのレスポンス形式が変わったらここで検知できる。

    ###generate – ピュアTypeScript型定義の生成

    Zodスキーマから zod-to-ts を使ってピュアなTypeScript型定義ファイルを自動生成する。Zodに依存したくないユーザー向けの提供手段。

    ##CI/CD

    GitHub Actionsで2つのワークフローを運用している。

    • Validate & Generate Types: push/PRのたびにマスクデータのバリデーションと型生成を実行。dist-types/ が最新かどうかを git diff でチェックし、差分があればCIを落とす
    • Publish to JSR: v* タグのpushで npx jsr publish を実行し、JSRに自動パブリッシュ

    ← Memos一覧に戻る