GraphQL フォーマッター

実例

整形前

query GetUser($id:ID!,$withPosts:Boolean!){user(id:$id){id name email posts @include(if:$withPosts){...PostSummary}}} fragment PostSummary on Post{id title publishedAt}

整形後

query GetUser($id: ID!, $withPosts: Boolean!) {
  user(id: $id) {
    id
    name
    email
    posts @include(if: $withPosts) {
      ...PostSummary
    }
  }
}

fragment PostSummary on Post {
  id
  title
  publishedAt
}

SDL スキーマ

type Post {
  id: ID!
  title: String!
  publishedAt: DateTime
  author: User!
}

type Query {
  post(id: ID!): Post
  posts(authorId: ID, limit: Int = 20): [Post!]!
}

なぜ GraphQL を整形するのか

一貫した GraphQL の整形は、コードレビュー、スキーマ diff、.graphql ファイルの保管に直結します。永続化クエリを使えない環境では minify によって通信量を減らせます。整形されたクエリは PR 上で読みやすく、クエリを単体で検証すると、閉じかっこの不足や閉じていない文字列といった構文エラーを送信前に見つけられます。存在しない fragment 名は構文エラーではないため、スキーマを使った検証が必要です。

内部の仕組み

本ツールはブラウザ内で graphql-js（GraphQL Foundation 管理の公式リファレンス実装）を動かします。parse() がテキストから AST を構築し、最初の構文エラーを行・列で報告。print() が AST を規範的な GraphQL に再シリアライズ。stripIgnoredCharacters() が spec で ignored とされるトークンをすべて除去して圧縮版を返します。ネットワーク往復ゼロ、データは端末内に留まります。

圧縮とエラーの例

上の「整形前」のクエリで圧縮を押すと、次のようになります（graphql-js 16.14 の stripIgnoredCharacters）。

query GetUser($id:ID!$withPosts:Boolean!){user(id:$id){id name email posts@include(if:$withPosts){...PostSummary}}}fragment PostSummary on Post{id title publishedAt}

GraphQL ではカンマは無視されるトークンなので、空白と一緒に削除されます。閉じ波かっこが 1 つ足りない query { user(id: 1) { id name } は 解析エラー: Syntax Error: Expected Name, found <EOF>. (行 1, 列 32) と表示され、パーサーが入力の終わりに達した位置を指します。

エイリアス、変数、コメント

このクエリは異なるエイリアスで 2 人のユーザーを取得します。4 スペースを選んで整形すると、入れ子の選択が行ごとに分かれます。出力には primary、secondary、引用符内の ID、変数のデフォルト値、@include ディレクティブが残ります。先頭のコメントは消えるため、必要な説明がある場合は元のクエリを保存してください。圧縮は同じ操作と選択を保持し、コメントとパーサーが省略を許すトークン間の空白を削除します。

入力

# Fetch two labels
query Labels($show: Boolean! = true) { primary: user(id: "a") { name } secondary: user(id: "b") @include(if: $show) { name } }

4 スペースの出力

query Labels($show: Boolean! = true) {
    primary: user(id: "a") {
        name
    }
    secondary: user(id: "b") @include(if: $show) {
        name
    }
}

圧縮した出力

query Labels($show:Boolean!=true){primary:user(id:"a"){name}secondary:user(id:"b")@include(if:$show){name}}

説明文の相対的なインデントを保持する

説明文自体にインデントを含めることができます。この SDL の例では、注記は前の文より 2 スペース深く始まります。4 スペースで整形すると、フィールドと説明の区切りは広い構造インデントに移ります。注記は引き続き前の文より 2 スペース深くなります。整形した結果を解析すると、改行と注記の前の 2 スペースを含め、入力と同じ説明文が得られます。

入力

type Query {
  """
  Returns a label.
    Keep this note indented.
  """
  label: String
}

4 スペースの出力

type Query {
    """
    Returns a label.
      Keep this note indented.
    """
    label: String
}

制限

• 整形するとコメントが消えます。graphql-js の print() は構文木から文字列を作り直し、# コメントは構文木に含まれません。圧縮でもコメントは削除されます。コメントが必要なら元のファイルを残してください。
• 検証は構文だけです。{ user(id: $id) { id } } は $id が宣言されていなくても通ります。変数やフィールドの確認にはスキーマが必要です。
• 報告される構文エラーは最初の 1 件だけです。
• 4 スペースのオプションが広げるのは入れ子によるインデントだけです。""" のブロック文字列は開始行が新しいインデントに移り、中の文字はそこからの相対的なインデントを保ちます。GraphQL の仕様はブロック文字列の共通インデントだけを取り除くため、中の行まで広げると説明文が変わってしまうからです。graphql-js の出力は 2 スペースで、他のツールも 2 スペースになります。
• 入力の上限は 10,485,760 文字です。