Add mutation engine for TypeSpec-to-GraphQL type transformation by FionaBronwen · Pull Request #62 · pinterest/typespec

FionaBronwen · 2026-02-23T19:09:55Z

This PR introduces a mutation engine that bridges the gap between TypeSpec's type system and
GraphQL's naming/structural constraints. It builds on @typespec/mutator-framework to apply
GraphQL-specific transformations to TypeSpec types before they're emitted as SDL.

What this does

TypeSpec and GraphQL have different conventions and rules around type naming and structure. For
example:

TypeSpec uses camelCase for properties, GraphQL enum values use SCREAMING_SNAKE_CASE
TypeSpec allows unions of scalars, but GraphQL unions can only contain object types
TypeSpec template instantiations like List<string> need readable names like ListOfString

The mutation engine handles these transformations by defining per-type mutation classes that hook
into the mutator framework's traversal:

Enum/EnumMember — Sanitizes names to PascalCase (types) and SCREAMING_SNAKE_CASE (values)
Model/ModelProperty — Sanitizes model and property names for GraphQL compatibility
Operation — Normalizes operation names; automatically propagates input context to parameters and
output context to return types
Scalar — Maps TypeSpec scalars to their GraphQL equivalents via a scalar mapping table
Union — Detects nullable unions (T | null) and flattens them; wraps scalar variants in synthetic
object types (since GraphQL unions only allow object members)

Input/output type context splitting

GraphQL distinguishes between input types (used in operation arguments) and output types (used in
return values). The mutation engine handles this via GraphQLMutationOptions, which overrides the
framework's mutationKey to produce separate cached mutations per context ("input" vs "output").

When an operation is mutated, GraphQLOperationMutation overrides mutateParameters() and
mutateReturnType() to inject the appropriate context. The framework's built-in options propagation
carries that context to all nested types automatically.

Also included

src/lib/type-utils.ts — Shared utilities for name sanitization (toTypeName, toFieldName,
sanitizeNameForGraphQL), nullable union detection, template name generation, and splitWithAcronyms
for handling acronyms in casing conversions
src/lib/scalar-mappings.ts — Complete mapping table from TypeSpec scalars to GraphQL scalar types
(including int64 → BigInt, float32 → Float, custom scalar specs, etc.)
56 tests across type-utils (35) and mutation engine (21)
Package hygiene: tspMain, node engine bump to >=20, api-extractor.json, consistent casing in test
helpers

Testing

npx vitest run

packages/graphql/src/lib/interface.ts

packages/graphql/src/lib/scalar-mappings.ts

packages/graphql/src/mutation-engine/mutations/union.ts

packages/graphql/src/mutation-engine/mutations/enum-member.ts

packages/graphql/src/lib/scalar-mappings.ts

packages/graphql/src/mutation-engine/mutations/scalar.ts

packages/graphql/src/mutation-engine/mutations/union.ts

packages/graphql/src/lib/scalar-mappings.ts

packages/graphql/src/mutation-engine/mutations/union.ts

packages/graphql/src/lib/type-utils.ts

packages/graphql/tspconfig.yaml

packages/graphql/CHANGELOG.md

packages/graphql/test/test-host.ts

packages/graphql/src/mutation-engine/mutations/union.ts

packages/graphql/src/mutation-engine/mutations/model.ts

packages/graphql/src/lib/type-utils.ts

packages/graphql/src/mutation-engine/engine.ts

## Summary Adds utility functions for transforming TypeSpec names into valid GraphQL identifiers. These utilities form the foundation for name handling throughout the GraphQL emitter. ## Changes - **`src/lib/type-utils.ts`** - Core utility functions for GraphQL name transformations - **`test/lib/type-utils.test.ts`** - Unit tests for `sanitizeNameForGraphQL` ## Utilities Added | Function | Purpose | |----------|---------| | `sanitizeNameForGraphQL` | Sanitize names to be valid GraphQL identifiers | | `toTypeName` | Convert to PascalCase for type names | | `toFieldName` | Convert to camelCase for field names | | `toEnumMemberName` | Convert to CONSTANT_CASE for enum members | | `getUnionName` | Generate names for anonymous unions | | `getTemplatedModelName` | Generate names for templated models (e.g., `ListOfString`) | | `isArray`, `isRecordType` | Type guards for array/record models | | `unwrapModel`, `unwrapType` | Extract element types from arrays | | `isTrueModel` | Check if a model should emit as GraphQL object type | | `getGraphQLDoc` | Extract doc comments for GraphQL descriptions |

Introduce a mutation engine that transforms TypeSpec types into GraphQL-compatible forms using the mutator framework. Includes mutations for enums, models, scalars, unions, and operations. Also includes package hygiene: add tspMain, update node engine to >=20, add api-extractor.json, CHANGELOG.md, fix testing casing, and clean up dead code.

