About

A document is a tree before it is text

Last updated 21 November 2026

GraphQL looks like JSON with the values left out. It is not: it is a small language with a grammar, and every reader on this page starts by turning your text into a tree of that grammar.

Three passes, no library

The first pass is the lexer. It walks the text one character at a time and cuts it into tokens: names, numbers, strings, block strings, punctuators and comments. It drops the two things GraphQL ignores, commas and whitespace, which is why the same query typed on one line and typed across twenty lines formats to the same bytes. An unterminated string, a bad escape or a number with a leading zero is rejected here, with the line and the column of the character that broke it.

The second pass is the parser: a recursive descent over those tokens that builds a document, definitions, operations, selection sets, arguments, values and, in the schema case, types. It does not know what a field means, only how it is written, which is the point. The third pass is a printer that walks the tree in order and writes it back out, four ways.

Two readers over one tree

The TypeScript writer and the mock writer both need the schema, and the schema is read with the same parser, in its definition language. From it they build a small map: type name to kind, field to type, enum to values, interface to the objects that implement it. The TypeScript writer prints that map as interfaces. The mock writer walks the query against it, choosing a value for each leaf and a shape for each selection set.

What depth and cost count

Depth is a property of the document alone: one level for a root field, one more for every selection set inside it. Cost counts fields, and here a list with a first, last or limit argument multiplies everything beneath it by that number, capped at ten so one careless first: 1000 does not drown the number. Neither is a rule. A limit is a conversation with the server team, and this page only puts a number in front of you before that conversation.

Where the checker stops

It can compare a document with a schema: a field that does not exist, a selection set on a scalar, an object field with no selection set, a variable used and never declared, a fragment spread with no definition. It cannot run a resolver, so it cannot tell you that user(id: "nobody") returns null, and it will not pretend a mock is a test result. The mock is a shape that matches the types, which is what a form field or a loading skeleton needs.

What it leaves to you

Who made it

Pikkola Lab builds small tools that keep the work in the browser. This is tool No. 54. Write to hello@pikkola.com with a document that formats badly, and say which part of the grammar it was.

Back to the studio

소개

문서는 글이기 전에 트리입니다

최종 수정 2026년 11월 21일

GraphQL은 값을 비워 둔 JSON처럼 보입니다. 하지만 문법이 있는 작은 언어이고, 이 페이지의 모든 리더는 글을 그 문법의 트리로 바꾸는 일에서 시작합니다.

라이브러리 없이 세 번

첫 번째는 어휘 분석입니다. 글자를 하나씩 넘기며 이름, 숫자, 문자열, 블록 문자열, 구두점, 주석이라는 토큰으로 자릅니다. GraphQL이 무시하는 쉼표와 공백은 여기서 버립니다. 한 줄로 친 쿼리와 스무 줄로 친 같은 쿼리가 같은 바이트로 정리되는 이유입니다. 닫히지 않은 문자열, 잘못된 이스케이프, 0으로 시작하는 숫자는 이 단계에서 거절하고, 문제가 된 글자의 행과 열을 함께 알려 줍니다.

두 번째는 파서입니다. 토큰 위를 재귀적으로 내려가며 문서와 정의, 오퍼레이션, 선택 집합, 인자, 값, 그리고 스키마라면 타입까지 세웁니다. 필드가 무엇을 뜻하는지는 모르고 어떻게 쓰였는지만 압니다. 그것이 핵심입니다. 세 번째는 트리를 순서대로 걸으며 네 가지 모습으로 다시 쓰는 인쇄기입니다.

한 트리 위의 두 리더

TypeScript 리더와 모의 응답 리더는 둘 다 스키마가 필요하고, 스키마는 같은 파서로 정의 언어를 읽어 얻습니다. 거기서 타입 이름과 종류, 필드와 타입, 열거형과 값, 인터페이스와 이를 구현한 객체의 지도를 만듭니다. TypeScript 리더는 그 지도를 인터페이스로 쓰고, 모의 응답 리더는 쿼리를 그 위로 걸으며 잎마다 값을, 선택 집합마다 모양을 고릅니다.

깊이와 비용이 세는 것

