# `TypedGql.TypeGenerator`
[🔗](https://github.com/fahchen/typed_gql/blob/v0.11.0/lib/typed_gql/type_generator.ex#L1)

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.

# `option`

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

# `generate`

```elixir
@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`

```elixir
@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`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*