Operations automatically propagate input context to parameters and output context to return types via GraphQLMutationOptions. The framework's cache and options propagation handle nested types, so the same source model produces separate input and output mutations without any custom type-graph walking.

Co-authored-by: Steve Rice <srice@pinterest.com>

Use scalars.graphql.org hosted specs per review feedback: - PlainDate → andimarek/local-date - PlainTime → apollographql/localtime-v0.1 - BigDecimal (decimal, decimal128) → chillicream/decimal

packages/graphql/src/lib/one-of.ts

packages/graphql/src/lib/scalar-mappings.ts

packages/graphql/lib/specified-by.tsp

packages/graphql/src/lib/type-utils.ts

steverice · 2026-03-17T18:06:26Z

packages/graphql/src/lib/type-utils.ts

+  const name = getTypeName(model, {});
+  const baseName = toTypeName(name.replace(/<[^>]*>/g, ""));


This always made me sad. There must be a better way to do this.

packages/graphql/src/mutation-engine/mutations/union.ts

Co-authored-by: Steve Rice <srice@pinterest.com>

FionaBronwen force-pushed the fionabronwen/graphql-mutation-engine-v2 branch from 0dda7d3 to 4964137 Compare February 23, 2026 21:45

FionaBronwen force-pushed the fionabronwen/graphql-package-hygiene branch from 0f7b9e1 to 139f961 Compare February 23, 2026 21:45

FionaBronwen changed the base branch from fionabronwen/graphql-package-hygiene to feature/graphql February 25, 2026 21:27

FionaBronwen force-pushed the fionabronwen/graphql-mutation-engine-v2 branch 5 times, most recently from a05a236 to 79ea773 Compare February 26, 2026 16:15

FionaBronwen marked this pull request as ready for review February 26, 2026 16:17

FionaBronwen requested review from steverice and swatkatz as code owners February 26, 2026 16:17

FionaBronwen removed the request for review from swatkatz February 26, 2026 16:17

steverice reviewed Feb 26, 2026

View reviewed changes

steverice reviewed Feb 27, 2026

View reviewed changes

packages/graphql/src/lib/type-utils.ts Outdated Show resolved Hide resolved

packages/graphql/src/mutation-engine/engine.ts Outdated Show resolved Hide resolved

packages/graphql/src/mutation-engine/engine.ts Outdated Show resolved Hide resolved

FionaBronwen and others added 14 commits March 13, 2026 14:28

cleanup

d33cf89

Update packages/graphql/src/lib/scalar-mappings.ts

3ce6f3e

Co-authored-by: Steve Rice <srice@pinterest.com>

Update packages/graphql/src/lib/scalar-mappings.ts

4fa1453

Co-authored-by: Steve Rice <srice@pinterest.com>

Update packages/graphql/src/lib/scalar-mappings.ts

ecbe290

Co-authored-by: Steve Rice <srice@pinterest.com>

Update packages/graphql/src/lib/scalar-mappings.ts

3327af6

Co-authored-by: Steve Rice <srice@pinterest.com>

Update packages/graphql/src/lib/scalar-mappings.ts

c633fe8

Co-authored-by: Steve Rice <srice@pinterest.com>

Address PR comments

a45ea01

Address additional comments

d6d55ca

Remove mutateModel variant

cf4aaa5

Update to use typekit functions

fa13554

handle scalar extends based on PR feedback

de658d1

FionaBronwen added 2 commits March 13, 2026 14:28

Handle input unions -> oneOf mutation

a6b6399

Add specificationUrls for PlainDate, PlainTime, and BigDecimal scalars

84b7764

Use scalars.graphql.org hosted specs per review feedback: - PlainDate → andimarek/local-date - PlainTime → apollographql/localtime-v0.1 - BigDecimal (decimal, decimal128) → chillicream/decimal

FionaBronwen force-pushed the feature/graphql branch from 42df8a9 to c204b15 Compare March 13, 2026 18:53

FionaBronwen force-pushed the fionabronwen/graphql-mutation-engine-v2 branch from 70e7589 to 84b7764 Compare March 13, 2026 18:53

steverice requested changes Mar 17, 2026

View reviewed changes

FionaBronwen and others added 3 commits March 19, 2026 13:30

Update packages/graphql/lib/specified-by.tsp

2bd5860

Co-authored-by: Steve Rice <srice@pinterest.com>

Address feedback, round out nullability handling

72c94c9

Carry nullability info in state map for nullable wrapper unions

1ec2c06

FionaBronwen requested a review from steverice March 20, 2026 19:36

		const name = getTypeName(model, {});
		const baseName = toTypeName(name.replace(/<[^>]*>/g, ""));

Conversation

FionaBronwen commented Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this does

Input/output type context splitting

Also included

Testing

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

steverice Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

FionaBronwen commented Feb 23, 2026 •

edited

Loading