lighthouse-graphql 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3be850a4eb57c4d4fc6bd41103d5bb783482530f3fc0f3584aa00314de4e936
-  data.tar.gz: 75ae5604d85d1549f159dc17a98932d7c4274074ea26b9a9ade38b4f8d8d6af6
+  metadata.gz: 44b6e89e140483d01ad4cb9c945cfc29d6f025e05798ed4e5e11868060b86885
+  data.tar.gz: cac88d1820f171e4cbe6dfaa51b737c405cacf6ec3c08ed4ce8694eb2039aa18
 SHA512:
-  metadata.gz: 62cafecf9c4deae7b974747a9de82c422ea1d58d50fa752d6c583fba20f6ff16b99db56496a9963d0740826803b89e730c3ede19fed937baf22fac7f954bd826
-  data.tar.gz: fcd638c332e4f055afb9b28e7ac211162582878e578e5cb45c02a7d24dcf2ae70f7dd5342cdd477bc1f8a16b3cc1e6dd78e487791ee396044fefbe7aa95bea49
+  metadata.gz: b70da4e82689cc2808b00c514f4de0eafb60fedcff45d6f0fa28b560bc3dbe502e6d3b4c0a7615d33065f95fa82fc756332added5dd9f2ba9396ef6b38ff79ce
+  data.tar.gz: 8a30bc33a00599f3302196e3e24c881be56a68f94026ae1c0ab64246afa7b2114f6e723fba4f203fe51be03661bc6351f65fc12e3d4827624a6e04a2798b53fd

data/CHANGELOG.md

