graph_weaver 0.6.1 → 0.7.0

data/docs/generated_modules.md

@@ -49,11 +49,21 @@ GraphWeaver.generate!(schema:)            # write the modules
 GraphWeaver.verify_generated!(schema:)    # the freshness guard, one line in a spec
 ```
 
+**`verify_generated!` costs what `generate!` costs**, minus the writes — it
+recomputes the whole plan, every file's content, and diffs each against disk,
+whether nothing is stale or everything is. It doesn't get cheaper because only
+one query changed, so it belongs in *one* example per suite run, not in a
+`before` or an assertion per example, where it reads like a cheap check and
+isn't.
+
 `generate!` returns every file the plan produces, but rewrites only the ones
 whose bytes changed; `GraphWeaver.changed_files` is that subset. So
 `rake graph_weaver:generate` prints `wrote` for what moved and `N already up to
 date` for the rest, and a watching dev server has one module to reload instead
-of all of them.
+of all of them. The unregistered-scalar report is the rake task's `puts`, not
+`generate!`'s, so off rake read `GraphWeaver.untyped_scalars` for the unioned
+list — or set [`GraphWeaver.logger`](logging.md), which `generate!` names them
+on at `info` as it goes.
 
 The schema dump is step 0 — codegen reads it, never a live endpoint.
 `cache: true` on a url client writes it on first introspection
@@ -89,6 +99,21 @@ explicit, factory_bot-style:
 GraphWeaver.load_generated!   # require every file under generated_paths
 ```
 
