graph_weaver 0.4.6 → 0.5.0

data/docs/scalars.md

@@ -9,10 +9,8 @@ Ruby object (and serializes back when used as a variable). A field typed
 GraphWeaver.register_scalar("Money", Money, requires: "bigdecimal")
 ```
 
-Registrations are global by default. A [client](transports.md) scopes
-them: `client.register_scalar(...)` overlays the global registry for that
-client's generation only — so two servers can disagree about what a
-`DateTime` is, and neither leaks into the other.
+Registration is global and codegen-time: `rake graph_weaver:generate` reads the
+same registry an initializer writes, so register before you generate.
 
 Pass a `Type.field` **coordinate** instead of a scalar name to override just
 that one field — so the same scalar can deserialize as different Ruby types
@@ -23,9 +21,9 @@ GraphWeaver.register_scalar("ISO8601DateTime", Time)   # the default, everywhere
 GraphWeaver.register_scalar("User.birthday", Date)     # this field only
 ```
 
-A field override wins over the scalar-name registration; both stack the same
-global-then-client way. (GraphQL names can't contain `.`, so the coordinate is
-unambiguous — and it's validated against the schema, so a typo'd field raises.)
+A field override wins over the scalar-name registration — which is also how two
+servers that disagree about a `DateTime` coexist in one process. Coordinates are
+validated against the schema, so a typo'd field raises.
 
 Pass a real class as `type:` and the cast/serialize are **inferred** from it by
 probing the deserialize side and pairing its serializer:
@@ -35,12 +33,9 @@ probing the deserialize side and pairing its serializer:
 | `.parse`          | `Type.parse(v)` | `v.to_s`     |
 | `.load`           | `Type.load(v)`  | `Type.dump(v)` |
 
-so the common case needs nothing more. Probing the *deserialize* side is
-deliberate — every object has `#to_s`, so inferring off it would wrongly wrap
-plain types like `String`/`Integer`; requiring a `.parse`/`.load` the type
-actually defines avoids that (and is why the built-in scalars — `Date`, `ID`,
-`Int`, and friends, pre-registered and detailed below — can be registered with
-their real class constants). Override explicitly when you need to:
+so the common case needs nothing more. A type defining neither `.parse` nor
+`.load` stays pass-through rather than getting wrapped. Override explicitly when
+you need to:
 
 - a `Symbol` method name, nothing to misspell: `cast: :load` → `Money.load(expr)`,
   `serialize: :to_json` → `expr.to_json`
@@ -54,7 +49,7 @@ a real class (so the runtime is loaded), each path is also `require`d at
 registration — a typo fails now, not in the generated file.
 
 Pass `coerce: true` to let a variable of this scalar accept **either** the value
-object **or** its raw input, normalizing the latter through the cast:
+object **or** its raw input, normalizing the latter before it goes on the wire:
 
 ```ruby
 GraphWeaver.register_scalar("Money", Money, coerce: true)
@@ -63,38 +58,42 @@ StoreQuery.execute(budget: "12.00")          # Money.parse("12.00") under the ho
 StoreQuery.execute(budget: Money.new(1200))  # passed straight through
 ```
 
-Bad input still explodes (the cast raises), so some safety survives; coercion
-needs both a cast and a serialize. Off by default — the strict typed kwarg is the norm.
+`GraphWeaver.auto_coerce = true` is the same switch for every scalar at once —
+set it any time before you generate; an explicit `coerce:` on a registration
+always wins. Off by default either way: the strict typed kwarg is the norm.
 
-`coerce:` also takes a **Symbol** naming a conversion method, for built-ins where
-a plain method is the whole story — `coerce: :to_f` makes a variable accept
-`5`/`"5"` and `.to_f` it, sending a native number (not `"5.0"`) on the wire. The
-convertible built-ins already know theirs (`Float`→`:to_f`, `Int`→`:to_i`,
-`ID`/`String`→`:to_s`), so rather than opting in each, flip the default:
-
-```ruby
-GraphWeaver.auto_coerce = true
-```
-
-Resolved lazily at generation time (set it any time before you generate),
-it gives convertible built-ins their conversion and any scalar with a full
-cast/serialize pair (`Date`, your `Money`) parse-style coercion; an explicit
-`coerce:` on a registration always wins. `Boolean` has no lossless
-one-method conversion, so it stays strict.
+*How* a scalar coerces isn't yours to pick — the scalar already knows. `Int` and
+`Float` convert (`"5"` → `5`, sent as a native number); anything with a full
+cast/serialize pair (`Date`, your `Money`) parses, and bad input still explodes
+because the cast raises. A pass-through scalar — `String`, `ID`, `Boolean` — has
+neither a conversion nor a codec pair, so it can't coerce at all: `coerce: true`
+on one raises rather than emitting a no-op.
 
 The built-in scalars (`Date`, `ID`, `Int`, …) are pre-registered through the
 same path (`Date` even carries its own `require "date"`), so a later
