graph_weaver 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3847d3890b566828d7bfe496a6523b1032036d6aad4df0959f0b940bddb14d9b
-  data.tar.gz: d2a38677d13f8a0f2a92c67c9082a1a9523add9429bf4388419dbabc8959302f
+  metadata.gz: 12bea1d4f3d38c00c496ec595788629ea6c12c9f7590fc7938976570d8c86917
+  data.tar.gz: e7f8e60574801cc70032a4e2502a05d6ec8f9ac170ab22b53fa12b4f2633835a
 SHA512:
-  metadata.gz: 118114092cf2cd436e8189fb79dd5be733aa25e34d0aa727da9247e87bc5e309b2b3692248ffa9e40832bf743d672859db444c3fcffc4fc1cbb263b6c395b7e4
-  data.tar.gz: c0846cca1819d0e2b75d98f4b8d6a74af2f29113686998bd9e616a7d7d1e9a3a70edbe985412c4750a8ec63f0f0c4389e6363c1bc9d58b251a10b2f652d10e0b
+  metadata.gz: e913ad4e5104a983b7ba0d87ae838de4a6e9e238aa7fc70c3d8d673ee24faba7eecf2734c7d403443cd2acdf93d4723adbc01bc0fc485e738df608f63adf43c1
+  data.tar.gz: cc1d344c3f99c5d587a3abb5e385626048d4821766c458ae7a7401b639ab9851c6c253d618282b9e314310bae88583240b0770588b06c898052e7a96d8472975

data/CHANGELOG.md