@@ -6,6 +6,80 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-17
+
+### Added
+
+- `Lighthouse::GraphQL::Controller`, a Rails controller concern: `include` it, name the schema
+  with `lighthouse_schema AppSchema`, and its `execute` action runs the operation through
+  persisted queries, batches a JSON array body, reads the variables, sets the Cache-Control
+  header and renders the result. Its private hooks (`graphql_context`, `graphql_variables`,
+  `graphql_schema`) adjust it, and `lighthouse_request { }` gives an action of your own the
+  request events. The generated `GraphqlController` and the example app now use it.
+- Events, as PHP Lighthouse dispatches them (`docs/events.md`): `Lighthouse::Events.listen`
+  for `StartRequest`, `StartOperationOrOperations`, `BuildSchemaString` (its listeners return SDL to add),
+  `RegisterDirectiveNamespaces` (its listeners return namespaces of directive classes to register), `ManipulateAST`,
+  `StartExecution`, `BuildExtensionsResponse` (its listeners return an `ExtensionsResponse` for the result's
+  `extensions`), `ManipulateResult`, `EndExecution`, `EndOperationOrOperations`, `EndRequest`
+  and `ValidateSchema`. Each one is also instrumented through `ActiveSupport::Notifications`
+  as `<event>.lighthouse`.
+- `@event(dispatch:)` dispatches an event class, constructed with the field's resolved value,
+  once the field resolves. Event classes are looked up in `Config.namespaces[:events]` (`Events`).
+- `PersistedQueries.multiplex` runs a batch of operations.
+- `bin/rails lighthouse:validate_schema` dispatches `ValidateSchema` and builds every type.
+- `@feature(name:, when:)` shows a field or object type only while a feature flag is in that
+  state, checked per query through graphql-ruby's visibility. It uses Flipper by default;
+  `Config.feature_checker` and `Config.feature_actor` change that.
+- `@convertEmptyStringsToNull` on an argument, input field or field, or on every field with
+  `Config.convert_empty_strings_to_null`, turns incoming `""` into `null`.
+- Soft deletes: `@softDeletes` adds a `trashed: Trashed @trashed` argument (`ONLY`, `WITH`,
+  `WITHOUT`), and `@restore` and `@forceDelete` restore or permanently delete the soft-deleted models
+  their filters select. They work with paranoia, discard or a plain `deleted_at` column,
+  detected per model, or with an adapter set in `Config.soft_deletes`.
+- `@withoutGlobalScopes(names:)` lifts a model's default scope conditions when the client passes
+  `true`. Each name is a `without_<name>` scope or a column.
+- Subscriptions (`docs/subscriptions.md`), on graphql-ruby's subscriptions: `Subscription`
+  fields resolve to plain `GraphQL::Schema::Subscription` classes in `Subscriptions::` by convention,
+  or to the class `@subscription(class:)` names, or work with no class at all.
+  `@broadcast(subscription:, shouldQueue:)` triggers a subscription once a mutation succeeds,
+  inline or in an ActiveJob (`Config.queue_broadcasts`, `Config.broadcast_queue`), with the class's
+  `self.trigger_arguments(root, context)` and `trigger_scope`; a plain class with required arguments
+  and no `trigger_arguments` (which could never reach a subscriber) is reported as a
+  `Lighthouse::DefinitionError`. The optional concern `Lighthouse::GraphQL::Subscription` adds PHP
+  Lighthouse's `authorize?`, `filter?` and `resolve_payload` hooks. `rails generate lighthouse:subscription`
+  writes a `GraphQL::Schema::Subscription` (`--lighthouse` to include the concern). The example app
+  has real ActionCable subscriptions (`GraphqlChannel`) with channel and end-to-end delivery specs.
+- The initializer `rails generate lighthouse:install` writes lists the new settings, and
+  `docs/custom-directives.md` shows registering a namespace of directives through
+  `RegisterDirectiveNamespaces`.
+
+### Fixed
+
+- Schemas using `@cacheControl` (or `@feature`) build on graphql 2.5 again. Their arguments
+  with a default are now nullable (`maxAge: Int = 0`, not `Int! = 0`), because graphql 2.5 does not
+  fill in a directive argument's default and so refused every usage that left one out. CI now
+  also runs the suite on graphql 2.5.
+
+## [0.2.1] - 2026-10-17
+
+### Added
+
+- RBS signatures in `sig/`, shipped with the gem, for the parts an app implements or calls:
+  `Lighthouse::_Builder` (what a `@builder` class answers) and `_Validator`, every
+  `Lighthouse::Config` setting with the callables it takes (`_ErrorHandler`, `_UserReader`,
+  `_Authorizer`), the directive extension points (`DirectiveRegistry`, the contracts,
+  `BaseDirectiveResolver`, `Directives::Arguments::Base`), the entrypoints (`get_schema`,
+  `SchemaFactory`, `PersistedQueries`, `CacheControl`, `SchemaCache`, `IdeHelper`) and the
+  errors. `rbs collection` (and so Steep) loads them from the installed gem, as it does for any
+  gem that ships `sig/`; nothing changes at runtime.
+  CI validates them and runs the suite with every Lighthouse method checked against its
+  signature, so they cannot drift from the code.
+- A documentation site, built from `docs/` with VuePress as PHP Lighthouse builds its own,
+  and published to GitHub Pages on every push to `main`:
+  <https://vaz-innovation.github.io/lighthouse-graphql/>.
+- `docs/motivation.md`: where Lighthouse comes from, why the schema comes first, and why
+  directives work so well on Active Record — and when something else fits better.
+
 ## [0.2.0] - 2026-10-17
 
 ### Added
@@ -208,7 +282,9 @@ 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.2.0...HEAD
+[Unreleased]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.2.1...v0.3.0
+[0.2.1]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/Vaz-Innovation/lighthouse-graphql/releases/tag/v0.1.0

data/README.md

@@ -39,7 +39,14 @@ paginate, walk a relationship, or read an attribute. Lighthouse — like its PHP
 inspiration — captures those patterns as **directives** you attach in the schema,
 and falls back to a sensible default reader for plain fields. You write Ruby only
 for the genuinely custom parts (`@field(resolver: "...")`), and your schema stays
-the single source of truth.
+the single source of truth. [Motivation](docs/motivation.md) explains the idea in depth.
+
+The same directives reach the rest of an API, too:
+- real-time updates: `Subscription` fields on graphql-ruby's subscriptions, triggered
+  by a mutation's `@broadcast`;
+- soft deletes (`@softDeletes`, `@restore`, `@forceDelete`) and feature flags (`@feature`);
+- request lifecycle [events](docs/events.md);
+- a controller concern that serves the schema in a few lines.
 
 ### Inspirations
 
