lighthouse-graphql 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eec6f789caae61cc196024238623ebc042783884cf8ebb53b19bb0e3f6d2cf3f
-  data.tar.gz: 61bdd5cef3df0d2c4ac9701501576c96a9c207d81b5f2f976d22e5fee14df9ba
+  metadata.gz: 504295e8c73043df4b45703bb304b02205a40298e5bc686eb7d3b93dd678478e
+  data.tar.gz: f5e1bc31e13856b2f636978eaed1c8d00c5fe6246bba46f4fad513d8ee247dfc
 SHA512:
-  metadata.gz: 11c76fea28a691e29eea4910674585891907cefbeef72e9efc7519b8f812cd26f39d6895c90a46c91259b53c0dc64e3a0437add651d9eed07e5cd74807f245f2
-  data.tar.gz: 530507331c8736355448b67e1cf6ac354a0745351038fc9e7f8535df47f30299e2cf4ea203bee15482bc3fbcf3b8f9d0e5d7e72c61f263f0d9759016ae210a10
+  metadata.gz: 5aa2a3bcb218dc305b68cbb0d2ac1b437fdcd801a0965bc0e9c69de994b8028febb7c6a46fe2edff8e4b39d386b94369a63d603f6899fe1b9065d1a7196fd750
+  data.tar.gz: 1dd8ef4b1426c9c4555a087da98aaee17cdbbf3133bd375ee6e2d83e738a4911d5e091545b7b65a3262bf823a8bd7f5e034943cf2124077a9d54c42930ee0b7a

data/CHANGELOG.md

@@ -6,6 +6,17 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-10-18
+
+### Added
+
+- **`lighthouse:install` on graphql-ruby's Relay** (`--relay`, its default) writes `node(id:)`
+  and `nodes(ids:)` in the starter `graphql/schema.graphql`, with `interface Node` and a
+  `User @node` whose ids are global (`id: ID! @globalId`, `user(id: ID! @globalId(decode: ID) @eq)`).
+  Graphql-ruby's `field :node` / `field :nodes` move out of `Types::QueryType`, whose
+  `#node` / `#nodes` methods resolve the SDL's fields. This happens only when the schema file
+  does not exist yet. An install without Relay writes the starter schema as before.
+
 ## [0.7.0] - 2026-10-18
 
 The schema is written by PHP Lighthouse's rules now: one entrypoint that imports
@@ -670,7 +681,8 @@ had been running inside a private monorepo as a path gem before being extracted.
 - Config-driven extension seams: `Lighthouse.configure`, `resolver_namespaces`,
   `on_error`, and `DirectiveRegistry.register` for app-defined directives.
 
-[Unreleased]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.7.0...HEAD
+[Unreleased]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.7.1...HEAD
+[0.7.1]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.7.0...v0.7.1
 [0.7.0]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.4.0...v0.5.0

data/docs/generators.md

@@ -32,7 +32,7 @@ And it adds Lighthouse's own:
 | File | What it is |
 | --- | --- |
 | `config/initializers/lighthouse.rb` | Every [configuration](configuration.md) option, commented out |