@@ -1,3 +1,26 @@
+###  v0.6.1  (2026-09-10)
+- **A stdlib scalar registers with nothing but its class.**
+  `GraphWeaver.register_scalar("Decimal", BigDecimal)` now emits the whole
+  codec: `BigDecimal(...)` reads the wire value, `to_s("F")` writes it back,
+  and the generated file requires `bigdecimal`. The careful spelling people
+  reached for was wrong — `serialize: :to_s` puts `"0.125e2"` on the wire —
+  so the library owns it. Cast inference gained Kernel's conversion functions
+  (`BigDecimal()`, and any `Kernel#Type` your app defines for a type the wire
+  can't already be), and `serialize:` accepts `[:method, *args]` for a
+  serializer that takes arguments. `cast:`/`serialize:`/`requires:` are
+  unchanged, for a class of your own.
+- **Scalar names that are conventions are registered already**: graphql-ruby's
+  `ISO8601Date`, `ISO8601DateTime`, `BigInt` and `JSON`, plus `DateTime` —
+  what GitHub, Shopify and most hand-written schemas call an ISO 8601
+  timestamp. A date deserializes into `Date` and a timestamp into `Time`, so
+  nothing invents a midnight; `BigInt` reads the decimal string graphql-ruby
+  writes as well as a JSON number; `JSON` is registered as `T.untyped` on
+  purpose, which also drops it from the "unregistered custom scalars" report.
+  A schema that means something else by one of these names fails loudly — the
+  cast raises, naming the field — and one `register_scalar` overrides it, as
+  it always could. **Regenerate** if a query of yours reads a scalar with one
+  of those names: its prop was `T.untyped` and now has a type.
+
 ###  v0.6.0  (2026-09-09)
 - **One rule for relative path settings: they resolve against
   `GraphWeaver.root`** — `Rails.root` in a Rails app, the working directory

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    graph_weaver (0.6.0)
+    graph_weaver (0.6.1)
       graphql (>= 2.6.7)
       sorbet-runtime
 
@@ -176,7 +176,7 @@ CHECKSUMS
   google-protobuf (4.35.1-arm64-darwin) sha256=d9c957df04fa89c749fa9a72a7b383eb4296efc9b2303dc6fd6fbe39c698ad6b
   google-protobuf (4.35.1-x86_64-darwin) sha256=66b62b4df00931018a692806df66393efa960d6d2b7da69735187249f950d3ee
   google-protobuf (4.35.1-x86_64-linux-gnu) sha256=c786439087512a3fbd199e9897d265b855f951d4027e218ea55e858d45969edd
-  graph_weaver (0.6.0)
+  graph_weaver (0.6.1)
   graphql (2.6.10) sha256=9b7c8633767f516ff9d48a8d6305b2a00a2101c82aa871b92e69086944f9f83e
   i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc

data/README.md

@@ -175,7 +175,7 @@ upgrade, and `verify` is what tells you when you've skipped it.
 - **[Federation](docs/federation.md)** — supergraph vs API schema, the local router, what it refuses
 - **[Transports](docs/transports.md)** — the execute contract, Faraday, retries and backoff
 - **[Errors](docs/errors.md)** — the Response envelope, the error hierarchy, field-level reports
-- **[Custom scalars](docs/scalars.md)** — the registry: codec inference, requires, input coercion
+- **[Custom scalars](docs/scalars.md)** — what's registered already, codec inference, input coercion
 - **[Cassettes](docs/cassettes.md)** — capture and replay real responses, anonymized
 - **[Editor support](docs/editors.md)** — five lines of YAML for schema autocomplete in `.graphql` files, no JS project
 - **[Against a real API](docs/real_world.md)** — introspecting a live endpoint, GitHub end to end

data/docs/getting_started.md

@@ -58,7 +58,7 @@ What it wrote:
   into generated source, so they have to run first:
 
   ```ruby
-  GraphWeaver.register_scalar("DateTime", Time, serialize: :iso8601, requires: "time")
+  GraphWeaver.register_scalar("Money", Money)   # a scalar the registry can't know
   ```
 
   A registration that names one of your own constants — a `T::Enum` for

data/docs/real_world.md

@@ -19,10 +19,10 @@ require "graph_weaver"
 # in a header, so a stale dump says where it came from.
 github = GraphWeaver.new("https://api.github.com/graphql", auth: `gh auth token`.strip, cache: true)
 
-# map GitHub's DateTime scalar onto Time (cast inferred from Time.parse).
-# Registrations are global and codegen-time, so this line types your
-# console and your checked-in code identically (docs/scalars.md).
-GraphWeaver.register_scalar("DateTime", Time, serialize: :iso8601, requires: "time")
+# GitHub's DateTime needs no registration — it is one of the names the
+# registry knows (docs/scalars.md). A scalar of your own would go here;
+# registrations are global and codegen-time, so one line types your
+# console and your checked-in code identically.
 
 RepoQuery = github.parse(<<~GRAPHQL)
   query($owner: String!, $name: String!) {

data/docs/scalars.md

@@ -2,74 +2,136 @@
 
 Teach the generator how a GraphQL custom scalar deserializes into a rich
 Ruby object (and serializes back when used as a variable). A field typed
-`Money` then generates `const :price, T.nilable(Money)` and casts with
-`Money.parse(...)` inline — no runtime reflection:
+`Decimal` then generates `const :price, T.nilable(BigDecimal)` and casts with
+`BigDecimal(...)` inline — no runtime reflection:
 
 ```ruby
-GraphWeaver.register_scalar("Money", Money, requires: "bigdecimal")
+GraphWeaver.register_scalar("Decimal", BigDecimal)
 ```
 
+Two arguments: the scalar's name in your schema, and the Ruby type it means.
+The second is the only part the library can't work out — how a wire value
+becomes a `BigDecimal`, how one goes back on the wire, and the
+`require "bigdecimal"` the generated file needs are all inferred.
+
 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
-across fields:
+## Already registered
 
-```ruby
-GraphWeaver.register_scalar("ISO8601DateTime", Time)   # the default, everywhere
-GraphWeaver.register_scalar("User.birthday", Date)     # this field only
-```
+These names need no registration. graphql-ruby ships all but `DateTime` as its
+own scalars, and `DateTime` is what GitHub, Shopify and most hand-written
+schemas call an ISO 8601 timestamp.
 
-A field override wins over the scalar-name registration — which is also how two
-servers that disagree about a `DateTime` coexist in one process.
+| scalar | Ruby type | on the wire |
+|---|---|---|
+| `ID` | `String` | the string (an `Integer` input is accepted) |
+| `String` | `String` | the string |
+| `Int` | `Integer` | a JSON integer |
+| `Float` | `Float` | any JSON number |
+| `Boolean` | `T::Boolean` | the boolean |
+| `Date`, `ISO8601Date` | `Date` | `"2024-01-15"` |
+| `DateTime`, `ISO8601DateTime` | `Time` | `"2024-01-15T10:20:30Z"` |
+| `BigInt` | `Integer` | the decimal string graphql-ruby writes; a JSON number is read too |
+| `JSON` | `T.untyped` | whatever it is, untouched |
+
+A date stays a `Date` and a timestamp a `Time`, deliberately: casting a date to
+`Time` invents a midnight the server never sent. A schema that means something
+else by one of these names fails loudly — the cast raises, naming the field —
+and one `register_scalar` overrides it, like any other entry. Names that are
+*not* a convention (`Timestamp`, `UUID`, `URL`, `Decimal`, `Money`) are left to
+you, because guessing at one would be worse than asking.
+
+## Registering a stdlib type
+
+Name the class and stop. What the library supplies is the part inference can't
+reach: the wire spelling (`BigDecimal#to_s` writes `"0.125e2"`, which is not
+what any server means by 12.5, and `Date.parse` reads far more than the ISO
+8601 a `Date` scalar carries) and the file to require, so the generated source
+stands alone.
+
+| Ruby type | cast | serialize | require |
+|---|---|---|---|
+| `BigDecimal` | `BigDecimal(v)` | `v.to_s("F")` | `bigdecimal` |
+| `Date` | `Date.iso8601(v)` | `v.iso8601` | `date` |
+| `Time` | `Time.parse(v)` | `v.iso8601` | `time` |
+| `DateTime` | `DateTime.iso8601(v)` | `v.iso8601` | `date` |
 
-Registrations are validated against the schema you generate against, and only
-what that schema can **disprove** fails generation: a name it declares as
-something else (`register_scalar("Species")` where `Species` is an enum), or a
-coordinate whose field it declares as a composite. A name it simply can't match
-only warns — one registry serves a whole graph, so that name may belong to the
-subgraph next door (see
-[federation](federation.md#generating-for-a-federated-graph)).
+For a timestamp, reach for `Time`; Ruby's own `DateTime` is accepted if you
+register it, but never assumed. `BigDecimal(v)` is Ruby's own reader, so
+it takes what Ruby takes — `"12.5"`, `"1e3"`, a JSON number — and refuses
+`"abc"` or `"$12.50"`, naming the field or the variable.
 
-Pass a real class as the second argument and the cast/serialize are
-**inferred** from it by probing the deserialize side and pairing its serializer:
+## Registering a class of your own
 
-| the class defines | cast          | serialize      |
+Pass the class and the cast/serialize are **inferred** from it, by probing the
+deserialize side and pairing its serializer:
+
+| the class defines | cast | serialize |
 |-------------------|---------------|----------------|
-| `.parse`          | `Type.parse(v)` | `v.to_s`     |
-| `.load`           | `Type.load(v)`  | `Type.dump(v)` |
+| `.parse` | `Type.parse(v)` | `v.to_s` |
+| `.load` | `Type.load(v)` | `Type.dump(v)` |
+| `Kernel#Type` | `Type(v)` | — |
+
+so a value object with a `.parse` needs nothing more:
 
-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:
+```ruby
+GraphWeaver.register_scalar("Money", Money)
+```
+
+A type defining none of those stays pass-through rather than getting wrapped —
+every object has `#to_s`, so inferring a serializer off it would wrap plain
+types too. Override explicitly when you need to:
 
 - a `Symbol` method name, nothing to misspell: `cast: :load` → `Money.load(expr)`,
   `serialize: :to_json` → `expr.to_json`
+- an `Array`, for a method with arguments: `serialize: [:to_s, "F"]` → `expr.to_s("F")`
 - a `Proc` for anything a method name can't express: `cast: ->(expr) { "Money.new(#{expr})" }`
 - `:itself` to force pass-through, opting out of inference (rare)
 
-The type also accepts a plain string (`"BigDecimal"`) when you'd rather not
+The type also accepts a plain string (`"Money"`) when you'd rather not
 reference the class. `requires:` (a string or array) names files emitted as
 `require`s atop the generated source so the cast/type resolve. When the type is
 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.
 
+## Overriding one field
+
+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
+across fields:
+
+```ruby
+GraphWeaver.register_scalar("Timestamp", Time)      # the default, everywhere
+GraphWeaver.register_scalar("User.birthday", Date)  # this field only
+```
+
+A field override wins over the scalar-name registration — which is also how two
+servers that disagree about a `DateTime` coexist in one process.
+
+Registrations are validated against the schema you generate against, and only
+what that schema can **disprove** fails generation: a name it declares as
+something else (`register_scalar("Species")` where `Species` is an enum), or a
+coordinate whose field it declares as a composite. A name it simply can't match
+only warns — one registry serves a whole graph, so that name may belong to the
+subgraph next door (see
+[federation](federation.md#generating-for-a-federated-graph)).
+
 The testing harness can't invent a wire value for a scalar registered as your
 own class — only `Money.parse` knows what it accepts — so it refuses rather than
 guess. Say it in test config, where that answer belongs: a pin for the type,
 `GraphWeaver::Testing.config.overrides = { "Money" => "12.00" }`, or per example
-([testing → pins](testing.md#pins)). A scalar registered as `Time`, `Date`,
-`Integer`, `Float`, `String` or `T::Boolean` needs nothing.
+([testing → pins](testing.md#pins)). A scalar registered as one of the types
+above — `BigDecimal`, `Time`, `Date`, `Integer`, `Float`, `String`,
+`T::Boolean` — needs nothing.
 
-A registration whose type is a class **JSON can't parse into** needs a
-`cast:` to build one — `BigDecimal` is the one people reach for, and it defines
-neither `.parse` nor `.load`, so inference finds no codec and the prop would be
-unsatisfiable. Generation refuses it where a query reads that scalar back,
-naming the field:
+A registration whose type is a class **JSON can't parse into**, with nothing to
+build one, is refused where a query reads that scalar back: the prop would be
+unsatisfiable for every response, and finding that out at runtime is worse.
+Generation names the field:
 
 ```
-register_scalar("Money", BigDecimal) has no cast, so nothing builds a BigDecimal
+register_scalar("Money", Wallet) has no cast, so nothing builds a Wallet
 out of the JSON at Product.price — give it one ...
 ```
 
@@ -91,9 +153,6 @@ stays as narrow as the schema and the conversion happens in its body (see
 error — as it should be, since you have a `Money` right there — while
 `budget: params[:budget]` typechecks and converts.
 
-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.
 
 ## What the wire carries
 
@@ -119,8 +178,9 @@ server writing a non-integer where the spec says integer, so it is refused.
 | `Boolean` | `true`, `false` | `"true"`, `1`, `0` |
 | `Date` | ISO-8601: `"2024-01-01"`, `"20240101"`, and a full timestamp (truncated) | any other spelling, an epoch integer |
 | `DateTime`/`Time` (registered as `Time`) | RFC 3339 with `Z` or an offset, with or without fractional seconds, seconds optional; also a bare date and `Time.parse`'s looser forms | an epoch integer, an unparseable string |
+| `BigInt` | the decimal string graphql-ruby writes, past 2⁵³ included; also a JSON integer | `1.5`, `"1.5"`, a non-numeric string, `true` |
 | an enum | a declared value, as a string | an undeclared value, a non-string |
-| unregistered | anything — `T.untyped`, straight through | nothing |
+| `JSON`, or unregistered | anything — `T.untyped`, straight through | nothing |
 
 A refusal is a [`GraphWeaver::TypeError`](errors.md) naming the field and the
 generated struct (which names the query). Two refusals carry advice rather than
@@ -148,10 +208,11 @@ the sig is `.checked(:never)`).
 | `Boolean` | `true`/`false` | nothing | the boolean |
 | `Date` | `Date` | an ISO-8601 string | `iso8601` |
 | `Time` | `Time` | a string `Time.parse` takes | `iso8601` |
+| `BigInt` | `Integer` | a decimal string | the decimal string, which is what the server writes |
 | an enum | the member **or** its wire value | — | the wire value |
 | an input object | the struct **or** a Hash | — | the wire hash |
-| a registered custom scalar | its Ruby type | whatever its `cast:` takes | its `serialize:` |
-| unregistered | `T.untyped` | anything | straight through |
+| a registered custom scalar | its Ruby type | whatever its cast takes | what its serialize writes |
+| `JSON`, or unregistered | `T.untyped` | anything | straight through |
 
 Two rows are judgment calls worth stating. **`ID` takes an `Integer`** because
 the GraphQL spec says an ID serializes as a string but accepts an integer input,
@@ -183,6 +244,10 @@ otherwise exact result type, so generation names the holes at `info` (see
 3 unregistered custom scalars → T.untyped: CountryCode, FuzzyDateInt, Json (register with GraphWeaver.register_scalar)
 ```
 
+A scalar that is *meant* to be untyped belongs in the registry too —
+`GraphWeaver.register_scalar("Json", "T.untyped")` says so once, and it leaves
+the report. `JSON` is registered that way already.
+
 ## Enums: map onto your own T::Enum
 
 By default a schema enum generates one `T::Enum` per schema, shared by every

data/docs/testing.md

@@ -181,8 +181,8 @@ A **scalar type pin** is the one thing a scalar registered as *your own class*
 needs — only `Money.parse` knows what wire value it accepts — so without one
 fabrication refuses at the path it reached (`at reader.orders.0.total`) and
 names the pin to add, rather than feeding your cast a placeholder that fails
-deep inside `from_h`. A scalar registered as `Time`, `Date`, `Integer`,
-`Float`, `String` or `T::Boolean` needs nothing. Suite-wide, the same hash is
+deep inside `from_h`. A scalar registered as `BigDecimal`, `Time`, `Date`,
+`Integer`, `Float`, `String` or `T::Boolean` needs nothing. Suite-wide, the same hash is
 `config.overrides`, and the [cassette anonymizer](cassettes.md) reads it too.
 
 Pins lead and options follow — `graphql_fake("Money" => "12.00", values:

data/docs/upgrading.md

@@ -163,8 +163,8 @@ are emitted `private_constant`, so **regenerate**.
   holding a registered custom scalar: the anonymizer used to write a value the
   generated codec couldn't read back.
 - **Generation refuses four more things**, each naming its fix — a
-  `register_scalar` whose Ruby type nothing can build out of JSON (`BigDecimal`,
-  classically: give it a `cast:`), a result key that would shadow a constant the
+  `register_scalar` whose Ruby type nothing can build out of JSON (a value
+  object of your own: give it a `cast:`), a result key that would shadow a constant the
   file uses, an enum value that camelizes to nothing, and a narrowed fragment
   whose `__typename` sits behind `@skip`/`@include`.
 

data/lib/graph_weaver/codegen/scalar_type.rb

@@ -12,10 +12,12 @@ class GraphWeaver::Codegen
   # scalars and overrides go through the same path.
   #
   # cast/serialize normalize to procs that, given a Ruby expression string,
-  # return the code to inline. Left nil (the default) they are inferred
-  # from the Ruby type when it is a real class, by probing for a known
-  # deserializer and pairing its serializer (see CODECS) — so the common
-  # case needs no more than a class:
+  # return the code to inline. Left nil (the default) they are inferred from
+  # the Ruby type: a type the library already knows takes its codec from
+  # STDLIB, otherwise it is probed for a known deserializer whose serializer
+  # pairs with it (see CODECS), and failing that for a Kernel conversion
+  # function of its own name — so the common case needs no more than a class:
+  #      type: BigDecimal (Kernel#BigDecimal) => BigDecimal(expr) / expr.to_s("F")
   #      type: Money   (defines .parse)   => Money.parse(expr) / expr.to_s
   #      type: Blob    (defines .load)    => Blob.load(expr)   / Blob.dump(expr)
   # Probing the *deserialize* side is deliberate: every object has #to_s,
@@ -25,6 +27,7 @@ class GraphWeaver::Codegen
   #   - a Symbol names a method, so there is no string to misspell:
   #           cast: :load        => "Blob.load(expr)"    (class method on type)
   #           serialize: :to_json => "expr.to_json"      (instance method)
+  #   - an Array is that method with arguments: serialize: [:to_s, "F"]
   #   - a Proc handles anything a Symbol can't express:
   #           cast: ->(e) { "Money.new(#{e})" }
   #   - :itself opts out — force identity pass-through even when a codec
@@ -59,7 +62,29 @@ class GraphWeaver::Codegen
       "String" => "string",
       "T::Boolean" => "boolean",
     }.freeze
-    private_constant :Codec, :CODECS, :COERCERS
+
+    # What the library already knows about a Ruby type, so registering one
+    # takes nothing but the class. Consulted only where the registration is
+    # silent; an explicit cast:/serialize:/requires: wins. Two things the
+    # probe above can't work out on its own:
+    #   - the wire spelling. BigDecimal#to_s writes "0.125e2", which is not
+    #     what any server means by 12.5, and Date.parse reads a great deal
+    #     more than the ISO 8601 a Date scalar carries.
+    #   - the file to require, so the generated source stands alone.
+    # Only types whose wire form is unambiguous belong here.
+    STDLIB = {
+      "BigDecimal" => { serialize: [:to_s, "F"], requires: "bigdecimal" },
+      "Date" => { cast: :iso8601, serialize: :iso8601, requires: "date" },
+      "Time" => { cast: :parse, serialize: :iso8601, requires: "time" },
+      "DateTime" => { cast: :iso8601, serialize: :iso8601, requires: "date" },
+    }.freeze
+
+    # Everything JSON.parse can hand back. A registered type outside this set
+    # has to be BUILT from one of them, which is what a cast is for (and what
+    # Codegen#refuse_uncastable! insists on).
+    WIRE_CLASSES = [String, Integer, Float, Hash, Array, TrueClass, FalseClass].freeze
+
+    private_constant :Codec, :CODECS, :COERCERS, :STDLIB
 
     attr_reader :graphql_name, :type, :requires
 
@@ -67,14 +92,22 @@ class GraphWeaver::Codegen
       @graphql_name = graphql_name.to_s
       @klass = type.is_a?(Module) ? type : nil
       @type = type_name(type)
-      # requires: load BEFORE codec probing — the probe method may come
-      # from the required file (core Time has no .parse until the "time"
-      # stdlib loads)
-      @requires = normalize_requires(requires)
+      known = STDLIB[@type] || {}
+      # requires: load BEFORE probing — the deserializer may arrive with the
+      # file (core Time has no .parse until the "time" stdlib loads, and
+      # Kernel#BigDecimal none until "bigdecimal" does). A path from STDLIB
+      # is the library's own, so it loads even for a type: given as a String,
+      # whose dependency we otherwise can't assume is installed.
+      @requires =
+        if requires.nil?
+          GraphWeaver::Codegen.normalize_requires!(known[:requires], load: true)
+        else
+          GraphWeaver::Codegen.normalize_requires!(requires, load: !@klass.nil?)
+        end
       codec = @klass && CODECS.find { |c| @klass.respond_to?(c.probe) }
-      @cast = normalize_cast(cast, codec&.cast)
-      @serialize = normalize_serialize(serialize, codec&.serialize)
-      @serialize_value = runtime_serialize(serialize, codec)
+      @cast = normalize_cast(cast || known[:cast], codec&.cast || kernel_cast)
+      @serialize = normalize_serialize(serialize || known[:serialize], codec&.serialize)
+      @serialize_value = runtime_serialize(serialize || known[:serialize], codec)
     end
 
     def cast(expr) = @cast&.call(expr)
@@ -126,6 +159,17 @@ class GraphWeaver::Codegen
       end
     end
 
+    # Kernel's conversion functions are how a wire value becomes one of these
+    # — BigDecimal defines neither .parse nor .load, but Kernel#BigDecimal has
+    # read a decimal string all along. Only for a type the wire can't already
+    # be: Kernel#String and Kernel#Array wrap a value rather than convert it.
+    def kernel_cast
+      return unless Kernel.private_method_defined?(@type.to_sym)
+      return if WIRE_CLASSES.any? { |native| native.name == @type }
+
+      ->(type, expr) { "#{type}(#{expr})" }
+    end
+
     # nil infers via the matched codec; :itself opts out (identity); a
     # Symbol is a class method on the type — Money.parse(expr)
     def normalize_cast(cast, inferred)
@@ -138,33 +182,37 @@ class GraphWeaver::Codegen
       end
     end
 
-    # nil infers via the matched codec; :itself opts out (identity); a
-    # Symbol is an instance method on the value — expr.to_s
+    # nil infers via the matched codec; :itself opts out (identity); a Symbol
+    # is an instance method on the value — expr.to_s — and an Array is that
+    # method with arguments: [:to_s, "F"] => expr.to_s("F")
     def normalize_serialize(serialize, inferred)
       case serialize
       when :itself then nil
       when nil then inferred && ->(expr) { inferred.call(@type, expr) }
       when Proc then serialize
       when Symbol then ->(expr) { "#{expr}.#{serialize}" }
-      else raise ArgumentError, "serialize: must be a Symbol, Proc, :itself, or nil, got #{serialize.inspect}"
+      when Array
+        method, *args = serialize
+        unless method.is_a?(Symbol)
+          # a syntax error in the generated file otherwise
+          raise ArgumentError, "serialize: an Array is [method, *arguments], got #{serialize.inspect}"
+        end
+
+        ->(expr) { "#{expr}.#{method}(#{args.map(&:inspect).join(", ")})" }
+      else raise ArgumentError, "serialize: must be a Symbol, Array, Proc, :itself, or nil, got #{serialize.inspect}"
       end
     end
 
-    # The runnable half of normalize_serialize: a Symbol names a method
-    # (:itself included, which is identity either way), an inferred codec
-    # knows its own call, and a Proc emits code there is no way to run.
+    # The runnable half of normalize_serialize: a Symbol (or Symbol with
+    # arguments) names a method — :itself included, which is identity either
+    # way — an inferred codec knows its own call, and a Proc emits code there
+    # is no way to run.
     def runtime_serialize(serialize, codec)
       case serialize
-      when Symbol then ->(value) { value.public_send(serialize) }
+      when Symbol, Array then ->(value) { value.public_send(*serialize) }
       when nil then codec && ->(value) { codec.call.call(@klass, value) }
       end
     end
-
-    # With only a type-name string we can't assume the lib is installed at
-    # codegen time, so the paths aren't loaded — only shape-checked.
-    def normalize_requires(requires)
-      GraphWeaver::Codegen.normalize_requires!(requires, load: !@klass.nil?)
-    end
   end
 
   class << self
@@ -230,24 +278,42 @@ class GraphWeaver::Codegen
       self
     end
 
-    # Built-in scalars — pre-registered entries in the one registry. Most stay
-    # pass-through: their Ruby classes (String, Integer) define neither .parse
-    # nor .load, so codec inference matches nothing and leaves them identity —
-    # which is exactly why we can name them with the real class constants.
-    # Float is the exception: JSON has one number type, so a whole Float
-    # arrives as `1` from every encoder that drops the trailing zero
-    # (graphql-js and Go both do), and Coerce.float widens that without
-    # accepting the garbage `.to_f` would silently turn into 0.0. Date
-    # deserializes via ISO-8601 (it *does* define .parse, but we want iso8601
-    # specifically, so it's explicit). The rest carry no cast and coerce
-    # input by their Ruby type — see coerce_input.
+    # Pre-registered scalars — ordinary entries in the one registry, so a
+    # later register_scalar overrides any of them.
+    #
+    # The five the spec names stay pass-through: their Ruby classes (String,
+    # Integer) define neither .parse nor .load, so inference matches nothing
+    # and leaves them identity — which is exactly why we can name them with
+    # the real class constants. Float is the exception: JSON has one number
+    # type, so a whole Float arrives as `1` from every encoder that drops the
+    # trailing zero (graphql-js and Go both do), and Coerce.float widens that
+    # without accepting the garbage `.to_f` would silently turn into 0.0.
+    #
+    # The rest are names, not guesses: graphql-ruby ships all but DateTime as
+    # its own scalars, and this library runs a graphql-ruby schema in-process.
+    # DateTime is what GitHub, Shopify and most hand-written schemas call an
+    # ISO 8601 timestamp; a schema that means something else by it fails
+    # loudly (the cast raises, naming the field) and is one register_scalar
+    # away. Date and datetime are told apart by their Ruby type — a Date cast
+    # to Time would invent a midnight the server never sent.
     def register_builtin_scalars!
       register_scalar "ID", String
       register_scalar "String", String
       register_scalar "Int", Integer
       register_scalar "Float", Float, cast: ->(expr) { "GraphWeaver::Coerce.float(#{expr})" }
       register_scalar "Boolean", "T::Boolean"
-      register_scalar "Date", Date, cast: :iso8601, serialize: :iso8601, requires: "date"
+      register_scalar "Date", Date
+      register_scalar "ISO8601Date", Date
+      register_scalar "ISO8601DateTime", Time
+      register_scalar "DateTime", Time
+      # graphql-ruby writes a BigInt as a string, since JSON numbers stop
+      # being exact at 2^53 — so read either spelling and write the one the
+      # server does.
+      register_scalar "BigInt", Integer,
+        cast: ->(expr) { "GraphWeaver::Coerce.integer(#{expr})" }, serialize: :to_s
+      # untyped on purpose: registering it says so, rather than leaving JSON
+      # in the "unregistered custom scalars" report every generation
+      register_scalar "JSON", "T.untyped"
     end
     private :register_builtin_scalars!
   end

data/lib/graph_weaver/codegen.rb

@@ -1285,21 +1285,16 @@ class GraphWeaver::Codegen
     Scalar.new(scalar)
   end
 
-  # Everything JSON.parse can hand back. A registered type outside this set
-  # has to be BUILT from one of them, which is what cast: is for.
-  WIRE_CLASSES = [String, Integer, Float, Hash, Array, TrueClass, FalseClass].freeze
-  private_constant :WIRE_CLASSES
-
   # A registered type nothing on the wire can be, with no cast to build one:
   # the prop is unsatisfiable, so every response fails — at runtime, a long
-  # way from the registration that caused it. BigDecimal is the one people
-  # reach for (it defines neither .parse nor .load, so inference finds no
-  # codec and leaves the value untouched).
+  # way from the registration that caused it. Reaches an app's own value
+  # object, since the stdlib types people reach for (BigDecimal, Time) infer
+  # a cast; see ScalarType.
   def refuse_uncastable!(scalar, where)
     return if scalar.cast?
 
     klass = Object.const_get(scalar.type)
-    return unless klass.is_a?(Class) && WIRE_CLASSES.none? { |native| native <= klass }
+    return unless klass.is_a?(Class) && ScalarType::WIRE_CLASSES.none? { |native| native <= klass }
 
     raise GraphWeaver::Error,
       "register_scalar(#{scalar.graphql_name.inspect}, #{scalar.type}) has no cast, so nothing " \

data/lib/graph_weaver/internal/values.rb

@@ -44,6 +44,7 @@ class GraphWeaver::Internal::Values
     "Date" => :date,
     "Time" => :time,
     "DateTime" => :time,
+    "BigDecimal" => :decimal,
   }.freeze
 
   # What Codegen.scalar reports for a scalar nobody registered
@@ -113,6 +114,8 @@ class GraphWeaver::Internal::Values
     when :integer then @rng.rand(0..1_000)
     when :float then @rng.rand(0.0..1_000.0).round(2)
     when :boolean then [true, false].sample(random: @rng)
+    # the plain-notation string BigDecimal() reads and #to_s("F") writes
+    when :decimal then format("%.2f", @rng.rand(0.0..10_000.0))
     when :date then (Date.new(2020, 1, 1) + @rng.rand(0..2_000)).iso8601
     when :time then Time.at(1_600_000_000 + @rng.rand(0..100_000_000)).utc.iso8601
     when :unregistered then "#{type_name}-#{@sequence += 1}" # nobody registered it: prop is T.untyped

data/lib/graph_weaver/version.rb

@@ -1,3 +1,3 @@
 module GraphWeaver
-  VERSION = "0.6.0"
+  VERSION = "0.6.1"
 end

data/lib/graph_weaver.rb

@@ -620,20 +620,26 @@ module GraphWeaver
     # rich Ruby object (and serializes back onto the wire when used as a
     # variable):
     #
-    #      GraphWeaver.register_scalar("Money", Money, requires: "bigdecimal")
+    #      GraphWeaver.register_scalar("Decimal", BigDecimal)
+    #      GraphWeaver.register_scalar("Money", Money)
     #
     # A field typed `Money` then generates `const :price, T.nilable(Money)`
-    # and casts with `Money.parse(...)` in from_h. Pass a real class as
-    # type: and cast:/serialize: are inferred from it — .parse/#to_s, or
-    # .load/.dump — by probing the deserialize side (see ScalarType::CODECS).
-    # Override with a Symbol method name (safest — no string to misspell), a
-    # Proc(expr) => code string, or :itself to force pass-through. requires:
-    # (a String or Array) names files the generated code needs — validated,
-    # and actually required to confirm it resolves when type: is a real class.
+    # and casts with `Money.parse(...)` in from_h. Pass a real class as type:
+    # and cast:/serialize: are inferred from it: a stdlib type the library
+    # knows (BigDecimal, Date, Time) brings its own codec and require, and
+    # anything else is probed on the deserialize side — .parse/#to_s,
+    # .load/.dump, or a Kernel conversion of its name (see ScalarType).
+    # Override with a Symbol method name (safest — no string to misspell),
+    # an Array for a method with arguments ([:to_s, "F"]), a Proc(expr) =>
+    # code string, or :itself to force pass-through. requires: (a String or
+    # Array) names files the generated code needs — validated, and actually
+    # required to confirm it resolves when type: is a real class.
     # cast: is also what an untyped variable input coerces through, so a
     # variable of this scalar takes the value OR its raw input ("12.00") with
-    # no static loosening — see GraphWeaver::Coerce. Built-in scalars are
-    # pre-registered the same way, so this also overrides them.
+    # no static loosening — see GraphWeaver::Coerce. The spec's own scalars
+    # and the conventional names (ISO8601Date, ISO8601DateTime, DateTime,
+    # BigInt, JSON) are pre-registered the same way, so this also overrides
+    # them — see Codegen::BUILTIN_SCALARS and docs/scalars.md.
     #
     # A scalar registered as a class of your own is the one value the testing
     # harness can't invent — only your `cast:` knows what it accepts — so it

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graph_weaver
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Daniel Pepper