graph_weaver 0.7.0 → 0.7.1

data/docs/i18n.md

@@ -1,104 +1,32 @@
 # Translating input errors
 
-The keys and the data an app translates "that input was wrong" from, without
-reading English sentences. See [errors](errors.md) for `InputError` itself and
-for what a server has to send.
+graph_weaver hands your app **a stable key and the facts**, and lets the app own
+the sentence. `kind` — a Symbol from a short closed vocabulary — and the key
+derived from it, `graph_weaver.input.<kind>`, are API: they change only with a
+MAJOR bump, and a new one arrives only as an addition. `#message` is the
+developer's line, in English, and it will be reworded. See
+[errors](errors.md) for `InputError` itself and for what a server has to send.
 
-## The one idea
-
-A library that hands you a sentence has already decided what your user reads, in
-one language, in its own voice. So graph_weaver should hand you **a stable key
-and the facts**, and let the app own the sentence:
-
-- **stable** — a `kind` from a short closed vocabulary, and the key derived from
-  it, `graph_weaver.input.<kind>`. These are API: they change only with a MAJOR
-  bump, and a new one arrives only as an addition.
-- **data** — the field, the value, the enum's members, the bounds. Never baked
-  into the message only, and never pre-formatted (`members` is an Array, not
-  "CAT or DOG" — joining it is a language decision).
-- **not stable** — `#message`. It is the developer's line, in English, and it
-  will be reworded.
-
-## The vocabulary
-
-Eight kinds, each one sentence. A ninth arrives only when a real input failure
-fits none of them — `:refused` is the honest home for everything else.
-
-The last four columns are **who can say it**, which is the other half of the
-story — a `kind` is worth only as much as the producer that can state it. The
-last of them is any server at all, through the
-[convention](#what-the-server-has-to-do).
-
-| `kind` | means | `details` carries | client | graphql-ruby | Hasura | convention |
-|---|---|---|---|---|---|---|
-| `:type_mismatch` | the value is not the type the schema declares, and no conversion applies | `type` | yes | yes | **no** | yes |
-| `:unparseable` | the right kind of thing, but the text doesn't parse as that scalar | `type` | yes | yes | **no** | yes |
-| `:not_a_member` | not one of the values an enum (or an inclusion rule) allows | `members` | yes | yes | yes | yes |
-| `:missing` | a required field or argument wasn't supplied, or was null | — | yes | yes | yes | yes |
-| `:unknown` | a key the input type doesn't define — a typo | `suggestion` | yes | yes | yes | yes |
-| `:out_of_range` | a number, length or date outside the bounds the schema states | `min`, `max` | **no** | **no** | **no** | yes |
-| `:invalid_format` | parses, right type, but fails a stated semantic rule — a regex, an email | `pattern` | **no** | **no** | **no** | yes |
-| `:refused` | rejected, with nothing more than a message — the fallback, never a guess | — | yes | yes | yes | yes |
-
-Those are the servers graph_weaver reads by name. **Apollo** is `:refused` and
-the server's own sentence, nothing finer — `BAD_USER_INPUT` says the input was
-bad and not what about it. **Anything else** says nothing graph_weaver will
-claim: `#input_errors` comes back `[]`, and the rejection stays an ordinary
-error to render as the server wrote it. Hasura's two extra blanks are one
-sentence doing two jobs: the same "expected a non-negative 32-bit integer" answers
-`limit: -5` and `limit: "lots"`, so both arrive `:refused` on the right field
-rather than one of them arriving confidently wrong. Which shape each server is
-read off is in [errors](errors.md#when-the-server-rejects-the-input).
-
-`field` and `value` ride on every kind. `value` is the offending value passed
-through [`filter_parameters`](logging.md#filtered-variables), so it reads
-`"[FILTERED]"` under a sensitive key and `nil` when the producer never said what
-the value was.
+## Translating it
 
-Two rows carry the headline: **`:out_of_range` and `:invalid_format` — the
-customer's "right type but out of range" and "bad semantic format" — cannot be
-produced from either side without the
-[server convention](errors.md#what-your-server-can-send).** The client doesn't
-know the schema's bounds, and a graphql-ruby `validates:` failure reaches the
-wire as a bare sentence with no `extensions` at all.
-
-`@oneOf` violations map to `:refused`, with one exception that isn't really
-one: exactly one field, explicitly null, is `:missing` on that field — the
-count is right and the value isn't, which is the same thing `:missing` means
-everywhere else, and it gives a form the one slot to highlight. The wrong
-*count* has no single field to name, so it stays a message ("supply exactly one
-field, non-null, got a, b"); one rule in twenty schemas doesn't earn a ninth
-kind.
-
-## The shape
-
-One class, carried by both halves. `GraphWeaver::InputError` is *raised* before
-the request leaves — rescuing it is a control-flow decision (render a 422) — and
-it is also the **value** a server's rejection becomes, which has precedent:
-`Response#errors` already holds unraised `GraphQLError`s. One class, zero new
-nouns, one renderer for both halves.
+No locale file ships — the strings are app-voice, not library-voice, and owning
+a user-visible English string would make every reword a breaking change. Paste
+this into your own `config/locales/en.yml`:
 
-```ruby
-GraphWeaver::InputError              # kind, path, coordinate, value, details, field, struct
-GraphWeaver::GraphQLError#input_errors    # [] when the error isn't about input
-GraphWeaver::Response#input_errors        # and QueryError#input_errors
+```yaml
+en:
+  graph_weaver:
+    input:
+      type_mismatch: "%{field} must be a %{type}."
+      unparseable: "%{field} isn't a valid %{type}."
+      not_a_member: "%{field} must be one of: %{members}."
+      missing: "%{field} is required."
+      unknown: "%{field} isn't a field we recognize."
+      out_of_range: "%{field} is out of range."
+      invalid_format: "%{field} isn't in the right format."
+      refused: "%{field} was rejected."
 ```
 
-Plural on all three: one variable-coercion error routinely carries several
-problems about different fields, and keeping only the first would lose the rest
-silently.
-
-- `path` — rooted at the **variable**: `["where", "_and", 0, "_not", "species"]`,
-  so `$where._and.0._not.species`. Every named segment is the **schema's**
-  spelling (`issuedOn`, not the `issued_on` you type in Ruby), whichever side
-  refused — [why](errors.md#which-spelling-a-path-is-in). `[]` when the
-  producer named no slot; `#field` is its last named segment.
-- `coordinate` — the GraphQL [schema coordinate](https://github.com/graphql/graphql-spec/pull/794):
-  `"PetFilter.species"`. `nil` when unknown — a variable names no schema
-  element, and a graphql-ruby coercion error rarely names the nested input type.
-
-## Translating it
-
 ```ruby
 def render_input_error(error)
   I18n.t(
@@ -111,6 +39,9 @@ def render_input_error(error)
 end
 ```
 
+One call serves both halves — a refusal raised before the request left, and one
+the server sent back:
+
 ```ruby
 # before the wire
 rescue GraphWeaver::InputError => e
@@ -120,97 +51,108 @@ rescue GraphWeaver::InputError => e
 response.input_errors.each { |e| form.errors.add(e.field&.underscore || :base, render_input_error(e)) }
 ```
 
-`#field` is the schema's spelling on both sides, so one `underscore` is the
-whole mapping to a Rails form field — and the two calls above really are the
-same call. **Plan for `nil`**: nothing named a slot, which is exactly what a
-server that states no input path gives you, and that is the default until your
+`#field` is the schema's spelling on both sides, so one `underscore` is the whole
+mapping to a Rails form field. **Plan for `nil`** — nothing named a slot, which
+is what a server that states no input path gives you, and the default until your
 server adopts [the convention](errors.md#what-your-server-can-send).
 
-**`field:` can't say which row.** A list index lives in `#path` and nowhere
-else, so every element of `lines: [LineInput!]!` translates to the same
-sentence. Where a form lists rows, label it from the path:
+`default:` is load-bearing: `:refused` is untranslatable by definition, so every
+app needs the fallback — and having it means you can translate the four kinds you
+care about and leave the rest.
 
-```ruby
-# "input.lines.0.qty", where #field alone is "qty" for every line at once
-I18n.t("graph_weaver.input.#{error.kind}", field: error.path.join("."), **error.details)
-```
+## The vocabulary
 
-`default:` is the load-bearing half: `:refused` is untranslatable by definition —
-it *is* whatever the message said — so every app needs the fallback, and having
-it means an app can translate the four kinds it cares about and leave the rest.
+Eight kinds; a ninth arrives only when a real input failure fits none of them.
+The last four columns are **who can say it**, which is the other half of the
+story — a `kind` is worth only as much as the producer that can state it, and the
+last of them is any server at all, through the
+[convention](#what-the-server-has-to-do).
 
-Arrays stay arrays: `details[:members]` is `["CAT", "DOG"]`, so join it where you
-know the language — `members: e.details[:members].to_sentence`.
+| `kind` | means | `details` carries | client | graphql-ruby | Hasura | convention |
+|---|---|---|---|---|---|---|
+| `:type_mismatch` | the value is not the type the schema declares, and no conversion applies | `type` | yes | yes | **no** | yes |
+| `:unparseable` | the right kind of thing, but the text doesn't parse as that scalar | `type` | yes | yes | **no** | yes |
+| `:not_a_member` | not one of the values an enum (or an inclusion rule) allows | `members` | yes | yes | yes | yes |
+| `:missing` | a required field or argument wasn't supplied, or was null | — | yes | yes | yes | yes |
+| `:unknown` | a key the input type doesn't define — a typo | `suggestion` | yes | yes | yes | yes |
+| `:out_of_range` | a number, length or date outside the bounds the schema states | `min`, `max` | **no** | **no** | **no** | yes |
+| `:invalid_format` | parses, right type, but fails a stated semantic rule — a regex, an email | `pattern` | **no** | **no** | **no** | yes |
+| `:refused` | rejected, with nothing more than a message — the fallback, never a guess | — | yes | yes | yes | yes |
 
-`details[:type]` is the **GraphQL** name for the type — `Int`, `Money` — so a
-sentence translated from it still says "Int" in the middle of the French. Name
-the scalars your forms use, and translate the name before it is interpolated:
-`render_input_error` splats `details`, so a `type:` passed after the splat wins.
+`field` and `value` ride on every kind. `value` is the offending value passed
+through [`filter_parameters`](logging.md#filtered-variables), so it reads
+`"[FILTERED]"` under a sensitive key and `nil` when the producer never said what
+the value was.
 
-```yaml
-fr:
-  types:
-    Int: "numérique"
-    String: "textuelle"
-```
+Two rows carry the headline: **`:out_of_range` and `:invalid_format` — the
+everyday "right type, wrong value" — cannot be produced from either side without
+the [server convention](errors.md#what-your-server-can-send).** The client
+doesn't know the schema's bounds, and a graphql-ruby `validates:` failure reaches
+the wire as a bare sentence with no `extensions` at all.
+
+Those three are the servers graph_weaver reads by name. **Apollo** is `:refused`
+and the server's own sentence, nothing finer. **Anything else** says nothing
+graph_weaver will claim: `#input_errors` comes back `[]`, and the rejection stays
+an ordinary error to render as the server wrote it. Which shape each server is
+read off, and why Hasura's blanks are blank, is in
+[errors](errors.md#when-the-server-rejects-the-input).
+
+## Details
+
+One class carries both halves: `GraphWeaver::InputError` is *raised* before the
+request leaves, and it is also the **value** a server's rejection becomes — read
+back by `Response#input_errors`, `QueryError#input_errors` and
+`GraphQLError#input_errors`, all plural, since one variable-coercion error
+routinely carries problems about several fields. What it holds is the table in
+[errors](errors.md#what-an-inputerror-says-without-reading-english); the one
+thing a translator needs from it is that every named segment of `#path` — and so
+`#field` — is the **schema's** spelling, whichever side refused
+([why](errors.md#which-spelling-a-path-is-in)).
+
+**`field:` can't say which row.** A list index lives in `#path` and nowhere else,
+so every element of `lines: [LineInput!]!` translates to the same sentence. Where
+a form lists rows, label it from the path:
 
 ```ruby
-type = I18n.t("types.#{error.details[:type]}", default: error.details[:type])
+# "input.lines.0.qty", where #field alone is "qty" for every line at once
+I18n.t("graph_weaver.input.#{error.kind}", field: error.path.join("."), **error.details)
 ```
 
-## No locale file ships
-
-graph_weaver ships the **keys and the data, and no `en.yml`**. Three
-reasons, in order:
-
-1. The strings are app-voice, not library-voice. "Species must be one of: cat,
-   dog" belongs to whoever owns the form.
-2. A shipped default applies by merely adding the gem — behavior that follows
-   from the Gemfile rather than from the code in front of you, which is the one
-   thing this library refuses to do everywhere else.
-3. Owning a user-visible English string means every reword is a breaking change
-   for apps that translated around it.
+Arrays stay arrays: `details[:members]` is `["CAT", "DOG"]`, so join it where you
+know the language — `members: e.details[:members].to_sentence`.
 
-Paste this into your own `config/locales/en.yml` instead:
+`details[:type]` is the **GraphQL** name for the type — `Int`, `Money` — so a
+sentence built from it still says "Int" in the middle of the French. Translate
+the name yourself under a key of your own and pass it *after* the splat, which
+wins: `I18n.t(key, **e.details, type: I18n.t("types.#{e.details[:type]}"))`.
 
-```yaml
-en:
-  graph_weaver:
-    input:
-      type_mismatch: "%{field} must be a %{type}."
-      unparseable: "%{field} isn't a valid %{type}."
-      not_a_member: "%{field} must be one of: %{members}."
-      missing: "%{field} is required."
-      unknown: "%{field} isn't a field we recognize."
-      out_of_range: "%{field} is out of range."
-      invalid_format: "%{field} isn't in the right format."
-      refused: "%{field} was rejected."
-```
+`@oneOf` violations are `:refused`, except exactly one field explicitly null,
+which is `:missing` on that field — a form gets the one slot to highlight. The
+wrong *count* names no single field, so it stays a message.
 
-## What the server has to do
+### What the server has to do
 
-For the two kinds nothing can produce on its own, and for every column the
-table leaves blank, the server states it — under one key, `extensions.input`, with
-the `kind` taken from the table above. The shape, the graphql-ruby recipes for
-it, and what a server that sends none of it gets instead are in
+For the two kinds nothing can produce on its own, and for every column the table
+leaves blank, the server states it — under one key, `extensions.input`, with the
+`kind` taken from the table above. The shape, the graphql-ruby recipes for it,
+and what a server that sends none of it gets instead are in
 [errors](errors.md#what-your-server-can-send).
 
 Two rules matter to a translator. **A `kind` outside the table becomes
-`:refused`** rather than being passed through, because a wrong key is worse
-than no key: the app will have translated it into a confident sentence. And
-**a key outside `type`/`members`/`min`/`max`/`pattern`/`suggestion` is dropped**
-before it reaches `details`, so `I18n.t(..., **details)` can never be handed an
-interpolation your locale file has no slot for. None of the six is a name in
-`I18n::RESERVED_KEYS` either — `:pattern` rather than `:format` for that reason,
-since splatting a `:format` key into `I18n.t` raises
-`I18n::ReservedInterpolationKey` instead of translating.
-
-## Transport and server failures
-
-`kind` exists for input errors and nothing else. The failures beside them — the
-endpoint was unreachable, the server answered 502, the server answered 200 and
-complained — name no field and carry nothing to interpolate. Key those on the
-**exception class**:
+`:refused`** rather than being passed through, because a wrong key is worse than
+no key: the app will have translated it into a confident sentence. And **a key
+outside `type`/`members`/`min`/`max`/`pattern`/`suggestion` is dropped** before it
+reaches `details`, so `I18n.t(..., **details)` can never be handed an
+interpolation your locale file has no slot for — nor one I18n reserves, which is
+why it is `:pattern` and not `:format`.
+
+### Transport and server failures
+
+`kind` exists for input errors and nothing else. The failures beside them name no
+field and carry nothing to interpolate, so key those on the **exception class**,
+which is the only closed vocabulary on that side — a `code` is a per-server
+invention, so a translation keyed on one degrades to English against the next
+server:
 
 | what you rescued | what the user is told |
 |---|---|
@@ -219,16 +161,11 @@ complained — name no field and carry nothing to interpolate. Key those on the
 | `GraphWeaver::QueryError` whose `#input_errors` is empty | something went wrong with that request |
 
 One static translated sentence each, and log what the server said rather than
-showing it. The [class hierarchy](errors.md) is the only closed vocabulary on
-this side: a `code` is a per-server invention — Apollo sends `BAD_USER_INPUT`,
-graphql-js sends none — so a translation keyed on one degrades to English
-against the next server, and `#message` is the developer's line, which moves.
+showing it.
 
-## Where translation stops
+### Where translation stops
 
 graph_weaver's own refusals are for developers and stay English, with no keys:
-`QueryValidationError` and the codegen errors (a rake task's output), the schema-drift
-hint, `ConfigurationError`, `Testing::*`. Same for `InputError#message` — it is
-the line in the log and the stack trace; the translated line is the one your app
-builds from `kind` and `details`. And a message the *server* wrote arrives in
-whatever language the server chose, passed through untouched.
+`QueryValidationError`, the codegen errors, the schema-drift hint,
+`ConfigurationError`, `Testing::*`, and `InputError#message`. A message the
+*server* wrote arrives in whatever language the server chose, untouched.