feat: make @defer/@stream directives opt-in

Move @defer and @stream directives from core built-ins to a new
opt-in module Absinthe.Type.BuiltIns.IncrementalDirectives.

Since @defer/@stream are draft-spec features (not yet finalized),
users must now explicitly opt-in by adding:

    import_types Absinthe.Type.BuiltIns.IncrementalDirectives

to their schema definition.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: jwaldrip

CHANGELOG.md

@@ -6,6 +6,7 @@
 
 * **draft-spec:** Add `@defer` and `@stream` directives for incremental delivery ([#1377](https://github.com/absinthe-graphql/absinthe/pull/1377))
   - **Note:** These directives are still in draft/RFC stage and not yet part of the finalized GraphQL specification
+  - **Opt-in required:** `import_types Absinthe.Type.BuiltIns.IncrementalDirectives` in your schema
   - Split GraphQL responses into initial + incremental payloads
   - Configure via `Absinthe.Pipeline.Incremental.enable/2`
   - Resource limits (max concurrent streams, memory, duration)

guides/incremental-delivery.md

@@ -29,6 +29,25 @@ def deps do
 end
 ```
 
+## Schema Setup
+
+Since `@defer` and `@stream` are draft-spec features, you must explicitly opt-in by importing the directives in your schema:
+
+```elixir
+defmodule MyApp.Schema do
+  use Absinthe.Schema
+
+  # Import the draft-spec @defer and @stream directives
+  import_types Absinthe.Type.BuiltIns.IncrementalDirectives
+
+  query do
+    # ...
+  end
+end
+```
+
+Without this import, the `@defer` and `@stream` directives will not be available in your schema.
+
 ## Basic Usage
 
 ### The @defer Directive

lib/absinthe/type/built_ins/directives.ex

@@ -43,74 +43,4 @@ defmodule Absinthe.Type.BuiltIns.Directives do
         Blueprint.put_flag(node, :include, __MODULE__)
     end
   end
-
-  directive :defer do
-    description """
-    Directs the executor to defer this fragment spread or inline fragment, 
-    delivering it as part of a subsequent response. Used to improve latency 
-    for data that is not immediately required.
-    """
-
-    repeatable false
-
-    arg :if, :boolean, 
-      default_value: true,
-      description: "When true, fragment may be deferred. When false, fragment will not be deferred and data will be included in the initial response. Defaults to true."
-    
-    arg :label, :string,
-      description: "A unique label for this deferred fragment, used to identify it in the incremental response."
-
-    on [:fragment_spread, :inline_fragment]
-
-    expand fn
-      %{if: false}, node ->
-        # Don't defer when if: false
-        node
-
-      args, node ->
-        # Mark node for deferred execution
-        defer_config = %{
-          label: Map.get(args, :label),
-          enabled: true
-        }
-        Blueprint.put_flag(node, :defer, defer_config)
-    end
-  end
-
-  directive :stream do
-    description """
-    Directs the executor to stream list fields, delivering list items incrementally 
-    in multiple responses. Used to improve latency for large lists.
-    """
-
-    repeatable false
-
-    arg :if, :boolean,
-      default_value: true,
-      description: "When true, list field may be streamed. When false, list will not be streamed and all data will be included in the initial response. Defaults to true."
-    
-    arg :label, :string,
-      description: "A unique label for this streamed field, used to identify it in the incremental response."
-    
-    arg :initial_count, :integer,
-      default_value: 0,
-      description: "The number of list items to return in the initial response. Defaults to 0."
-
-    on [:field]
-
-    expand fn
-      %{if: false}, node ->
-        # Don't stream when if: false
-        node
-
-      args, node ->
-        # Mark node for streaming execution
-        stream_config = %{
-          label: Map.get(args, :label),
-          initial_count: Map.get(args, :initial_count, 0),
-          enabled: true
-        }
-        Blueprint.put_flag(node, :stream, stream_config)
-    end
-  end
 end

lib/absinthe/type/built_ins/incremental_directives.ex

@@ -0,0 +1,116 @@
+defmodule Absinthe.Type.BuiltIns.IncrementalDirectives do
+  @moduledoc """
+  Draft-spec incremental delivery directives: @defer and @stream.
+
+  These directives are part of the [Incremental Delivery RFC](https://github.com/graphql/graphql-spec/blob/main/rfcs/DeferStream.md)
+  and are not yet part of the finalized GraphQL specification.
+
+  ## Usage
+
+  To enable @defer and @stream in your schema, import this module:
+
+      defmodule MyApp.Schema do
+        use Absinthe.Schema
+
+        import_types Absinthe.Type.BuiltIns.IncrementalDirectives
+
+        query do
+          # ...
+        end
+      end
+
+  You will also need to enable incremental delivery in your pipeline:
+
+      pipeline_modifier = fn pipeline, _options ->
+        Absinthe.Pipeline.Incremental.enable(pipeline,
+          enabled: true,
+          enable_defer: true,
+          enable_stream: true
+        )
+      end
+
+      Absinthe.run(query, MyApp.Schema,
+        variables: variables,
+        pipeline_modifier: pipeline_modifier
+      )
+
+  ## Directives
+
+  - `@defer` - Defers execution of a fragment spread or inline fragment
+  - `@stream` - Streams list field items incrementally
+  """
+
+  use Absinthe.Schema.Notation
+
+  alias Absinthe.Blueprint
+
+  directive :defer do
+    description """
+    Directs the executor to defer this fragment spread or inline fragment,
+    delivering it as part of a subsequent response. Used to improve latency
+    for data that is not immediately required.
+    """
+
+    repeatable false
+
+    arg :if, :boolean,
+      default_value: true,
+      description: "When true, fragment may be deferred. When false, fragment will not be deferred and data will be included in the initial response. Defaults to true."
+
+    arg :label, :string,
+      description: "A unique label for this deferred fragment, used to identify it in the incremental response."
+
+    on [:fragment_spread, :inline_fragment]
+
+    expand fn
+      %{if: false}, node ->
+        # Don't defer when if: false
+        node
+
+      args, node ->
+        # Mark node for deferred execution
+        defer_config = %{
+          label: Map.get(args, :label),
+          enabled: true
+        }
+        Blueprint.put_flag(node, :defer, defer_config)
+    end
+  end
+
+  directive :stream do
+    description """
+    Directs the executor to stream list fields, delivering list items incrementally
+    in multiple responses. Used to improve latency for large lists.
+    """
+
+    repeatable false
+
+    arg :if, :boolean,
+      default_value: true,
+      description: "When true, list field may be streamed. When false, list will not be streamed and all data will be included in the initial response. Defaults to true."
+
+    arg :label, :string,
+      description: "A unique label for this streamed field, used to identify it in the incremental response."
+
+    arg :initial_count, :integer,
+      default_value: 0,
+      description: "The number of list items to return in the initial response. Defaults to 0."
+
+    on [:field]
+
+    expand fn
+      %{if: false}, node ->
+        # Don't stream when if: false
+        node
+
+      args, node ->
+        # Mark node for streaming execution
+        stream_config = %{
+          label: Map.get(args, :label),
+          initial_count: Map.get(args, :initial_count, 0),
+          enabled: true
+        }
+        Blueprint.put_flag(node, :stream, stream_config)
+    end
+  end
+end

test/absinthe/incremental/complexity_test.exs

@@ -16,6 +16,8 @@ defmodule Absinthe.Incremental.ComplexityTest do
   defmodule TestSchema do
     use Absinthe.Schema
 
+    import_types Absinthe.Type.BuiltIns.IncrementalDirectives
+
     query do
       field :user, :user do
         resolve fn _, _ -> {:ok, %{id: "1", name: "Test User"}} end

test/absinthe/incremental/defer_test.exs

@@ -14,6 +14,8 @@ defmodule Absinthe.Incremental.DeferTest do
   defmodule TestSchema do
     use Absinthe.Schema
 
+    import_types Absinthe.Type.BuiltIns.IncrementalDirectives
+
     query do
       field :user, :user do
         arg :id, non_null(:id)

test/absinthe/incremental/stream_test.exs

@@ -14,6 +14,8 @@ defmodule Absinthe.Incremental.StreamTest do
   defmodule TestSchema do
     use Absinthe.Schema
 
+    import_types Absinthe.Type.BuiltIns.IncrementalDirectives
+
     query do
       field :users, list_of(:user) do
         resolve fn _, _ ->