lighthouse-graphql 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da632a31f353bc75d798a228769150a76f8cd3a0e8dce13e8bc19c363641f850
-  data.tar.gz: 6d0e92dc7818bccd89d4d9d1bc2e4905421cedd84190a0d0ae09c8ad31cb546f
+  metadata.gz: eec6f789caae61cc196024238623ebc042783884cf8ebb53b19bb0e3f6d2cf3f
+  data.tar.gz: 61bdd5cef3df0d2c4ac9701501576c96a9c207d81b5f2f976d22e5fee14df9ba
 SHA512:
-  metadata.gz: 30c076b60a32754472f1360eedc72c46b2ee518230d8ce686658f6a436f9a7d74cbcb13c24bf6a1d7dc8c05f29fba8f6ddd0d53e5614ea00ab498753340429c3
-  data.tar.gz: d558ad506a5bfebda1486cf8b62450113d0a1022f0ff458a8b040924aca458189a176cf9dbdcab95f877b571bfc18b1408109b5db36bfc128a6754df55b1bc11
+  metadata.gz: 11c76fea28a691e29eea4910674585891907cefbeef72e9efc7519b8f812cd26f39d6895c90a46c91259b53c0dc64e3a0437add651d9eed07e5cd74807f245f2
+  data.tar.gz: 530507331c8736355448b67e1cf6ac354a0745351038fc9e7f8535df47f30299e2cf4ea203bee15482bc3fbcf3b8f9d0e5d7e72c61f263f0d9759016ae210a10

data/CHANGELOG.md

