Feature Proposal: Configurable Cursor Type for Federated Graph Compatibility

[anthonycastiglia-toast]

Problem

ElasticGraph uses a Cursor scalar type for pagination fields (more expressive than String), but this creates incompatibility when composing federated supergraphs. Most GraphQL tooling follows the Relay spec literally, using String for cursor fields. Federation composition fails with:

Type of field PageInfo.startCursor is incompatible across subgraphs:
it has type String in subgraphs [...] but type Cursor in subgraph elasticgraph

Attempting to override the cursor type with type_name_overrides: { Cursor: "String" } causes a collision with the built-in String scalar:

ElasticGraph::Errors::SchemaError: Duplicate definition for type String detected. Each type can only be defined once. (ElasticGraph::Errors::SchemaError)

Proposed Solution

Add an optional cursor_type configuration option to control the GraphQL type used for all cursor fields:

ElasticGraph::SchemaDefinition::RakeTasks.new(
  # ...
  cursor_type: "String" # Optional: defaults to "Cursor" if omitted
)

Options:

• Parameter omitted or cursor_type: "Cursor" (default): Uses the Cursor scalar type
• cursor_type: "String": Uses built-in String scalar, enabling federation compatibility

This applies to: PageInfo.startCursor/endCursor, Edge.cursor, and before/after pagination arguments.

Compatibility notes:

• Omitting the cursor_type option preserves the current behavior, using the Cursor scalar type, so this change is backwards-compatible for existing projects.
• This change does not affect the wire format: Cursor is semantically identical to String (base64-encoded opaque string). This only affects the GraphQL schema type.

Implementation Overview

Code Changes

Thread cursor_type parameter through the schema definition pipeline:

• RakeTasks → API → State → BuiltInTypes, Factory, and Field
• Replace hardcoded "Cursor" strings with the configurable value in PageInfo, Edge, and pagination arguments
• Conditionally skip Cursor scalar registration when cursor_type == "String"
• Validate that cursor_type is either "Cursor" or "String"

Tests

• Verify both cursor_type modes generate correct schema artifacts
• Test validation for invalid values
• Regenerate Apollo federation artifacts

Documentation

• Add federation compatibility section to elasticgraph-apollo/README.md
• Document cursor_type parameter in schema customization guide
• Add YARD documentation to RakeTasks
• Create code examples for site documentation

References

• Relay Cursor Connections Specification - particularly the PageInfo specification which defines cursor fields as String
• Apollo Federation Subgraph Specification

[myronmarston]

There's already an open issue for this: #1028. Let's discuss further there.