-`register_scalar` overrides them; `GraphWeaver.reset_scalars!` restores the
-defaults (`reset_scalars!(coerce: true)` restores them coercible) and
-`clear_scalars!` empties the registry. Register before generating — it's a
-codegen-time concern, baked into the emitted source.
+`register_scalar` overrides them.
+
+`GraphWeaver.reset_registrations!` is the clean slate between tests: built-in
+scalars restored, enum mappings and type helpers dropped. To reset one registry
+rather than all of them, `GraphWeaver::Codegen` has the pieces —
+`reset_scalars!` (restore the built-ins), `clear_scalars!` (empty the registry
+entirely), `reset_enums!`, `reset_type_helpers!`.
+
+A scalar you never register is not an error — it generates as `T.untyped` and
+the wire value passes through untouched. It is, though, the one hole in an
+otherwise exact result type, so generation names the holes at `info` (see
+[logging](logging.md)):
+
+```
+3 unregistered custom scalars → T.untyped: CountryCode, FuzzyDateInt, Json (register with GraphWeaver.register_scalar)
+```
 
 ## Enums: map onto your own T::Enum
 
-By default each generated module grows its own `T::Enum` per GraphQL
-enum — `AddPetQuery::Species`, `SearchQuery::Result::...::Species`, one
-per module that touches it. That's fine until your app has its own
-domain enum, and then the boundary shuffle starts:
+By default a schema enum generates one `T::Enum` per schema, shared by every
+query module that touches it (`GraphQLTypes::Species`, aliased as
+`AddPetMutation::Species`). That's fine until your app has its own domain
+enum, and then the boundary shuffle starts:
 
 ```ruby
 # your domain already speaks PetKind — it's in your models, your
@@ -105,28 +104,24 @@ end
 
 # without a mapping, every call site converts by hand, in both directions
 kind = PetKind.deserialize(pet.species.serialize.downcase)      # response -> domain
-AddPetQuery.execute!(species: kind.serialize.upcase)            # domain -> wire
+AddPetMutation.execute!(species: kind.serialize.upcase)            # domain -> wire
 ```
 
-Two enums for one concept, glue at every crossing, and each generated
-module has its *own* incompatible `Species`, so a pet from `SearchQuery`
-and a pet from `AddPetQuery` don't even compare. Register the mapping
-once and the seam disappears — generated code speaks your enum
-everywhere, casting wire values in and serializing members out:
+Register the mapping once and the seam disappears — generated code speaks your
+enum everywhere, casting wire values in and serializing members out:
 
 ```ruby
-GraphWeaver.register_enum("Species", PetKind)                # global
-api.register_enums("Species" => PetKind, "Role" => Role)     # or per client, in bulk
+GraphWeaver.register_enum("Species", PetKind)
 
 pet.species                                   # => PetKind::Dog — compare, case, persist directly
 pet.species == other_pet.species              # same type across every query
-AddPetQuery.execute!(species: PetKind::Cat)   # or "CAT" — members and wire values both work
+AddPetMutation.execute!(species: PetKind::Cat)   # or "CAT" — members and wire values both work
 ```
 
 **When to reach for it**: the enum has a life outside the API — it's
