README

A Statamic addon that adds type-safe GraphQL arguments for better developer experience when using typed GraphQL clients.

The Problem

Statamic's default GraphQL schema uses String for collection names and JsonArgument for filters:

entries(collection: [String], filter: JsonArgument, ...): EntryInterfacePagination

This means GraphQL clients like gqty, graphql-codegen, or Apollo can't provide autocomplete or type checking for these arguments.

The Solution

This addon replaces the collection argument with a dynamically generated CollectionName enum based on your actual collections:

enum CollectionName {
  ARTICLES
  PAGES
  # ... auto-generated from your collections
}

entries(collection: [CollectionName], ...): EntryInterfacePagination

Features

• Dynamically generates CollectionName enum from your Statamic collections
• Overrides the default entry and entries queries to use the typed enum
• Generates per-field enums for select, radio, and button group fields from their blueprint options
• Zero configuration required - just install and regenerate your client types

Installation

composer require segbedji/graphql-typed

Usage

After installing, regenerate your GraphQL client types. The collection argument will now be typed as CollectionName enum instead of String.

Before (untyped)

query.entries({ collection: ['articles'] }) // 'articles' is just a string, no validation

After (typed)

query.entries({ collection: [CollectionName.ARTICLES] }) // Type-safe enum value

Select Field Enums

Statamic types every select, radio, and button group field as a generic LabeledValue whose value is a plain String. This addon replaces each of those fields with a per-field type whose value is an enum generated from the blueprint options:

enum Updates_Update_TagEnum {
  NEW
  IMPROVEMENT
  FIX
  FREE_TOOL
}

type Updates_Update_TagLabeledValue {
  value: Updates_Update_TagEnum
  label: String
}

Typed clients then infer the option union, so entry.tag.value is 'NEW' | 'IMPROVEMENT' | 'FIX' | 'FREE_TOOL' instead of string. Note that GraphQL serializes enum output as the enum name (FREE_TOOL), not the raw option value (free-tool).

Fields are left untouched (keeping the generic LabeledValue) when they can't be represented as an enum: cast_booleans selects, fields without options, and options whose sanitized names collide (e.g. free-tool and free_tool).

How It Works

The addon registers:

1. CollectionNameEnum - A GraphQL enum type that dynamically generates values from Collection::all()
2. TypedEntryQuery - Extends the default EntryQuery but uses the CollectionName enum for the collection argument
3. TypedEntriesQuery - Extends the default EntriesQuery but uses the CollectionName enum for the collection argument
4. SelectFieldTypeGenerator - Walks every GraphQL-enabled collection's blueprints and overrides select-like fields with per-field enum types

Future Improvements

• Add typed sort options based on available fields
• Typed enums for select fields nested inside Bard, Replicator, and Grid sets