+**Outside Rails, four things have to agree**, and nothing wires them together
+for you — a script that generates its own modules sets all four:
+
+1. `queries_paths` — where `generate!` reads `.graphql` files.
+2. `generated_paths` — where it writes, and where `load_generated!` reads.
+   Point them at the same directory or generation is invisible.
+3. the call above, before the first `execute` — nothing else requires the
+   files.
+4. `GraphWeaver.client =` — a module generated without a baked
+   [`client:`](#clients) has none of its own.
+
+Miss (3) and the script gets a `NameError` for its own module; miss (4) and it
+gets `PersonQuery: client must respond to #execute(query, variables:), got
+NilClass` from a module that otherwise looks fine.
+
 Every directory setting is a list — `queries_paths`, `generated_paths`,
 `fragments_paths` — and every entry is read (entries may be globs; the
 generated default includes `app/graphql/*/generated`, so per-schema layouts
@@ -168,6 +193,58 @@ end
   **result**, or a raised `GraphWeaver::QueryError`. See [errors](errors.md).
 - `from_response` / `from_response!` are the **network-free half** of the
   pair — same envelope, but from a response hash you already have (below).
+- A `Result` is an **ordinary Ruby object**: value `==` (with `eql?` and
+  `hash`, so a result works as a hash key), `deconstruct_keys` for pattern
+  matching, `#to_h`, and `#to_json`/`#as_json`. All of them go the whole way
+  down a nested result.
+  Immutable as far as its props go, like `Struct` or `Data` — and no further:
+  the `String` or `Hash` a leaf holds is the one the response carried, so
+  `result.name << "!"` changes the result, and its `hash` with it.
+
+  **Cache a result with `Marshal`, not YAML.** A `T::Enum` member is a
+  singleton that sorbet compares by identity, and Psych allocates an object
+  before filling it in, so YAML has no way to hand back the canonical one:
+  after a round trip `pet.species == Species::Dog` is false and the result no
+  longer equals itself. `Marshal` restores it intact — as does JSON, since
+  `#to_json` writes the wire shape and `from_h` reads it back (below).
+
+  ```ruby
+  PersonQuery.from_response!(raw) == PersonQuery.from_response!(raw)  # true — value, not identity
+
+  case PersonQuery.execute!(id: "1")
+  in { person: { name:, pets: [{ name: first_pet }, *] } } then "#{name} and #{first_pet}"
+  in { person: { name: } } then "#{name}, petless"
+  in { person: nil } then "nobody"
+  end
+
+  PersonQuery.execute!(id: "1").to_h
+  # => { person: { id: "1", name: "Daniel", birthday: #<Date 1984-05-06>,
+  #                pets: [{ name: "Nibbler" }] } }
+  ```
+
+  `#to_h` is the **Ruby** shape, not the wire's: snake_case prop names as
+  Symbols, nils kept, enums as their `T::Enum` members, and a registered
+  scalar as whatever object its codec built. It is a view, for Ruby to read.
+
+  `#to_json` — and `#as_json`, which `render json:` goes through — is the
+  **wire** shape instead: the response keys, and every leaf back through its
+  scalar registration's `serialize:`. So a result's JSON is the inverse of
+  `from_h`:
+
+  ```ruby
+  PersonQuery::Result.from_h(JSON.parse(result.to_json)) == result  # true
+  ```
+
+  which is what a cache entry, a log line or a JSON API response wants. That
+  split is deliberate: a Symbol-keyed Ruby hash can't be mistaken for a
+  server's response, and a JSON string can — so the JSON is the one that has
+  to be true. (An **input** struct's `to_h` is already the wire hash it
+  sends, so there its JSON and its `to_h` agree.) The trip is exactly as
+  faithful as each scalar's own `cast:`/`serialize:` pair: a `Time` goes back
+  out with [the microseconds its registration writes](scalars.md#going-out--what-a-variable-kwarg-accepts),
+  and a `register_scalar` with a `cast:` and no `serialize:` has no wire
+  spelling at all, so its value reaches the encoder as it is — the same
+  reason an input can't send one.
 - `OPERATION_NAME` rides along on every request as the spec's
   `operationName`, so Apollo Studio, Hasura and your APM key traces, rate
   limits and slow-query reports on the operation instead of lumping every
@@ -196,6 +273,12 @@ file holding two operations, since one file can't name two modules. Change a
 file's `query` to `mutation` and its constant changes with it; the next
 `generate!` prunes the old file, and `verify` fails until you regenerate.
 
+**A graph's `namespace:` nests what it generates**, and is the answer when two
+schemas in one app each have a `person.graphql`: `namespace: "Billing"` makes
+that one `Billing::PersonQuery` in the same `person_query.rb`, and its shared
+types module `Billing::GraphQLTypes`. Nothing else about the rule changes — the
+file still names the module. See [getting started](getting_started.md#more-than-one-schema).
+
 Parsing a raw query *string* has no file to name it after, so it uses the
 operation name (`query GetPerson` → `GetPerson`); dynamic `parse` falls back to
 `Query` for an anonymous one (its constants are container-scoped, so collisions
@@ -291,6 +374,14 @@ stands in its place for the arguments — stricter, and with a better message
 and the `Result` it returns is a `T::Struct`, so its props are still checked one
 by one.
 
+`T::Configuration.default_checked_level = :never` buys nothing back here. That
+knob governs `sig` dispatch, and the emitted sigs already opt out; the cost that
+remains is `T::Struct`'s own prop validation, which sorbet-runtime declares
+`.checked(:never)` in its own source and runs through a setter built at class
+definition. `from_h` allocates and costs the same either way — measured
+object-for-object identical — so reach for the scalar's cast, not this, when a
+deserialization path is hot.
+
 One kwarg per declared variable, always — so adding a variable to a query
 adds a kwarg and leaves every existing call site alone. Two names are refused at
 generation, `$client` and `$variables`: the generated `execute` body already
@@ -339,6 +430,40 @@ a shared type keeps one identity across modules. A query module aliases only its
 diffs exactly the types it touched, and types the schema drops are pruned on
 regeneration (`verify` flags strays). Dynamic `parse` stays self-contained.
 
+### An input object generates its whole closure
+
+A result type is generated per selection set, because a selection set *is* the
+question. An input object has no selection set, so the only static answer to
+"what can `$where` hold" is every input type it can transitively reach — and
+codegen emits a file for each. On a hand-written schema that closure is usually
+the one type and nothing else. On a generated one (Hasura, Gatsby), where every
+`_bool_exp` references every other, one `$where` reaches a thousand of them.
+
+The escape is to stop making the filter a variable. Write it as a literal in the
+query with a variable per leaf, and codegen has ordinary scalars to generate
+instead of the closure — on the query that emitted ~1,200 files, exactly one:
+
+```graphql
+query($name: String!, $minHeight: Int!) {
+  pokemon(where: { name: { _ilike: $name }, height: { _gte: $minHeight } }) {
+    name
+  }
+}
+```
+
+`srb tc` gets *more* out of that, not less. `name: String`, `min_height:
+Integer` are types it checks at every call site, where the variable form is
+`T.any(PokemonBoolExp, T::Hash[T.untyped, T.untyped])` — and a hash built from
+`params`, which is how a filter is really assembled, takes the untyped branch.
+Refusals land on the leaf too, so `path` is the form field rather than the
+comparison operator under it.
+
+Two shapes can't be inlined, and codegen says which when a prop collision in an
+input type forces the question. A key chosen at runtime — the sort column in
+`order_by: { <column>: asc }` — has no spelling, because GraphQL has no dynamic
+object keys. And a literal list can't stand in for a length only the runtime
+knows.
+
 ## Enums: one GraphQL enum, one Ruby type
 
 Every schema enum a query touches — as a variable, in a result, or both —
@@ -363,6 +488,28 @@ of yours instead.
 the enums into the query module itself; there's no cross-query set to share
 against, but one enum is still one class within that module.
 
+**The one misuse nothing catches** is comparing against the wire spelling:
+
+```ruby
+pet.species == "CAT"                    # => false, always, and silently
+pet.species == GraphQLTypes::Species::Cat
+```
+
+A generated enum is a plain `T::Enum`, so `==` against a String is `false` —
+`srb tc` allows it (`==` takes `BasicObject`) and nothing raises. sorbet-runtime
+owns this question and ships the switch; turn it on in dev and test and route
+the report wherever your other soft assertions go:
+
+```ruby
+T::Configuration.enable_legacy_t_enum_migration_mode
+T::Configuration.soft_assert_handler = ->(message, extra) { raise "#{message} #{extra}" }
+```
+
+It covers your own `T::Enum`s too, which is why it belongs there rather than in
+the generated classes. Careful reading it: in that mode the comparison answers
+**true** (it serializes first), so the handler, not the return value, is the
+signal.
+
 ## Selections
 
 - **Fragments** — inline fragments and named spreads flatten into the
@@ -380,6 +527,20 @@ mode) the struct raises a NoMethodError naming the prop that does exist —
 `use 'name_with_owner'` for the exact wire name, `did you mean ...?` for
 a near-miss typo in either casing.
 
+A name that would shadow a method every struct answers — `class`, `hash`,
+`display`, `to_json`, and `supplied` on an input — takes a trailing underscore
+instead: `class` → `class_`, in results and input types alike. The generated
+source says so on the line above the prop. Only the Ruby name moves: the wire
+keeps the schema's spelling in both directions, so the query, the request and
+the response are untouched, and `result.class` is still Ruby's `class`. The
+prop is the one Ruby name for the field, so `.new`, `.coerce`, a result's
+`#to_h` and pattern matching, and an `InputError`'s `#path` all use `class_`
+(an input error's `#coordinate` still names the schema's `Tricky.class`). The
+wire views are where the schema's spelling comes back: an **input** struct's
+`#to_h` is the hash you would send — `{"class" => …}` — and a result's
+`#as_json`/`#to_json` write `"class"` too, so `render json: result` never
+leaks a trailing underscore. Input structs don't pattern-match at all.
+
 ### Abstract types
 
 An abstract field emits **one struct per type condition the selection names**,
@@ -387,7 +548,10 @@ plus a catch-all `Other`, wrapped in a module with
 `Type = T.type_alias { T.any(...) }` and a `from_h` that dispatches on
 `__typename`. Generation therefore *requires* `__typename` in such a selection,
 unaliased and unconditional — the wire response carries no type tag unless you
-ask, and `from_h` reads it on every response.
+ask, and `from_h` reads it on every response. One `__typename` inside each
+`... on Type` does **not** substitute, however many of them there are: the
+dispatch runs before any member's selection applies, and a member the query
+never named would carry none at all.
 
 Size follows the query, not the schema: two `... on` conditions against GitHub's
 `Node` — an interface with a few hundred implementations — emit three structs,
@@ -473,9 +637,12 @@ pet.name           # => "Shelby" — the wire value stays honest
 
 The methods live on the struct, so they see its wire fields at runtime and
 fakes/cassettes get the behavior automatically; registrations are additive
-(repeated ones stack). Editing the *mixin* in development needs a restart,
-unlike a `.graphql` edit: a reload hands the constant a new module object, and
-the `include` that took the old one doesn't run again.
+(repeated ones stack). The mixin is one of your own constants, so in Rails the
+registration goes in a `to_prepare` block like `register_enum` does, and for the
+same reason — [getting started](getting_started.md#2-run-the-generator) has the
+rule and the boot order behind it. Editing the *mixin* in development needs a
+restart, unlike a `.graphql` edit: a reload hands the constant a new module
+object, and the `include` that took the old one doesn't run again.
 For quick decoration, build the mixin inline — the block
 is `module_eval`'d into a fresh module auto-named under
 `GraphWeaver::TypeHelpers`:
@@ -486,12 +653,41 @@ GraphWeaver.extend_type("Pet") do
 end
 ```
 
-**Neither form is statically checked**, for the same reason: `srb tc` checks a
-mixin's method bodies in the module's own scope, not the including struct's, so
-a helper reading a wire field (`name`, `birthday`) fails with "method does not
-exist on the module" — and the block form has no source on disk for `srb tc` to
-read at all. Write such a helper at `# typed: false`, or reach the field through
-`T.unsafe(self)`.
+The name is where the block is written and what it extends:
+`GraphWeaver::TypeHelpers::Pet` at the top level,
+`GraphWeaver::TypeHelpers::Billing::Pet` inside `GraphWeaver.graph :billing`.
+Generated code spells it, so it depends on your source and nothing else — two
+graphs can extend the same type name, and the name a `generate` bakes in is the
+one a boot creates.
+
+**Neither form is statically checked as written**, for the same reason: `srb tc`
+checks a mixin's method bodies in the module's own scope, not the including
+struct's, so a helper reading a wire field (`name`, `birthday`) fails with
+"method does not exist on the module" — and the block form has no source on disk
+for `srb tc` to read at all (it shows up as `Unable to resolve constant` on the
+generated `include`, which is the cost of the convenience).
+
+A *named* module can carry real sigs, though, by declaring the fields it leans
+on — abstract sigs are how a mixin says "whatever includes me has these", and the
+struct's `const`s satisfy them:
+
+```ruby
+# typed: strict
+module PetHelpers
+  extend T::Sig
+  extend T::Helpers
+  abstract!
+
+  sig { abstract.returns(String) }
+  def name; end
+
+  sig { returns(String) }
+  def display_name = "#{name} 🐶"
+end
+```
+
+`T.unsafe(self).name` also silences it, at the cost of checking nothing. Either
+beats `# typed: false` for a helper you want checked.
 
 ### Flat accessors with `alias:`
 
@@ -560,13 +756,23 @@ Resolution is per call (`client:`) → per module → baked constant →
 [transports](transports.md#client-resolution).
 
 Generate *without* a baked constant when you want modules to follow the
-app default (`GraphWeaver.client =` in an initializer) — that's also what
-lets [testing's `graphql:` tag](testing.md) swap in a client per example.
+app default (`GraphWeaver.client =` in an initializer).
+
+A baked constant is no longer a reason a module escapes
+[testing's `graphql:` tag](testing.md): the tag is exactly the instruction
+to replace the client generation chose, so it stands in for the baked one
+too. What the *example* says still wins — a per-call `client:`, or
+`MyQuery.client =` in a `before` block.
 
 `client`/`client=` live in the gem (`GraphWeaver::QueryModule`, extended by
 every generated module). A baked constant is emitted as a private
 `DEFAULT_CLIENT`, resolved on first use so a module can load before the
-initializer that builds its client.
+initializer that builds its client. A module generated from a
+[declared graph](getting_started.md#more-than-one-schema) also carries a private `GRAPH` naming
+it — so with two graphs, `graphql: :fake` fabricates each module's own
+schema instead of having to be told which one you meant, and it is the
+`:graph` on every [instrumentation event](logging.md#the-payload) the
+module's `execute` produces.
 
 ## Deserializing a response from another client
 
@@ -593,7 +799,7 @@ keys** (`"person"`, `"nameWithOwner"`), the top-level `"data"` / `"errors"` /
 
 Which is checked, since symbolizing is the likeliest thing to go wrong at this
 seam: a hash carrying neither `"data"` nor `"errors"` raises a
-`GraphWeaver::TypeError` naming the keys it *did* find, rather than handing back
+`GraphWeaver::CastError` naming the keys it *did* find, rather than handing back
 an envelope that reports success with no data. `nil` and a bare String are
 refused the same way.
 
@@ -606,6 +812,16 @@ checking matters. `GraphWeaver.run(source, query, **variables)` — or
 `client.run` — is the one-shot form: parse and execute in one call, no module
 kept.
 
+In an app with [more than one graph](getting_started.md#more-than-one-schema), a
+parsed module belongs to one of them — that is what a `graphql:` tag runs it
+against, the same thing generation bakes into a file. It is read off the schema
+you parsed against when a graph runs that class in-process; say it outright
+otherwise:
+
+```ruby
+PersonQuery = GraphWeaver.parse(schema: BILLING, query: "…", graph: :billing)
+```
+
 Generated source is eval'd, so inputs are validated: module names must be
 constant names, and query heredocs can't be terminated early. Still: queries
 are code — don't feed untrusted strings to parse.