Add @alloy-js/graphql language bindings backed by graphql-js#358
Open
steverice wants to merge 1 commit intoalloy-framework:mainfrom
Open
Add @alloy-js/graphql language bindings backed by graphql-js#358steverice wants to merge 1 commit intoalloy-framework:mainfrom
@alloy-js/graphql language bindings backed by graphql-js#358steverice wants to merge 1 commit intoalloy-framework:mainfrom
Conversation
Introduce a new `@alloy-js/graphql` package that lets Alloy build GraphQL schemas via JSX components or STC helpers and emits a `GraphQLSchema` from `graphql-js`. The package defines a dedicated schema state + build/validation pipeline instead of the binder model, keeping the API aligned with GraphQL’s single global namespace and explicit naming semantics. Identity is based on `name`/`namekey` only—no refkeys or rename tracking—so changes to names are explicit and breaking by design. Key capabilities included in this package: - Component API for schema constructs (`Schema`, `ObjectType`, `InterfaceType`, `UnionType`, `InputObjectType`, `EnumType`, `ScalarType`) plus `Field`, `Argument`, `InputValue`, and directives, with list/tagged child slot helpers to enforce valid component usage and nested list composition. - Relay-friendly helpers (`Field.Connection`, `Connection.Edge`, `Connection.PageInfo`, `Connection.Fields`) that generate connection and edge types, add pagination arguments, and enforce Relay schema rules when the Relay policy is selected. - GraphQL-specific name policy system (`defaultNamePolicy`, `relayNamePolicy`, `createGraphQLNamePolicy`) with optional formatters and regex rules for conventions, while always enforcing GraphQL hard requirements (spec name regex, reserved `__` prefix, reserved enum values). `namekey` can bypass convention rules but still must satisfy GraphQL validity, and string type references are normalized through the active policy. - Built-in names and helpers for GraphQL scalars and Relay types (`Node`, `PageInfo`), plus root type helpers (`Query`, `Mutation`, `Subscription`) and directive application by `name` or `namekey`. Supporting work rounds out the package with a README and API Extractor config, `tsconfig`/`vitest` setup, and extensive test coverage. Snapshot fixtures exercise real-world schemas (Star Wars, SpaceX, etc.) while targeted tests cover build behavior, schema definitions, directives, naming policies, connection behavior, and Relay validation rules. Docs tooling is updated to include the new `graphql` package in API docs and to normalize declaration references during generation, and changelog entries plus lockfile updates capture the new workspace package.
Contributor
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Introduce a new
@alloy-js/graphqlpackage that lets Alloy build GraphQL schemas via JSX components or STC helpers and emits aGraphQLSchemafromgraphql-js. The package defines a dedicated schema state + build/validation pipeline instead of the binder model, keeping the API aligned with GraphQL’s single global namespace and explicit naming semantics. Identity is based onname/namekeyonly—no refkeys or rename tracking—so changes to names are explicit and breaking by design.Key capabilities included in this package:
Schema,ObjectType,InterfaceType,UnionType,InputObjectType,EnumType,ScalarType) plusField,Argument,InputValue, and directives, with list/tagged child slot helpers to enforce valid component usage and nested list composition.Field.Connection,Connection.Edge,Connection.PageInfo,Connection.Fields) that generate connection and edge types, add pagination arguments, and enforce Relay schema rules when the Relay policy is selected.defaultNamePolicy,relayNamePolicy,createGraphQLNamePolicy) with optional formatters and regex rules for conventions, while always enforcing GraphQL hard requirements (spec name regex, reserved__prefix, reserved enum values).namekeycan bypass convention rules but still must satisfy GraphQL validity, and string type references are normalized through the active policy.Node,PageInfo), plus root type helpers (Query,Mutation,Subscription) and directive application bynameornamekey.Supporting work rounds out the package with a README and API Extractor config,
tsconfig/vitestsetup, and extensive test coverage. Snapshot fixtures exercise real-world schemas (Star Wars, SpaceX, etc.) while targeted tests cover build behavior, schema definitions, directives, naming policies, connection behavior, and Relay validation rules.Docs tooling is updated to include the new
graphqlpackage in API docs and to normalize declaration references during generation, and changelog entries plus lockfile updates capture the new workspace package.If this is your first exposure to the GraphQL bindings, please see the README for important notes and design decisions.