@@ -6,6 +6,99 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-10-18
+
+The schema is written by PHP Lighthouse's rules now: one entrypoint that imports
+the other files, every type defined once, and `extend type` to add to it.
+`@orderBy`, `@whereConditions` and `@whereHasConditions` generate and apply what
+PHP Lighthouse's do. In development, the IDE helper files are rewritten
+automatically.
+
+**Upgrading from 0.6:**
+
+1. Replace `config.sdl_folder = ...` with `config.schema_path = Rails.root.join('graphql/schema.graphql').to_s`
+   (that is the default), and `get_schema(sdl_folder:)` with `get_schema(schema_path:)`.
+2. Import every other file from `graphql/schema.graphql`. `#import **/*.graphql` imports
+   every file below its folder, which matches what was loaded before.
+3. Turn a second `type Query { ... }` (or `type Mutation`, or any type defined in two files)
+   into `extend type Query { ... }`. A type defined twice now fails the build.
+4. Write `orderBy:` arguments as `orderBy: _ @orderBy(columns: [...])`, and drop the
+   `OrderByClause` inputs and the `SortOrder` enum you declared. `order` is required in a
+   clause, and `{ field:, direction: }` clauses are no longer accepted.
+5. `SQLOperator` has PHP Lighthouse's values. Replace `NIN` with `NOT_IN`, and
+   `CONTAINS` / `STARTS_WITH` / `ENDS_WITH` with `LIKE` and a `%` pattern
+   (`value: "%Rails%"`, `"Rails%"`, `"%Rails"`). `@where(operator:)` keeps its operators.
+6. A `HAS` condition is on the related records' columns (`…HasCondition`, a `String`
+   column), as in PHP Lighthouse, no longer on the parent's column enum.
+
+### Added
+
+- **`#import`.** The schema's entrypoint, `config.schema_path`, imports other files by a
+  path relative to the importing file. Globs (`#import blog/*.graphql`) work too. An
+  imported file can import more files, and each file is read once.
+- **Type extensions merged as PHP Lighthouse merges them.** `extend type`, `input`,
+  `interface`, `enum`, `union` and `scalar` add to their definition, and the
+  directives on their fields work as on the type's own. `extend type Query` alone
+  defines `Query`.
+- **`@orderBy` generates its types.** `orderBy: _ @orderBy(columns: [...])` gets
+  `[<Type><Field><Arg>OrderByClause!]`, a column enum (`@enum(value:)` per column)
+  and `SortOrder`. `columnsEnum:` reuses an enum, and without columns the shared
+  `OrderByClause` takes any column.
+- **`@orderBy(relations:)`.** Clients order by `COUNT` of a relation, or by
+  `AVG`/`MIN`/`MAX`/`SUM` of one of its columns
+  (`{ posts: { aggregate: COUNT }, order: DESC }`). Records without related ones
+  are ordered too, and this works on batched relationship pages.
+- **`@orderBy(column:, direction:)` on a field.** It always orders the result, after
+  the client's clauses.
+- **`@whereConditions` and `@whereHasConditions`, as in PHP Lighthouse.** They have
+  PHP Lighthouse's `SQLOperator` (`LIKE`, `NOT_LIKE`, `NOT_IN`, `BETWEEN`,
+  `NOT_BETWEEN`, ...), and `HAS` with `operator:` / `amount:`
+  (`{ relation: "posts", operator: LT, amount: 1 }`: the records with none). The
+  `…Relation` / `…HasCondition` inputs filter on the related table, and
+  `handler:` names a class that applies the conditions instead.
+- **JSON columns.** `@whereConditions`, `@whereHasConditions` and `@orderBy` take a path into a
+  JSON column, `meta->author->name` or `meta->tags->0`, on PostgreSQL, MySQL and SQLite.
+  Numbers compare and sort as numbers, booleans compare as booleans, and `IS_NULL` holds
+  for a JSON `null` too.
+- **`config.ide_helper`.** `schema-directives.graphql` and
+  `programmatic-types.graphql` are rewritten on boot and on every reload. By
+  default this happens in development when the app has a `graphql.config.yml`.
+- `Contracts::FieldBuilder`, and `Contracts::ArgManipulator` as `ASTBuilder` calls
+  it, for custom directives.
+- The guide [docs/schema-organisation.md](docs/schema-organisation.md).
+
+### Changed
+
+- **Breaking:** The schema is read from `config.schema_path` and its imports, not from every
+  file in `config.sdl_folder`, which is removed. `lighthouse:install` takes `--schema-path`
+  instead of `--sdl-folder`.
+- **Breaking:** A type defined twice fails the build: "Duplicate definition X found when parsing
+  the schema", pointing at `extend`. PHP Lighthouse keeps the last definition.
+- **Breaking:** An argument typed `_` that no directive replaces fails the build. It used to
+  become a scalar.
+- **Breaking:** `@orderBy` clauses need `order`, take only `{ column:, order: }`, and a
+  column outside an enum must be an identifier.
+- **Breaking:** `SQLOperator`'s values are PHP Lighthouse's (see above).
+- **Breaking:** `@builder` and `@whereAuth` on a field apply after the argument directives,
+  as PHP Lighthouse's field builder directives do. An `order` a builder adds now breaks the
+  ties of the client's `orderBy` instead of preceding it. They also apply on relationship
+  fields (`@hasMany`, ...), where they used to be ignored, and on `@aggregate`, which now
+  gets the argument directives too.
+
+### Fixed
+
+- A schema that stops building while you edit it keeps its `programmatic-types.graphql`.
+  If there is none yet, the file declares the `_` placeholder alone, so the IDE never
+  reports `Unknown type "_"`. When an import is missing, the IDE helper reads every
+  `.graphql` file in the folder, as the IDE does.
+- `programmatic-types.graphql` no longer repeats the types `schema-directives.graphql`
+  defines (`Mixed`, `CanAction`, `PaginateType`, ...). graphql-js, which the VS Code
+  and JetBrains GraphQL plugins use, rejected the schema.
+- `@whereConditions` applied only to an argument named `where`. It and `@whereHasConditions`
+  are argument directives like the others now: any name, in SDL order.
+- An error in a `@whereConditions` value (an unknown relation or operator) is the client's
+  error. It used to be swallowed and leave the query unfiltered.
+
 ## [0.6.0] - 2026-10-18
 
 Lighthouse now uses what the Rails app and graphql-ruby already have instead of settings and
