- Rust 98.8%
- CSS 0.6%
- TypeScript 0.4%
Migrating to grebedoc.dev instead of netlify Reviewed-on: #1204 Co-authored-by: Graeme Coupar <graeme@turbofish.tech> Co-committed-by: Graeme Coupar <graeme@turbofish.tech> |
||
|---|---|---|
| .config | ||
| .forgejo | ||
| cynic | ||
| cynic-book | ||
| cynic-cli | ||
| cynic-codegen | ||
| cynic-introspection | ||
| cynic-parser | ||
| cynic-parser-deser | ||
| cynic-parser-deser-macros | ||
| cynic-proc-macros | ||
| cynic-querygen | ||
| cynic-querygen-web | ||
| examples | ||
| graphql-mocks | ||
| large-api-example | ||
| schemas | ||
| tests | ||
| .gitattributes | ||
| .gitignore | ||
| .ignore | ||
| Cargo.lock | ||
| Cargo.toml | ||
| CHANGELOG.md | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| logo.png | ||
| README.md | ||
| release-plz.toml | ||
| renovate.json | ||
| rust-toolchain | ||
Overview
Cynic is a GraphQL library for Rust. It's not the first but it takes a different approach from the existing libraries.
Existing libraries take a query first approach to GQL - you write a query using GraphQL and libraries use that to generate Rust structs for you using macros. This is really easy and great for getting going quickly. However, if you want to use structs that aren't quite what the macros output you're out of luck. Some more complex use cases like sharing structs among queries are also commonly not supported.
Cynic takes a different approach - it uses Rust structs to define queries and
generates GraphQL from them. This gives you freedom to control the structs
you'll be working with while still enjoying type safe queries, checked against
the GraphQL schema. When its built in derives don't do exactly what you
want it provides lower level APIs to hook in and fetch the data you want in the
format you want to work with it.
Of course writing out all the structs to represent a large GraphQL query can be
quite challenging, and GraphQL has excellent tooling for building queries
usually. Cynic provides querygen to help with this - you write a
GraphQL query using the existing GQL tooling and it'll generate some cynic
structs to make that query. You can use this as a starting point for your
projects - either adding on to the rust structs directly, or re-using
querygen as appropriate.
Features
Cynic is currently a work in progress, but the following features are supported:
- Typesafe queries & mutations.
- Defining custom scalars.
- Building dynamic (but still type checked) queries at run time.
- Query arguments including input objects
- Interfaces & union types
- Introspection via
cynic-cliorcynic-introspection - GraphQL Subscriptions via
graphql-ws-client. - Field directives (
@skip,@includeand any custom directives that don't require client support)
Documentation
Cynic is documented in a few places:
- There's a guide to using cynic on cynic-rs.dev
- The reference documentation on docs.rs
Inspiration
- graphql-client, the original Rust GraphQL client. This is a great library for using GraphQL from Rust. It wasn't quite what I wanted but it might be what you want.
- The idea of encoding the GraphQL typesystem into a DSL was taken from elm-graphql.
- Most of the JSON decoding APIs were taken from Json.Decode in Elm.
- Deriving code from structs is a fairly common Rust pattern, though serde in particular provided inspiration for the derive APIs.
Getting Help
If you want help with cynic you can join the #cynic chat room on IRC using any of these options:
- A Web UI
- Using this link if you have an IRC client
- Selecting a client from joinrc.at
- Joining #cynic on irc.libera.chat if you know what you're doing