-| `graphql/schema.graphql` | A starter schema, unless the folder holds `.graphql` files already |
+| `graphql/schema.graphql` | A starter schema, unless the file exists. With graphql-ruby's Relay (`--relay`, its default), it declares `Query.node` and `nodes`, `interface Node`, and a `User @node` with global ids, and `Types::QueryType`'s `field :node` / `:nodes` go: its `#node` / `#nodes` resolve the SDL's |
 | `graphql.config.yml` | IDE configuration, and `.gitignore` entries for the [IDE helper](getting-started.md#ide-support) files |
 | `app/graphql/subscriptions/base_subscription.rb` | With `--subscriptions` only: graphql-ruby has no subscription base. It includes `Lighthouse::GraphQL::Subscription` |
 | `config/routes.rb` | `post "/graphql", to: "graphql#execute"`, when missing |

data/docs/getting-started.md

@@ -37,7 +37,7 @@ graphql-ruby wrote, and adds Lighthouse's own:
 | `app/graphql/types/base_*.rb`, `resolvers/base_resolver.rb`, `mutations/base_mutation.rb` | graphql-ruby's base classes. `BaseObject`, `BaseInterface`, `BaseUnion` and `BaseScalar` include `Lighthouse::GraphQL::Type` |
 | `app/controllers/graphql_controller.rb` | graphql-ruby's controller, replaced by one including `Lighthouse::GraphQL::Controller` |
 | `config/initializers/lighthouse.rb` | Every [configuration](configuration.md) option, commented out at its default |
-| `graphql/schema.graphql` | The schema's entrypoint: a starter schema (`user` via `@find`, `users` via `@paginate`) that assumes a `User` model. Skipped when the file exists |
+| `graphql/schema.graphql` | The schema's entrypoint: a starter schema (`user` via `@find`, `users` via `@paginate`) that assumes a `User` model. With graphql-ruby's Relay, also `node(id:)` and `nodes(ids:)` (see [relay.md](relay.md#relay-through-graphql-ruby)). Skipped when the file exists |
 | `graphql.config.yml` | IDE configuration — see [IDE support](#ide-support) |
 
 `--schema=ApiSchema`, `--schema-path=app/schema/schema.graphql`, `--subscriptions`,

data/docs/relay.md

@@ -160,9 +160,58 @@ directives then work on them. The schema has one kind of global id and one `Node
   `ID` gives its id, and `ARRAY` / `TYPE` its class name (`["Tag", 1]`, `"Tag"`).
 - `node:` is the SDL's `Node` interface: `interface Node`, which `@node` adds, and
   `implements Node` refer to `Types::NodeType`. A `@node` type implements it.
-- `Query.node` and `nodes` are graphql-ruby's code-first fields of
-  `Types::QueryType`, which find objects with `object_from_id`. The `node` field
-  `@node` would add to `Query` gives way to them.
+- `Query.node` and `nodes` find objects with `object_from_id`, through the
+  `#node` and `#nodes` methods of `Types::QueryType`. `lighthouse:install`
+  declares both fields in the starter `graphql/schema.graphql`, and removes the
+  `field :node` / `field :nodes` that graphql-ruby wrote in `Types::QueryType`,
+  so the SDL is where they are declared. An SDL field without a resolving
+  directive resolves with the root type class's method of its name. If the
+  fields stay in `Types::QueryType` instead, they are part of the schema too, and
+  the `node` field `@node` would add to `Query` gives way to them.
+
+The starter schema `lighthouse:install` writes on graphql-ruby's Relay:
+
+```graphql
+type Query {
+  "Fetches an object given its ID. Resolved by Types::QueryType#node, with AppSchema.object_from_id."
+  node("ID of the object." id: ID!): Node
+
+  "Fetches a list of objects given a list of IDs. Resolved by Types::QueryType#nodes."
+  nodes("IDs of the objects." ids: [ID!]!): [Node]
+
+  user(id: ID! @globalId(decode: ID) @eq): User @find
+  users: [User!]! @paginate(defaultCount: 10)
+}
+
+interface Node {
+  "ID of the object."
+  id: ID!
+}
+
+type User @node {
+  id: ID! @globalId
+  name: String
+  email: String
+}
+```
+
+```ruby
+module Types
+  class QueryType < Types::BaseObject
+    # Query.node and nodes are declared in graphql/schema.graphql; these methods resolve them.
+    def node(id:)
+      context.schema.object_from_id(id, context)
+    end
+
+    def nodes(ids:)
+      ids.map { |id| context.schema.object_from_id(id, context) }
+    end
+  end
+end
+```
+
+`lighthouse:install` writes this only when the app has no schema file yet, and
+only on the `node` / `nodes` fields as graphql-ruby writes them.
 
 ```graphql
 type Tag @node {

data/lib/generators/lighthouse/install/graphql_ruby_install.rb

@@ -26,6 +26,10 @@ module Lighthouse::Generators::GraphqlRubyInstall
   # The example field graphql-ruby's install puts in each root type.
   TEST_FIELD = /\n+[ \t]*# TODO: remove me\n[ \t]*field :test_field,.*?\n[ \t]*def test_field\n.*?\n[ \t]*end\n/m
 
+  # The `node` and `nodes` fields graphql-ruby's install (--relay, its default)
+  # puts in Types::QueryType, without the methods that resolve them.
+  RELAY_FIELDS = /^[ \t]*field :nodes?, \[?Types::NodeType\b.*? do\n(?:[ \t]*argument .*\n)*[ \t]*end\n\n?/
+
   # The `resolve_type` stub graphql-ruby's install puts in the schema class.
   RESOLVE_TYPE_STUB = /
     \n+[ \t]*\#\ Union\ and\ Interface\ Resolution\n
@@ -98,6 +102,16 @@ module Lighthouse::Generators::GraphqlRubyInstall
     options[:subscriptions] || exist?(File.join(directory, 'subscriptions', 'base_subscription.rb'))
   end
 
+  # Did graphql-ruby's install write Relay's side (--relay, its default):
+  # Types::NodeType, and Types::QueryType's node and nodes, as it writes them?
+  def relay?
+    query_type = types_path('query_type.rb')
+    return false unless exist?(types_path('node_type.rb')) && exist?(query_type)
+
+    source = read(query_type)
+    source.scan(RELAY_FIELDS).size == 2 && source.include?('def node(id:)') && source.include?('def nodes(ids:)')
+  end
+
   def graphql_ruby_controller?(source)
     source.include?('def prepare_variables(variables_param)') && source.include?('def handle_error_in_development(e)') &&
       source.include?("#{schema_name}.execute(query, variables: variables, context: context, operation_name: operation_name)")

data/lib/generators/lighthouse/install/install_generator.rb

@@ -21,6 +21,9 @@ require_relative 'graphql_ruby_install'
 #   graphql-ruby's and stays, but the `resolve_type` stub (Lighthouse resolves
 #   types) and the root types it is built on;
 # - the example `test_field` goes from the root types;
+# - with Relay, the starter SDL declares Query.node and nodes (and a User
+#   @node with global ids), so their `field`s go from Types::QueryType, whose
+#   #node / #nodes methods resolve the SDL's fields;
 # - graphql-ruby's base object, interface, union and scalar include
 #   Lighthouse::GraphQL::Type, so every type class (Types::QueryType,
 #   Types::NodeType, what `graphql:object` writes) is Lighthouse's;
@@ -76,6 +79,7 @@ class Lighthouse::Generators::InstallGenerator < Rails::Generators::Base
       return
     end
 
+    @relay_starter = relay?
     template 'schema.graphql.tt', sdl_schema_path
   end
 
@@ -101,12 +105,15 @@ class Lighthouse::Generators::InstallGenerator < Rails::Generators::Base
     add_dataloader if source.include?('use GraphQL::Batch') && source.exclude?('use GraphQL::Dataloader')
   end
 
-  # The example field goes; the root types' own fields stay.
+  # The example field goes; the root types' own fields stay. With Relay, the
+  # starter SDL declares Query.node and nodes, so their `field`s go too, and
+  # the methods graphql-ruby wrote resolve the SDL's fields.
   def adapt_root_types
     %w[query_type mutation_type subscription_type].each do |name|
       path = types_path("#{name}.rb")
       gsub_file path, TEST_FIELD, "\n" if exist?(path) && read(path).match?(TEST_FIELD)
     end
+    move_relay_fields_to_sdl if @relay_starter
   end
 
   # Every type class is Lighthouse's: graphql-ruby's base object, interface,
@@ -223,6 +230,13 @@ class Lighthouse::Generators::InstallGenerator < Rails::Generators::Base
     sdl_schema_path == 'graphql/schema.graphql'
   end
 
+  def move_relay_fields_to_sdl
+    path = types_path('query_type.rb')
+    gsub_file path, RELAY_FIELDS, ''
+    gsub_file path, /^([ \t]*)def node\(id:\)\n/,
+              "\\1# Query.node and nodes are declared in #{sdl_schema_path}; these methods resolve them.\n\\1def node(id:)\n"
+  end
+
   def ide_helper_files
     [Lighthouse::IdeHelper::DIRECTIVES_FILE, Lighthouse::IdeHelper::PROGRAMMATIC_TYPES_FILE]
   end

data/lib/generators/lighthouse/install/templates/schema.graphql.tt

@@ -1,15 +1,44 @@
 # Starter schema generated by `rails generate lighthouse:install`. It assumes a
 # User model with `name` and `email` columns — replace it with your own types.
+# This file is the schema's entrypoint: split the schema into files it imports
+# (#import user.graphql), which add their fields with `extend type Query`.
 # Directives reference: https://github.com/Vaz-Innovation/lighthouse-graphql/blob/main/docs/directives.md
 
 "Indicates what fields are available at the top level of a query operation."
 type Query {
+<% if relay? -%>
+  "Fetches an object given its ID. Resolved by Types::QueryType#node, with <%= schema_name %>.object_from_id."
+  node("ID of the object." id: ID!): Node
+
+  "Fetches a list of objects given a list of IDs. Resolved by Types::QueryType#nodes."
+  nodes("IDs of the objects." ids: [ID!]!): [Node]
+
+  "Find a single user by its global id."
+  user(id: ID! @globalId(decode: ID) @eq): User @find
+<% else -%>
   "Find a single user by id."
   user(id: ID! @eq): User @find
+<% end -%>
 
   "List users, a page at a time (10 by default; pass first: and page:)."
   users: [User!]! @paginate(defaultCount: 10)
 }
+<% if relay? -%>
+
+"An object with an ID: graphql-ruby's Types::NodeType."
+interface Node {
+  "ID of the object."
+  id: ID!
+}
+
+"Account of a person who uses this application. @node makes it a Node, which Query.node finds."
+type User @node {
+  "Its global id, from <%= schema_name %>.id_from_object (Rails' GlobalID)."
+  id: ID! @globalId
+  name: String
+  email: String
+}
+<% else -%>
 
 "Account of a person who uses this application."
 type User {
@@ -17,3 +46,4 @@ type User {
   name: String
   email: String
 }
+<% end -%>

data/lib/lighthouse/graphql/version.rb

@@ -2,6 +2,6 @@
 
 module Lighthouse
   module GraphQL
-    VERSION = '0.7.0'
+    VERSION = '0.7.1'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lighthouse-graphql
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Vaz Innovation