-persisted, matched in business logic, or shared across queries. **When
-not to bother**: display-only values you read and forget; the per-module
-generated enums are self-contained and need zero setup.
+persisted or matched in business logic. **When not to bother**: values you
+only read back out of responses; the generated enum is already one type
+across every query and needs zero setup.
 
 The mapping is inferred by name (`"CAT"` ↔ `PetKind::Cat`,
 case/underscore-insensitive against each member's serialized value), so
@@ -151,107 +146,7 @@ Two safety properties do the real work:
 
 The translation tables are emitted into the generated source
 (`SPECIES_FROM_WIRE` / `SPECIES_TO_WIRE`) — reviewable in the diff, no
-runtime registry. And because registration can be client-scoped, two
-servers with different ideas of `"Species"` can map onto different (or
-the same) domain enums without touching each other.
-
-## Type helpers: your logic on generated structs
-
-Derived values (display names, emoji, predicates) belong next to the
-data but not *in* it — rewriting wire values on the way in destroys the
-raw truth. Register a plain module and every struct generated from that
-GraphQL type includes it, whatever query it appears in:
-
-```ruby
-module PetHelpers
-  def adult? = birthday && birthday < Date.today << 24
-  def display_name = adult? ? "#{name} 🦴" : "#{name} 🐶"
-end
-
-GraphWeaver.extend_type("Pet", PetHelpers)   # or api.extend_type(...)
-
-pet.display_name   # => "Shelby 🦴"
-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
-(global plus client-scoped stack). One caveat on *static* typing, though:
-`srb tc` checks a mixin's method bodies in the module's own scope, not the
-including struct's — so a helper that reads a wire field (`name`, `birthday`)
-doesn't resolve it and fails with "method does not exist on the module." Write
-such a helper at `# typed: false`, or reach the field through `T.unsafe(self)`
-— either way its body isn't statically checked against the selection. (Sorbet's
-`requires_ancestor` is the escape in principle, but it needs an experimental
-flag and a concrete ancestor, which a per-query struct isn't.) The only place a
-field-reading derivation type-checks natively is *inside* the struct body, where
-the field is in scope — which is codegen's job, not a mixin's.
-
-For quick decoration, build the mixin inline — the block is
-`module_eval`'d into a fresh module auto-named under
-`GraphWeaver::TypeHelpers` so generated files can reference it:
-
-```ruby
-api.extend_type("Pet") do
-  def display_name = "#{name} 🐶"
-end
-```
-
-Same runtime behavior, less static reach: the block becomes a runtime module
-with no source on disk, so `srb tc` can't see its methods at all — fine in
-dynamic `parse`, but in a checked-in `# typed: strict` file it's an unresolved
-reference. Prefer a named module (and mind the field-access caveat above) where
-static checking matters — complexity on demand.
-
-### Flat accessors with `alias:`
-
-The one derivation the generator can type for you is a plain projection — a
-selected field, possibly nested, exposed under a flat accessor. `alias:` emits a
-sig'd delegator *into the struct body*, where the field is in scope, so it's
-fully checked (the thing a mixin can't be):
-
-```ruby
-GraphWeaver.extend_type("Widget", alias: { tag: "meta.tag" })
-
-# generated on the Widget struct:
-#   sig { returns(T.nilable(String)) }
-#   def tag = meta&.tag
-```
-
-So a hand-written value object that only existed to expose `tag` flat over
-`data.dig("meta", "tag")` drops away — the generated struct answers `.tag`
-directly. Forms:
-
-```ruby
-alias: { tag: "meta.tag" }              # explicit accessor name
-alias: "meta.tag"                       # accessor named after the last segment (`tag`)
-alias: ["meta.tag", "meta.color"]       # several at once
-alias: { label: "name", tag: "meta.tag" }
-```
-
-The path is the Ruby accessor chain (`meta.tag`), typed from the selection: any
-nullable hop makes the accessor nilable and inserts `&.`; the leaf can be a
-scalar, enum, or nested struct. It's validated against each query at generation —
-an unselected or misspelled segment (`did you mean 'tag'?`), a selector on a
-non-list, or a name that collides with a real field all fail with a pointed
-error. Registrations stack and are client-scopable, like the mixin forms.
-
-A segment can also be `first` or `last` to pick one element out of a list hop —
-always nilable, since the list may be empty. This is what turns an
-`_entities`-style "array that logically holds one thing" into a clean accessor:
-
-```ruby
-GraphWeaver.extend_type("Query", alias: { entity: "_entities.first" }, optional: true)
-
-#   sig { returns(T.nilable(Widget)) }        # concrete, when the selection is one `... on Widget`
-#   def entity = _entities&.first             # (a multi-fragment selection types it as the union)
-```
-
-`optional: true` makes the aliases *lenient*: a query whose selection doesn't fit
-the path just omits the accessor instead of failing generation. Reach for it when
-the alias lives on a universal type like `Query` — where a strict alias would
-force *every* query to select the path — or when it only fits some selections.
+runtime registry.
 
-For anything beyond a passthrough projection — real logic, still typed — reopen
-the generated struct in your own file and add sig'd methods; Sorbet merges the
-bodies.
+Decorating a generated *struct* with your own methods is the sibling API —
+`extend_type`, in [generated modules](generated_modules.md#type-helpers).