@@ -62,6 +69,8 @@ gem 'lighthouse-graphql'
 
 It depends on `graphql ~> 2.5` and `activesupport`. For federation you also need
 `apollo-federation` in your app (it is an optional, app-provided dependency).
+On graphql 2.5, keep the `json` gem below 3: graphql 2.5 calls `JSON.generate`
+with an option json 3 removed (graphql 2.6 no longer does).
 
 Then let the generator set the app up:
 
@@ -142,8 +151,12 @@ are the library's end-to-end suite. See [example/README.md](example/README.md).
 
 ## Documentation
 
+**Read it at [vaz-innovation.github.io/lighthouse-graphql](https://vaz-innovation.github.io/lighthouse-graphql/)**,
+or as Markdown in [`docs/`](docs):
+
 | Guide | What it covers |
 | --- | --- |
+| [Motivation](docs/motivation.md) | Where Lighthouse comes from, why the schema comes first, and why directives fit Active Record |
 | [Getting started](docs/getting-started.md) | Install, base types, building & serving the schema |
 | [Directives reference](docs/directives.md) | Every built-in directive, grouped by purpose |
 | [Relationships](docs/relationships.md) | `@hasMany`, `@belongsTo`, `@belongsToMany`, `@hasOne`, the `@morph*` variants, batching and `type:` pagination |
@@ -153,6 +166,8 @@ are the library's end-to-end suite. See [example/README.md](example/README.md).
 | [Validation](docs/validation.md) | Model validations, `@validator` with Dry::Validation contracts |
 | [Authentication & authorization](docs/authorization.md) | `@guard`, `@canFind` / `@canModel` / `@canQuery` / `@canResolved` / `@canRoot` (Pundit by default) |
 | [Performance at scale](docs/performance.md) | Opt-in schema cache, SDL reloading in development, persisted queries (APQ) and trusted-document allowlists |
+| [Events](docs/events.md) | Request, schema-build and execution events, `@event`, the controller concern |
+| [Subscriptions](docs/subscriptions.md) | `Subscription` fields, `@subscription`, `@broadcast`, filtering and queued broadcasts |
 | [Caching](docs/caching.md) | `@cache`, `@cacheKey`, `@clearCache` (Rails.cache), `@cacheControl` (HTTP) |
 | [Apollo Federation](docs/federation.md) | `@key`, `resolve_reference`, the `ReferenceResolver` registry |
 | [Custom directives](docs/custom-directives.md) | The contracts, the registry, writing your own directive |

data/docs/caching.md

@@ -99,7 +99,7 @@ Each cached read costs one `read_multi` for the tokens.
 ## `@cacheControl`
 
 ```graphql
-directive @cacheControl(maxAge: Int! = 0, scope: CacheControlScope! = PUBLIC, inheritMaxAge: Boolean! = false)
+directive @cacheControl(maxAge: Int = 0, scope: CacheControlScope = PUBLIC, inheritMaxAge: Boolean = false)
   on FIELD_DEFINITION | OBJECT | INTERFACE | UNION
 ```
 

data/docs/configuration.md

@@ -35,6 +35,8 @@ different contracts, so they live apart ([resolvers.md](resolvers.md)):
 | `mutations` | `['Mutations']` | `GraphQL::Schema::Mutation` classes for `Mutation` fields |
 | `builders` | `['Builders']` | `@builder` classes |
 | `validators` | `['Validators']` | `@validator` contracts |
+| `events` | `['Events']` | Classes `@event(dispatch:)` names ([events.md](events.md)) |
+| `subscriptions` | `['Subscriptions']` | `GraphQL::Schema::Subscription` classes (optionally including `Lighthouse::GraphQL::Subscription`) for `Subscription` fields, and `@subscription(class:)` ([subscriptions.md](subscriptions.md)) |
 
 ```ruby
 config.namespaces = { queries: ['Api::Queries'] }   # the other kinds keep their defaults
@@ -100,17 +102,83 @@ config.persisted_queries_manifest = Rails.root.join('persisted-queries.json')  #
 config.persisted_queries_only = Rails.env.production?  # run nothing else
 ```
 
+### `convert_empty_strings_to_null`
+
+Makes every field behave as if it carried
+[`@convertEmptyStringsToNull`](directives.md#convertemptystringstonull): empty
+strings sent for nullable inputs arrive as `nil`, non-null inputs unchanged.
+Defaults to `false`. It is read when the schema is built, so set it in the
+initializer.
+
+```ruby
+config.convert_empty_strings_to_null = true
+```
+
+### `queue_broadcasts`, `broadcast_queue`
+
+Whether [`@broadcast`](directives.md#broadcast) triggers its subscription in an
+ActiveJob (`Lighthouse::GraphQL::BroadcastJob`, needs the `activejob` gem)
+instead of inside the mutation's request, and the queue it goes to. A directive's
+`shouldQueue:` overrides `queue_broadcasts`. Defaults: `false`, and `nil` (the
+default queue of ActiveJob). See [subscriptions.md](subscriptions.md#queueing).
+
+```ruby
+config.queue_broadcasts = true
+config.broadcast_queue = :subscriptions
+```
+
 ### `transactional_mutations`
 
 Whether `@create` / `@update` / `@createMany` / `@updateMany` run in a database
 transaction. Defaults to `true`.
 
+### `soft_deletes`
+
+What "trashed" means, for `@softDeletes`, `@trashed`, `@restore`, `@forceDelete`
+and `@withoutGlobalScopes`. By default each model is inspected: paranoia
+(`acts_as_paranoid`), then discard (`Discard::Model`), then a `deleted_at` column.
+Set it for another column, or a scheme of your own:
+
+```ruby
+# Another column, for models without a gem:
+config.soft_deletes = Lighthouse::Support::SoftDeletes::Column.new(:archived_at)
+
+# Any object answering these (relations in, relations out; records in, truthy out):
+class SoftDeleteAdapter
+  def soft_deletes?(model) = model.include?(Archivable)
+  def only_trashed(relation) = relation.unscope(where: :archived_at).where.not(archived_at: nil)
+  def with_trashed(relation) = relation.unscope(where: :archived_at)
+  def without_trashed(relation) = relation.unscope(where: :archived_at).where(archived_at: nil)
+  def restore(record) = record.unarchive
+  def force_delete(record) = record.destroy
+end
+config.soft_deletes = SoftDeleteAdapter.new
+```
+
+See [Soft deletes & global scopes](directives.md#soft-deletes-global-scopes).
+
 ### `authenticated_user`, `policy_user`, `authorizer`
 
 The authentication and authorization seams behind `@guard` and the `@can*`
 family. The authorizer is `->(user, record, ability, args = [])`, Pundit by
 default. See [authorization.md](authorization.md#configuration).
 
+### `feature_checker`, `feature_actor`
+
+The seams behind [`@feature`](directives.md#feature). The checker is
+`->(name, actor, ctx) { true/false }`, called with the feature's name as written
+in the SDL; by default it asks Flipper, `Flipper.enabled?(name.to_sym, actor)`,
+and raises a clear error when Flipper is not loaded. The actor is
+`->(ctx) { actor }`; by default it is the authenticated user (a Flipper actor
+answers `flipper_id`), and `nil` checks the feature globally.
+
+```ruby
+Lighthouse.configure do |config|
+  config.feature_actor = ->(ctx) { ctx[:current_account] }
+  config.feature_checker = ->(name, account, _ctx) { account&.features&.include?(name) }
+end
+```
+
 ## Extending the registry
 
 Register app-defined directives (see [custom-directives.md](custom-directives.md))

data/docs/custom-directives.md

@@ -109,7 +109,17 @@ Lighthouse::DirectiveRegistry.register(App::Graphql::Directives::StartsWith)
 Lighthouse::DirectiveRegistry.register(App::Graphql::Directives::UpcaseDirective)
 ```
 
-It is now usable in your SDL — no other changes:
+To register every directive in a namespace at once, as PHP Lighthouse locates
+directives by namespace, listen to the
+[`RegisterDirectiveNamespaces`](events.md) event. Each class there with a
+`directive_name` that is a resolver or an argument builder gets registered when
+the schema is built:
+
+```ruby
+Lighthouse::Events.listen(Lighthouse::Events::RegisterDirectiveNamespaces) { 'App::Graphql::Directives' }
+```
+
+Either way, it is now usable in your SDL — no other changes:
 
 ```graphql
 type Query {

data/docs/directives.md

@@ -318,6 +318,33 @@ type Query {
 }
 ```
 
+### `@convertEmptyStringsToNull`
+
+Replaces incoming empty strings `""` with `null`, before any resolver sees them —
+directive resolvers (`@create`, `@all` filters, …), `@field`, `Queries::` /
+`Mutations::` classes and `@validator` alike. On an argument or an input field it
+converts that one input; on a field it converts every input of the field, nested
+input objects and lists included. Non-null inputs (`String!`) pass unchanged when
+the directive is only on the field: placing it on the non-null argument or input
+field itself forces the conversion.
+
+```graphql
+type Mutation {
+  createPost(title: String @convertEmptyStringsToNull, body: String): Post! @create
+  signUp(input: SignUpInput!): User! @create @convertEmptyStringsToNull
+}
+
+input SignUpInput {
+  name: String          # "" becomes null on signUp, but not where no directive applies
+  nickname: String @convertEmptyStringsToNull   # on every field taking SignUpInput
+  email: String!        # unchanged; add the directive here to force it
+}
+```
+
+A directive on an input field applies wherever the input type is used; one on a
+field affects only that field. To enable it for every field, set
+[`convert_empty_strings_to_null`](configuration.md#convert_empty_strings_to_null).
+
 ---
 
 ## Mutation directives
@@ -342,6 +369,197 @@ See [mutations.md](mutations.md).
 
 ---
 
+## Soft deletes & global scopes
+
+Rails has no built-in soft deletes or named global scopes, so these directives
+work with what Rails apps use. Lighthouse detects, per model, in this order:
+
+1. **[paranoia](https://github.com/rubysherpas/paranoia)** (`acts_as_paranoid`):
+   a default scope hides trashed records.
+2. **[discard](https://github.com/jhawthorn/discard)** (`include Discard::Model`):
+   nothing is hidden, unless the model adds `default_scope -> { kept }`.
+3. **A plain `deleted_at` column**, with no gem (a default scope is optional).
+
+An app with its own scheme, or another column, sets
+[`Config.soft_deletes`](configuration.md#soft_deletes). A model that matches none
+of them is an error when a client uses one of these directives on it
+(`Model Widget does not support soft deletes …`).
+
+### `@softDeletes`
+
+Lets clients filter trashed records. It adds the argument
+`trashed: Trashed @trashed` to the field and defines the `Trashed` enum once
+(unless your schema declares its own).
+
+```graphql
+type Query {
+  tasks: [Task!]! @all @softDeletes
+}
+```
+
+becomes
+
+```graphql
+type Query {
+  tasks(trashed: Trashed @trashed): [Task!]! @all
+}
+
+"Specify if you want to include or exclude trashed results from a query."
+enum Trashed {
+  "Only return trashed results."
+  ONLY
+  "Return both trashed and non-trashed results."
+  WITH
+  "Only return non-trashed results."
+  WITHOUT
+}
+```
+
+### `@trashed`
+
+The argument builder `@softDeletes` adds; use it by hand to name the argument
+yourself. It works wherever argument filters do: `@all`, `@paginate`, `@find`,
+`@first`, `@count` and the relationship directives (`@hasMany`, …, including
+paginated ones, which keep batching through the Dataloader).
+
+```graphql
+type Query {
+  flights(trashed: Trashed @trashed, destination: String @eq): [Flight!]! @all
+}
+type Post {
+  comments(trashed: Trashed @trashed): [Comment!]! @hasMany
+}
+```
+
+| Value | Result |
+| --- | --- |
+| `ONLY` | only trashed records |
+| `WITH` | trashed and non-trashed records |
+| `WITHOUT` | only non-trashed records |
+| *(omitted)* | **the model's own behaviour, untouched**: paranoia and a default scope hide trashed records, a bare `deleted_at` column or discard without a default scope show everything |
+
+`ONLY`, `WITH` and `WITHOUT` lift the model's default scope on the soft-delete
+column first, so they behave the same whatever the model does by default. That
+is `unscope(where: column)`, which removes every condition on that column from
+the query, including one added by an argument declared before `trashed`. Avoid a
+separate filter on the soft-delete column itself.
+
+### `@forceDelete`
+
+Permanently removes one or more soft deleted models. It works like
+[`@delete`](mutations.md#delete): the filter arguments (`@whereKey`, `@eq`, …) are
+required (`Would modify all models, use an argument to filter.`), the removed
+models are returned (a list for a list field, else the first or `null`), and
+`model:` and `scopes:` are honoured. It finds trashed models even when the model
+hides them by default, and it removes live ones too. It runs in a transaction
+(`Config.transactional_mutations`).
+
+```graphql
+type Mutation {
+  forceDeletePost(id: ID! @whereKey): Post @forceDelete
+  forceDeletePosts(ids: [ID!]! @whereKey): [Post!]! @forceDelete
+}
+```
+
+paranoia models are removed with `really_destroy!`, discard and `deleted_at`
+models with `destroy`. A model whose callbacks refuse is reported as
+`Could not modify model Post with ID 1.`
+
+### `@restore`
+
+Un-deletes one or more soft deleted models, with the same arguments, guard and
+result as `@forceDelete`: paranoia's `restore`, discard's `undiscard`, or setting
+the `deleted_at` column to `NULL`.
+
+```graphql
+type Mutation {
+  restorePost(id: ID! @whereKey): Post @restore
+}
+```
+
+### `@withoutGlobalScopes`
+
+Omits global scopes from the query when the client passes `true`. Use it on a
+`Boolean` argument; `false` and an omitted argument leave the scopes in place.
+
+```graphql
+type Query {
+  posts(includeUnscheduled: Boolean @withoutGlobalScopes(names: ["scheduled"])): [Post!]! @all
+}
+```
+
+ActiveRecord has one anonymous `default_scope`, not scopes with names, so each
+name is resolved like this (snake_cased; a trailing `Scope` is optional):
+
+1. A model scope **`without_<name>`**, if the model has one. You write it:
+   `scope :without_scheduled, -> { unscope(where: :schedule_at) }`.
+2. Else a **column** of that name: `unscope(where: column)`. Like `@trashed`, this
+   removes every condition on that column from the query, including ones added by
+   earlier arguments.
+3. Else a soft-delete name (`softDeletes`, `SoftDeletingScope`): trashed records
+   are included, as with `trashed: WITH`.
+
+Any other name is an error: `Cannot omit the global scope …`.
+
+---
+
+## Subscriptions
+
+Fields of the `Subscription` type resolve to a `Subscriptions::` class by
+convention, like queries and mutations: a plain graphql-ruby
+`GraphQL::Schema::Subscription` (`authorized?`, `subscribe`, `update`, ...).
+`@subscription` names another one, and `@broadcast` triggers a subscription from
+a mutation. The backend (ActionCable, ...) is the schema's; see
+[subscriptions.md](subscriptions.md).
+
+### `@subscription`
+
+```graphql
+directive @subscription(class: String!) on FIELD_DEFINITION
+```
+
+Names the class a `Subscription` field resolves to, when it does not follow the
+convention (`postUpdated` → `Subscriptions::PostUpdated`). The class inherits from
+`GraphQL::Schema::Subscription` (which may `include Lighthouse::GraphQL::Subscription`,
+the optional concern with PHP Lighthouse's `filter?` hooks) and is looked up in
+`Config.namespaces[:subscriptions]`; a name with `::` is used as it is.
+
+```graphql
+type Subscription {
+  postUpdated(author: ID!): Post @subscription(class: "Blog::PostUpdatedSubscription")
+}
+```
+
+### `@broadcast`
+
+```graphql
+directive @broadcast(subscription: String!, shouldQueue: Boolean) repeatable on FIELD_DEFINITION
+```
+
+Once the field has resolved, triggers the `subscription` field of the
+`Subscription` type with the result as its root, so its subscribers are updated,
+each passing through the class's `update` (or `filter?`). The class's
+`self.trigger_arguments(root, context)` says which subscribers' arguments the
+trigger must equal: none are needed for a field without arguments, and a plain
+class with a required argument and no `trigger_arguments` is reported as a
+`Lighthouse::DefinitionError`. A failed mutation, or a `nil` result, broadcasts
+nothing. An unknown subscription name is a
+`Lighthouse::DefinitionError` when the schema is built. `shouldQueue` performs the
+trigger in an ActiveJob; without it, `Config.queue_broadcasts` (default `false`)
+decides.
+
+```graphql
+type Mutation {
+  createPost(input: CreatePostInput! @spread): Post! @create @broadcast(subscription: "postCreated")
+  updatePost(input: UpdatePostInput! @spread): Post!
+    @update
+    @broadcast(subscription: "postUpdated", shouldQueue: false)
+    @broadcast(subscription: "postChanged")
+}
+```
+
+---
+
 ## Validation
 
 `@validator` runs a contract (Dry::Validation by default) before a field
@@ -369,6 +587,94 @@ type Query {
 
 ---
 
+## Feature flags
+
+### `@feature`
+
+Include a field or an object type in the schema depending on a feature flag,
+backed by [Flipper](https://www.flippercloud.io/docs) (PHP Lighthouse's
+`@feature` is backed by Laravel Pennant).
+
+```graphql
+type Query {
+  newCheckout: Checkout @feature(name: "new_checkout")
+  legacyCheckout: Checkout @feature(name: "new_checkout", when: INACTIVE)
+}
+
+type Beta @feature(name: "beta") {
+  id: ID!
+}
+```
+
+| Argument | Meaning |
+| --- | --- |
+| `name: String!` | The feature to check. |
+| `when: FeatureState = ACTIVE` | The state the feature must be in for the element to be included: `ACTIVE` or `INACTIVE`. |
+
+Feature flags depend on who asks, while the schema is built once, so the element
+stays in the schema and is hidden **per query**, through graphql-ruby's
+[visibility](https://graphql-ruby.org/authorization/visibility.html). A hidden
+field or type disappears from introspection, and a query selecting it fails
+validation (`Field 'newCheckout' doesn't exist on type 'Query'`). The fields
+returning a hidden type are hidden with it. `to_definition` prints the schema as
+the features stand for no actor.
+
+Each feature is checked at most once per query. By default Flipper is asked
+whether the feature is enabled for the authenticated user (`Flipper.enabled?(:new_checkout, user)`;
+the user answers `flipper_id`, which Flipper's ActiveRecord integration adds to
+models); with no user, the global gate decides. Flipper is optional: add
+`gem "flipper"` to your Gemfile, or configure your own check with
+`feature_checker` and `feature_actor` (see [configuration.md](configuration.md#feature_checker-feature_actor)).
+
+```ruby
+Flipper.enable_actor(:new_checkout, User.find(1))
+
+# schema.execute(query, context: { current_user: user })
+```
+
+---
+
+## Events
+
+`@event` dispatches an event once the field has resolved. The class is built with
+the resolved value and handed to `Lighthouse::Events.dispatch`; the value is
+returned unchanged, and nothing is dispatched when the field raises. It is
+repeatable: each `@event` dispatches its own. See [events.md](events.md) for
+listening, and for the events Lighthouse itself dispatches.
+
+```graphql
+directive @event(dispatch: String!) repeatable on FIELD_DEFINITION
+```
+
+```graphql
+type Mutation {
+  shipOrder(id: ID!): Order!
+    @update
+    @event(dispatch: "OrderShipped")
+    @event(dispatch: "Billing::InvoiceDue")
+}
+```
+
+```ruby
+class OrderShipped
+  attr_reader :order
+
+  def initialize(order) = @order = order
+end
+
+Lighthouse::Events.listen(OrderShipped) { |event| Mailer.shipped(event.order).deliver_later }
+```
+
+The class is looked up in `Config.namespaces[:events]` (default `['Events']`,
+so `Events::OrderShipped`, then `::OrderShipped`); a name with `::` is used
+as-is. A name that finds no class fails the schema build with
+`Lighthouse::DefinitionError`. `@event` runs inside `@guard`, `@can*`,
+`@validator` and `@cache`: a rejected request, or a cache hit, dispatches
+nothing. (`@canResolved` checks the resolved value, so there the event is
+dispatched before the check.)
+
+---
+
 ## Adding your own
 
 Every directive above is a small class registered with