깊이는 문서만의 성질입니다. 루트 필드가 한 겹이고, 그 안의 선택 집합마다 한 겹씩 늘어납니다. 비용은 필드를 세되, first나 last, limit 인자가 붙은 목록은 그 아래를 그 수만큼 곱합니다. 열에서 멈추는 이유는 first: 1000 하나가 숫자를 통째로 삼키지 않게 하기 위해서입니다. 둘 다 규칙이 아닙니다. 한도는 서버 팀과 나눌 대화이고, 이 페이지는 그 대화 전에 숫자를 하나 내밀 뿐입니다.

검사기가 멈추는 곳

문서를 스키마와 견줄 수는 있습니다. 없는 필드, 스칼라 안의 선택 집합, 선택 집합이 없는 객체 필드, 선언하지 않은 변수, 정의 없는 프래그먼트를 찾습니다. 리졸버를 실행할 수는 없으니 user(id: "nobody")가 null을 돌려준다는 것까지는 모르고, 모의 응답을 시험 결과인 척하지도 않습니다. 모의 응답은 타입에 맞는 모양이고, 폼 필드나 로딩 뼈대가 필요로 하는 것이 바로 그 모양입니다.

남겨 두는 일

만든 곳

피콜라 랩은 일을 브라우저 안에 두는 작은 도구를 만듭니다. 이것은 54호기입니다. 정리가 이상하게 되는 문서와 함께 문법의 어느 부분이었는지를 hello@pikkola.com으로 보내 주세요.

스튜디오로 돌아가기

概要

文書は、文字である前に木です

最終更新 2026年11月21日

GraphQL は値を抜いた JSON に見えます。そうではなく、文法のある小さな言語です。このページのどの読み手も、あなたの文字をその文法の木に変えるところから始めます。

ライブラリなしで三度

一つ目は字句解析です。文字を一つずつ進み、名前、数値、文字列、ブロック文字列、区切り記号、コメントというトークンに切ります。GraphQL が無視するカンマと空白はここで捨てます。一行で打ったクエリと二十行で打った同じクエリが同じバイトに整う理由です。閉じない文字列、誤ったエスケープ、先頭が 0 の数値はこの段階で断り、壊れた文字の行と列を一緒に伝えます。

二つ目はパーサです。トークンの上を再帰的に降りて、文書、定義、オペレーション、選択セット、引数、値、スキーマなら型まで組み立てます。フィールドが何を意味するかは知らず、どう書かれたかだけを知ります。それが要点です。三つ目は木を順に歩いて四つの姿で書き戻す出力です。

一つの木に二人の読み手

TypeScript の読み手とモックの読み手はどちらもスキーマを必要とし、スキーマは同じパーサで定義言語を読んで得ます。そこから型名と種類、フィールドと型、列挙型と値、インターフェースと実装するオブジェクトの地図を作ります。TypeScript の読み手はその地図をインターフェースとして書き、モックの読み手はクエリをその上で歩いて、葉ごとに値、選択セットごとに形を選びます。

深さとコストが数えるもの

深さは文書だけの性質です。ルートのフィールドが一重、その中の選択セットごとに一重増えます。コストはフィールドを数え、first や last、limit の引数が付いたリストはその下をその数だけ掛けます。十で止めるのは、first: 1000 一つが数字を丸ごと飲み込まないようにするためです。どちらも規則ではありません。上限はサーバー側のチームと交わす会話で、このページはその前に数字を一つ差し出すだけです。

検査が止まる場所

文書をスキーマと比べることはできます。無いフィールド、スカラーの中の選択セット、選択セットの無いオブジェクトのフィールド、宣言の無い変数、定義の無いフラグメントを見つけます。リゾルバを実行することはできないので、user(id: "nobody") が null を返すことまでは分からず、モックを試験結果のふりもしません。モックは型に合う形で、フォームの項目や読み込み中の骨組みが求めるのはその形です。

残していること

作ったところ

Pikkola Lab は仕事をブラウザの中に置く小さな道具を作っています。これは 54号機です。整形がおかしくなる文書と、文法のどの部分だったかを hello@pikkola.com まで送ってください。

スタジオに戻る