Repository files navigation

This is an effort to advance the Dart GraphQL ecosystem.

It consists of multiple packages and libraries centered around GraphQL AST.

The core of this project is the GraphQL parser which parses GraphQL strings into an AST. The parsed AST can then be transformed, visited and printed back to GraphQL string.

Pub	Package	Library	Description
	package:gql	ast.dart	GraphQL AST implementation with Visitor pattern and AST transformer
	package:gql	language.dart	GraphQL source parser and printer. Recognizes both operations and SDL
	package:gql	document.dart	Document and schema validation

GraphQL language enables code generation to speed up development and move document processing to build-time.

We provide code builders to generate Dart source code and file builders which easily plug into standard Dart code generation pipeline.

Ideas for future work:

• Typed resolvers for field resolution on the client or server

Pub	Package	Library	Description
	package:gql_code_builder		Various builders
	package:gql_build		File builders

To enable development of GraphQL clients, we provide type definitions used to execute GraphQL operations. They include AST-based operation, request with per operation context, and response. These types are used by the Links.

Link is the current client implementation. Link is GraphQL AST-aware request/response middleware. They can be used to build a pipeline to deduplicate requests, conditionally transform requests and responses (including the context), and eventually send the requests to the server.

Ideas for future work:

• websocket link for subscriptions
• batched request HTTP link
• retry link to handle network issues transparently
• link for client-side request resolution

Pub	Package	Library	Description
	package:gql_exec	gql_exec.dart	Implementation of types for GraphQL requests and responses
	package:gql_link	link.dart	Base for modular GraphQL execution interface
	package:gql_http_link	gql_http_link.dart	Link to execute GraphQL requests via HTTP
	package:gql_dedupe_link	gql_dedupe_link.dart	De-duplicating Link to avoid execution of identical requests
	package:gql_transform_link	gql_transform_link.dart	GQL Link to transform Requests and Responses. May be used to update context, document, variables, data, errors, etc.
	package:gql_websocket_link	gql_websocket_link.dart	GQL Link for subscriptions using websocket.
	package:gql_dio_link	gql_dio_link.dart	Similar to gql_http_link, A GQL Terminating Link to execute requests via Dio using JSON.

Pub	Package	Library	Description
	package:gql_pedantic		Lint rules used by allgql-dart/gql packages

Pub	Package	Library	Description
	package:gql_example_cli		Example usage in a CLI environment
	package:gql_example_flutter		Example usage in a Flutter environment

The goal of this project is to expand Dart GraphQL ecosystemand to build a community around this vendor-neutral implementation.

Community contributions are welcome.

This repository usesMelos to manage the monorepo and handle releases. The release process is partially automated through GitHub Actions.

The repository is organized into several package categories:

• Core packages:

  • gql: Core GraphQL package
  • gql_tristate_value
  • gql_code_builder_serializers
  • gql_code_builder

• Execution packages:

  • gql_exec
  • gql_link

• Link implementations:

  • gql_http_link
  • gql_dio_link
  • gql_websocket_link
  • gql_dedupe_link
  • gql_error_link
  • gql_transform_link

• Build packages:

  • gql_build

To get started with local development:

1. Install Melos:

   dart pub global activate melos&& dart pub get

2. Bootstrap the workspace:

   melos bootstrap

3. Run tests:

   melostest

The publish workflow is automated via GitHub Actions and triggers when:

• Changes are pushed to themaster orrelease branches AND include changes to anypubspec.yaml file
• Manually triggered through GitHub Actions UI

The automated process:

1. Validates all packages (formatting, analysis, and tests)
2. Publishes packages in dependency order:
   • Core packages first
   • Execution packages second
   • Link implementation packages third
   • Build packages last

To create a new release manually:

1. Ensure you're on the branch you want to release from (master orrelease)

2. Version the packages using one of the following commands:

   # For a patch releasemelos run bump-patch# For a minor releasemelos run bump-minor# For a major releasemelos run bump-major# For an alpha releasemelos run bump-alpha# To graduate from prerelease(alpha) to stablemelos run graduate

3. Push the changes and tags:

   git push&& git push --tags

4. The GitHub Action will automatically handle publishing to pub.dev if changes include pubspec.yaml files

• Usebump-patch for backward-compatible bug fixes
• Usebump-minor for backward-compatible features
• Usebump-major for breaking changes
• Usebump-alpha for prerelease versions
• Usegraduate to promote prerelease versions to stable

• melos bootstrap: Set up the workspace
• melos clean: Clean all packages
• melos test: Run tests for all packages
• melos format: Format all packages
• melos analyze: Run static analysis
• melos build: Run build_runner for all packages
• melos publish: Publish packages to pub.dev

If the automated publish fails:

1. Check the GitHub Actions logs for specific errors
2. Ensure all tests are passing locally:melos test
3. Verify that version numbers inpubspec.yaml files are correct
4. Check that all dependencies are properly versioned

For manual publishing (if needed, requires pub dev authentication):

melos publish --no-dry-run --yes --scope="package_name"

• The publish workflow publishes packages in a specific order to handle dependencies correctly
• All packages are versioned together to maintain consistency
• The workflow automatically handles pub.dev credentials through GitHub Secrets
• Changes topubspec.yaml files automatically trigger the publish workflow

Please file feature requests and bugs at theGitHub.