[graphql] Add @typespec/graphql emitter

[FionaBronwen]

Summary

This PR introduces @typespec/graphql, a new emitter that generates GraphQL SDL (Schema Definition Language) from TypeSpec definitions.

Features

• Schema generation: Emit complete GraphQL schemas from TypeSpec models and operations
• Operation types: Support for @query, @mutation, and @subscription decorators
• Interface composition: Use @Interface and @compose for GraphQL interface inheritance
  patterns
• Visibility filtering: Automatic input/output type generation based on @visibility decorators
• Custom scalars: @specifiedBy decorator for custom scalar URL specifications
• Schema customization: @schema decorator for multi-schema scenarios

Architecture

The emitter uses a two-phase approach:

1. Mutation phase: Transforms TypeSpec types into GraphQL-compatible structures using the mutator framework, handling visibility filtering, naming conventions, and type deduplication
2. Render phase: Uses @alloy-js/graphql components to emit the final SDL output

Example

import "@typespec/graphql";

using TypeSpec.GraphQL;

@query
op getUser(@path id: string): User;

@mutation
op createUser(input: User): User;

model User {
  id: string;
  name: string;
  email: string;
}

Generates:

  type Query {
    getUser(id: String!): User!
  }

  type Mutation {
    createUser(input: UserInput!): User!
  }

  type User {
    id: String!
    name: String!
    email: String!
  }

  input UserInput {
    name: String!
    email: String!
  }

Test plan

• Unit tests for all decorators and components (318 tests passing)
• E2E tests covering schema generation scenarios
• Mutation engine tests for type transformation logic

Notes

• This emitter depends on @alloy-js/graphql which is pending publication
• Tracked in GitHub issue GraphQL Emitter Design #4933

[timotheeguerin]

The way those decorators are implemented kinda goes against the philosphy of those decorators(shouldn't really have to check the .decorators list unless there is a feature gap in the compiler)

Any reason to do that over using the stateMap/stateSet(and potentially as mentioned in another comment the upcomming auto decorators?)

[FionaBronwen]

The @nullable decorator is applied programmatically by the mutation engine after stripping | null variants from unions. (In GraphQL, unions don't have null variants, they just become null themselves.) We check .decorators rather than stateMap because we need the state to travel with cloned types. stateMap entries point to the original type objects and would be lost after cloning during mutation. Keeping this information alongside the cloned type via a decorator, enables mutation engine chaining where each mutation phase can work on the transformed output of the previous one and still contain the nullability context.

Since auto decorators #10197 use stateMap I think we'd run into the same issue. Happy to discuss if there's a better pattern that still allows us to chain together mutation stages without auxiliary data to pass around!

[timotheeguerin]

hhm so I think this expose a different issue then, when you clone a type it should clone the decorators and run them and in turn updating the state map.

My guess here is that in the mutation you are not actually calling finishType on the type.(You need to do that to make sure the decorators run) It has been a common mistake when writing emitters

[FionaBronwen]

I took a closer look at finishType, and I want to clarify our use case since it's a bit different from the scenario you're describing.

The mutator-framework does call finishType on cloned types, so I don't think that's the issue.

The key difference is that we're not trying to preserve stateMap entries from the original type. We're programmatically injecting metadata during mutation. The flow is like this:

1. User writes a union T | null in TSP (no @nullable decorator in source TSP)
2. Mutation engine unwraps the union to T and calls setNullable(type) to mark it
3. Downstream mutation engines/emitters check isNullable(type) to emit the correct nullability

Since the decorator wasn't in the original source, there's nothing for finishType to re-run. We're using the decorators array as a portable metadata container — the decorator function reference ($nullable) is just a unique identifier, and the function itself is intentionally a no-op.

This pattern gives us a simple contract for multi-stage mutation pipelines: metadata travels with the type object itself, no shared stateMap infrastructure needed between stages.

I know this isn't perhaps the intended decorator usage, but it seemed like the cleanest way to transport information between mutation engines without auxiliary data structures. If there is a different mechanism for this, please let me know!

[timotheeguerin]

/azp run typespec - pr tools

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/microsoft/typespec/@typespec/graphql@11000

commit: 954e220

[github-actions]

❌ There is undocummented changes. Run chronus add to add a changeset or click here.

The following packages have changes but are not documented.

• ❌@typespec/graphql

Show changes

[timotheeguerin]

how common is this decorator going to be used? It is a bit unfortunate that we'll have to escape all usages, i see why it was called Interface, other options maybe

@iface

[FionaBronwen]

Interfaces are a core feature that I would expect to come up a fair amount. So yeah, totally agree about the escaping. Maybe @graphqlInterface is better? Updated to try that out.