@@ -577,7 +670,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.6.0...HEAD
+[Unreleased]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.7.0...HEAD
+[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
 [0.4.0]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.3.0...v0.4.0

data/README.md

@@ -87,23 +87,31 @@ and scalar include `Lighthouse::GraphQL::Type`; the controller serves the schema
 through `Lighthouse::GraphQL::Controller`. It adds the initializer, a starter schema
 in `graphql/schema.graphql` and a `graphql.config.yml` for your IDE. Run
 `bin/rails generate lighthouse:install --help` for its options (`--schema`,
-`--sdl-folder`, `--subscriptions`, `--skip-controller`, `--skip-ide`), and see
+`--schema-path`, `--subscriptions`, `--skip-controller`, `--skip-ide`), and see
 [docs/generators.md](docs/generators.md) for every generator, graphql-ruby's included.
 
+### Schema files
+
+As in PHP Lighthouse, the schema is read from one entrypoint,
+`graphql/schema.graphql`, which `#import`s the other files
+(`#import user.graphql`, `#import blog/*.graphql`). A type is defined once, and the
+other files add to it with `extend type Query`. See
+[docs/schema-organisation.md](docs/schema-organisation.md).
+
 ### IDE support
 
 Lighthouse's directives and the types it generates (Paginator/Connection types,
-`whereConditions` inputs, …) are defined in Ruby, so your IDE can't see them in
-your `.graphql` files. Write them out for it:
+`@whereConditions` and `@orderBy` inputs, the `_` placeholder, …) are defined in
+Ruby, so your IDE can't see them in your `.graphql` files. Lighthouse writes them
+to `schema-directives.graphql` and `programmatic-types.graphql` in the app root:
+in development on every boot and reload, or with:
 
 ```shell
 bin/rails lighthouse:ide_helper
 ```
 
