TypedGql.TypeGenerator (typedGql v0.11.0)

Copy Markdown View Source

Generates EctoTypedSchema embedded schema modules from GraphQL query AST.

Given an operation definition and a schema, generates per-query output type modules with proper nesting, nullability, and field alias support.

Generation pipeline

Generation runs as four named steps. Lifecycle plugins (TypedGql.Generation.Plugin) hook the first three via after_normalize, after_resolve, and after_lower (plus before_normalize for the raw entry); the terminal create step compiles modules and is not hookable:

  1. normalize — raw selections to canonical selections: expands fragment spreads, flattens inline fragments on object types, and propagates ancestor (inline-fragment / fragment-spread) directives down onto each field's directives.
  2. resolve — canonical selections + schema to a TypedGql.Generation.Schema tree. The whole tree is built before any lowering.
  3. lower — tree to {module, quoted_ast} pairs.
  4. create — {module, ast} pairs to BEAM modules.

TypedGql always runs its built-in plugins (currently TypedGql.Generation.Plugins.SkipInclude for @include/@skip) before any user plugins supplied via the :generation_plugins option.

Naming convention

Output types follow per-query path naming under a Result namespace:

ClientModule.FunctionName.Result.FieldName.NestedField...

Field aliases override both struct field names and module path segments.

Union/Interface support

When a field's type is a union or interface, inline fragments determine which concrete types to generate. Shared fields (outside fragments) are merged into each concrete type's struct. A parameterized TypedGql.Types.Union Ecto Type handles __typename-based dispatch during deserialization.

Summary

Types

option()

Functions

generate(operation, schema, opts)

Generates embedded schema modules for an operation's output types.

generate_fragment(fragment, schema, client_module, scalar_types, generation_plugins \\ [])

Generates an embedded schema module for a named fragment under ClientModule.Fragments.FragmentName.

Types

option()

@type option() ::
  {:client_module, module()}
  | {:function_name, atom()}
  | {:scalar_types, map()}
  | {:fragments, map()}
  | {:generation_plugins, [module()]}

Functions

generate(operation, schema, opts)

@spec generate(TypedGql.Language.OperationDefinition.t(), TypedGql.Schema.t(), [
  option()
]) :: [module()]

Generates embedded schema modules for an operation's output types.

Returns a list of generated module names.

Options

  • :client_module — the parent client module (e.g., MyApp.UserService)
  • :function_name — the defgql function name (e.g., :get_user)
  • :scalar_types — custom scalar type mappings (default: %{})
  • :fragments — named fragment entries for spread expansion (default: %{})
  • :generation_plugins — user TypedGql.Generation.Plugin modules, appended after the built-in plugins (default: [])

generate_fragment(fragment, schema, client_module, scalar_types, generation_plugins \\ [])

@spec generate_fragment(
  TypedGql.Language.Fragment.t(),
  TypedGql.Schema.t(),
  module(),
  map(),
  [module()]
) ::
  module()

Generates an embedded schema module for a named fragment under ClientModule.Fragments.FragmentName.