-This writes `schema-directives.graphql` and `programmatic-types.graphql` to the app
-root; the generated `graphql.config.yml` already points the GraphQL plugins for
-JetBrains IDEs and VS Code at them. Rerun it after changing your schema or
-registering a directive. See [docs/getting-started.md](docs/getting-started.md#ide-support).
+The generated `graphql.config.yml` already points the GraphQL plugins for
+JetBrains IDEs and VS Code at them. See [docs/getting-started.md](docs/getting-started.md#ide-support).
 
 ## Quick start
 

data/docs/best-practices.md

@@ -92,7 +92,9 @@ app's GraphQL setup easy to find.
 
 ## Split your SDL
 
-Lighthouse concatenates every `*.graphql` file under your `sdl_folder`. Organize
-by domain (`users.graphql`, `orders.graphql`, …) and keep a small
-`_directives.graphql` only for directives you declare yourself (built-ins are
-injected automatically).
+Lighthouse reads `graphql/schema.graphql` and the files it `#import`s
+([schema-organisation.md](schema-organisation.md)). Organize
+by domain (`users.graphql`, `orders.graphql`, …), each with its types and the
+fields it adds with `extend type Query` / `extend type Mutation`. Keep a small
+`directives.graphql`, imported too, only for directives you declare yourself
+(built-ins are injected automatically).

data/docs/configuration.md

@@ -9,7 +9,7 @@ reusable and publishable.
 require 'lighthouse-graphql'
 
 Lighthouse.configure do |config|
-  config.sdl_folder = Rails.root.join('graphql').to_s
+  config.schema_path = Rails.root.join('graphql/schema.graphql').to_s
   config.namespaces = { queries: ['Resolvers'], mutations: ['Mutations'] }
   config.resolver_namespaces = ['App::Graphql']
   config.on_error = ->(error, _context) { Rails.error.report(error) }
@@ -18,11 +18,25 @@ end
 
 ## Options
 
-### `sdl_folder`
+### `schema_path`
 
-Where Lighthouse loads `*.graphql` files from. Defaults to `RAILS_ROOT/graphql`
-in a Rails app, `nil` otherwise (pass SDL explicitly via `SchemaFactory` when not
-on Rails).
+The schema's entrypoint, as PHP Lighthouse's `schema_path`. Lighthouse reads
+this file and the files it imports (`#import user.graphql`, `#import blog/*.graphql`).
+A type is defined once, and other files add to it with `extend type`. See
+[schema-organisation.md](schema-organisation.md). Defaults to
+`RAILS_ROOT/graphql/schema.graphql` in a Rails app, and `nil` otherwise. Outside
+Rails, pass the path, or the SDL itself (`SchemaFactory.build_base_schema(sdl:)`).
+
+`get_schema(schema_path: ...)` overrides it for one schema.
+
+### `ide_helper`
+
+Rewrite `schema-directives.graphql` and `programmatic-types.graphql` in the
+app's root on boot and on every reload, for the IDE
+([schema-organisation.md](schema-organisation.md#ide-support)). A file whose
+content is unchanged is left alone. `nil` (the default) turns it on in
+development when the app has a `graphql.config.yml`, which `lighthouse:install`
+writes. Set `true` or `false` to decide yourself.
 
 ### `namespaces`
 

data/docs/custom-directives.md

@@ -29,7 +29,8 @@ Include the marker module(s) your directive fulfils:
 | `Contracts::FieldResolver` | provide a field's resolver | `#define_resolver(type)` (or `#resolve_field`) |
 | `Contracts::FieldMiddleware` | wrap an existing resolver (e.g. `@auth`) | `#wrap_resolver(next)` |
 | `Contracts::FieldManipulator` | reshape the schema for a field | `manipulate_field_definition(...)` |
-| `Contracts::ArgManipulator` | reshape the schema for an argument | `manipulate_argument_definition(...)` |
+| `Contracts::ArgManipulator` | reshape the schema for an argument, as `@orderBy` and `@whereConditions` generate their types | `#manipulate_arg_definition(document_ast, field_node, type_node)` returning the argument node |
+| `Contracts::FieldBuilder` | constrain a field's query, whatever the client sends | `#handle_field_builder(relation)` |
 | `Contracts::ArgBuilder` | compose a query constraint from an argument | `#handle_builder(relation, value)` |
 
 A directive class also answers two class-level questions: its name and its SDL

data/docs/directives.md

@@ -78,7 +78,7 @@ type Query {
 ```
 
 - **The query.** It is the model's (`model:`, else the return type), narrowed by
-  `scopes:`, [`@builder`](#builder) and the field's argument filters. On a nested
+  `scopes:`, the field's argument filters and [`@builder`](#builder). On a nested
   field it pages the parent's association of the same name: `User.posts @paginate`
   pages the user's posts.
 - **`first`.** It defaults to `defaultCount`, else
@@ -456,7 +456,12 @@ Builders are looked up in their own namespace, `Builders::` (app/graphql/builder
 `class:` with `method:` (default `call`), or PHP Lighthouse's `method: "Class@method"`.
 
 On a field, the method gets `(relation, args, context)`, or the directive's
-`value:` in place of the arguments. On an argument or an input field, it gets
+`value:` in place of the arguments. As in PHP Lighthouse, a field's `@builder`
+(with `@whereAuth` and `@orderBy(column:)`) applies after the argument
+directives, in SDL order. An `order` it adds therefore breaks the ties of the
+client's `orderBy`. It applies on every field that queries records: `@all`,
+`@paginate`, `@find`, `@first`, `@count`, `@aggregate`, the relationship
+directives and `resolve_info.enhance_builder`. On an argument or an input field, it gets
 `(relation, value, context)` whenever the client sends that argument, an explicit
 `null` included, and not when it is left out:
 
@@ -518,7 +523,7 @@ Full guide: [filtering-and-ordering.md](filtering-and-ordering.md).
 | `@whereBetween` / `@whereNotBetween` | `column BETWEEN` / `NOT BETWEEN` the input's two fields, in order |
 | `@whereJsonContains` | a JSON column contains the value (every value of a list); `key: "meta->tags"` points into it |
 | `@scope(name:)` | calls the model scope with the value (`name:` defaults to the argument's) |
-| `@orderBy` | sort by one or more columns |
+| `@orderBy` | sort by the client's clauses (columns, relations' aggregates); on a field, a fixed order |
 
 ```graphql
 type Query {
@@ -526,7 +531,7 @@ type Query {
     status: String @eq
     nameSearch: String @like
     minAge: Int @where(operator: "GTE", key: "age")
-    orderBy: [OrderByClause!] @orderBy
+    orderBy: _ @orderBy(columns: ["name", "created_at"])
   ): [User!]! @all
 }
 ```
@@ -568,18 +573,71 @@ parents it would cut them all together, as PHP Lighthouse warns. PHP Lighthouse
 also allows `@limit` on the field itself, where it only marks the field the argument
 limits; it is accepted there and changes nothing.
 
+### `@orderBy`
+
+```graphql
+directive @orderBy(
+  columns: [String!]               # argument: the columns the client may order by
+  columnsEnum: String              # argument: an enum of them instead (one of the two)
+  relations: [OrderByRelation!]    # argument: { relation:, columns:, columnsEnum: } to order by an aggregate
+  column: String                   # field: the column to order by
+  direction: OrderByDirection = ASC
+) on ARGUMENT_DEFINITION | FIELD_DEFINITION
+```
+
+On an argument written as `_`, Lighthouse generates the clause input
+(`<Type><Field><Arg>OrderByClause`, or `…RelationOrderByClause` with
+`relations:`) and the column enum. Without `columns:`, `columnsEnum:` or
+`relations:`, the argument takes the shared `OrderByClause`, which allows any
+column. A column can be a JSON path, `meta->rank`, in `@orderBy` and in
+`@whereConditions` ([JSON columns](filtering-and-ordering.md#json-columns)). On a field, `@orderBy(column:, direction:)` orders the result after
+the client's clauses.
+
+```graphql
+type Query {
+  posts(orderBy: _ @orderBy(columns: ["posted_at", "title"])): [Post!]! @all
+  users(orderBy: _ @orderBy(relations: [{ relation: "posts" }])): [User!]! @all
+  latestPosts: [Post!]! @all @orderBy(column: "posted_at", direction: DESC)
+}
+
+# { posts(orderBy: [{ column: POSTED_AT, order: DESC }]) { title } }
+# { users(orderBy: [{ posts: { aggregate: COUNT }, order: DESC }]) { name } }
+```
+
+Guide: [filtering-and-ordering.md](filtering-and-ordering.md#ordering).
+
 ### `@whereConditions` / `@whereHasConditions`
 
-Give clients a structured, dynamic `WHERE` builder (AND/OR/operators, and HAS for
-related records). Lighthouse generates the input and enum types for you. See
-[filtering-and-ordering.md](filtering-and-ordering.md#complex-where-conditions).
+```graphql
+directive @whereConditions(columns: [String!], columnsEnum: String, handler: String) on ARGUMENT_DEFINITION
+directive @whereHasConditions(relation: String, columns: [String!], columnsEnum: String, handler: String) on ARGUMENT_DEFINITION
+```
+
+These give clients a dynamic `WHERE` builder, with conditions joined by `AND`
+and `OR`, PHP Lighthouse's `SQLOperator` operators, and `HAS` checks on
+relations. On an argument written as `_`, Lighthouse generates the input
+(`<Type><Field><Arg>WhereConditions` / `…WhereHasConditions`), its `…Relation`
+and `…HasCondition` inputs, and the column enum. Without `columns:` or
+`columnsEnum:`, the argument takes the shared `WhereConditions`, which allows
+any column.
+
+`@whereHasConditions` keeps the records with a related record matching the
+conditions. The relation is `relation:`, or the argument's name without `has`.
+`handler:` names a `Builders::` class whose `call(relation, conditions)` applies
+the conditions instead.
 
 ```graphql
 type Query {
   people(where: _ @whereConditions(columns: ["age", "type"])): [Person!]! @all
+  users(hasPosts: _ @whereHasConditions(columns: ["title"])): [User!]! @all
 }
+
+# { people(where: { AND: [{ column: AGE, operator: GT, value: 37 }, { column: TYPE, value: "Actor" }] }) { name } }
+# { users(hasPosts: { column: TITLE, operator: LIKE, value: "%Rails%" }) { name } }
 ```
 
+Guide: [filtering-and-ordering.md](filtering-and-ordering.md#complex-where-conditions).
+
 ### `@trim`, `@hash`, `@drop`, `@bind` and `@upload`
 
 Rewrite an argument's or input field's value before the field resolves, in the

data/docs/federation.md

@@ -29,7 +29,7 @@ class Types::BaseObject < GraphQL::Schema::Object
 end
 
 BaseAppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
-  sdl_folder: Rails.root.join('graphql').to_s,
+  schema_path: Rails.root.join('graphql/schema.graphql').to_s,
   options: { federation: true, base_types: { object: Types::BaseObject, resolver: Resolvers::BaseResolver } }
 )