{"id":13880554,"url":"https://github.com/notarize/qlc","last_synced_at":"2025-07-16T17:30:34.029Z","repository":{"id":35059407,"uuid":"193021234","full_name":"notarize/qlc","owner":"notarize","description":"A super fast and multithreaded GraphQL codegenerator","archived":false,"fork":false,"pushed_at":"2024-12-04T18:36:33.000Z","size":404,"stargazers_count":61,"open_issues_count":3,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-13T01:54:56.968Z","etag":null,"topics":["codegen","compiler","graphql","types","typescript","typings"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/notarize.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-21T03:04:53.000Z","updated_at":"2025-04-29T12:47:41.000Z","dependencies_parsed_at":"2024-06-21T14:19:18.867Z","dependency_job_id":"c251a9e8-467d-425f-9789-19d7e816b8b5","html_url":"https://github.com/notarize/qlc","commit_stats":{"total_commits":131,"total_committers":2,"mean_commits":65.5,"dds":0.007633587786259555,"last_synced_commit":"7fee0cea1723765d1928888e78ad681bf25e3702"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/notarize/qlc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notarize%2Fqlc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notarize%2Fqlc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notarize%2Fqlc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notarize%2Fqlc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/notarize","download_url":"https://codeload.github.com/notarize/qlc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/notarize%2Fqlc/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265527541,"owners_count":23782480,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["codegen","compiler","graphql","types","typescript","typings"],"created_at":"2024-08-06T08:03:11.114Z","updated_at":"2025-07-16T17:30:33.620Z","avatar_url":"https://github.com/notarize.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"## 👌 QL Compiler (qlc)\n\nThe QL compiler is a fun codegenerator for GraphQL clients. Specifically, it is capable of reading\n`.graphql` query, mutation, and fragment files and combining this with schema introspection JSON to\nproduce ad-hoc type definitions for TypeScript. It is similar to the tools\n[Apollo Tooling CLI](https://github.com/apollographql/apollo-tooling) and\n[GraphQL Code Generator](https://github.com/dotansimha/graphql-code-generator), but smaller in scope\n(and faster).\n\n### Motivating Example\n\nSay you have a query that looks like this:\n\n```graphql\nquery CommentQuery($id: ID!) {\n  comment(id: $id) {\n    author {\n      name\n      avatar: profilePictureUrl\n    }\n    content\n  }\n}\n```\n\nIf you are using TypeScript and a GraphQL client, it would be useful to get the type of this query.\nYou could write one out by hand (and then maintain this definition as the query changes). But since\nGraphQL supports introspection and has a schema, we already know the type for the above! `qlc`\nenables you to automate the codegen of the following types:\n\n```ts\nexport type CommentQuery_comment_author = {\n  name: string;\n  avatar: string | null;\n};\n\nexport type CommentQuery_comment = {\n  author: CommentQuery_comment_author;\n  content: string;\n};\n\nexport type CommentQuery = {\n  comment: CommentQuery_comment;\n};\n\nexport type CommentQueryVariables = {\n  id: string;\n};\n```\n\n### Usage\n\nYou can download _some_ prebuilt binaries on the\n[releases](https://github.com/notarize/qlc/releases) page. You will need to build from source with\n`cargo` for other platforms.\n\nFor convenience, it is also available as an NPM package that supports x64/aarch64 MacOS and x64\nlinux:\n\n```sh\nyarn add @notarize/qlc-cli\n```\n\n`qlc` will recursively scan directories, finding `.graphql` files and producing `.graphql.d.ts`\nfiles. By default, it starts at the working directory but you can optionally provide it a directory\nargument. `qlc` supports fragment imports with the `#import \"\u003cfile\u003e.graphql\"` syntax at the top of\nyour files; it supports both relative imports and absolute imports starting at the root directory\nsupplied to `qlc`.\n\nYou will need to supply `qlc` with the JSON result of _the_ introspection query. Most, if not all,\nGraphQL servers support producing this query result, and the canonical implementation can even be\nfound in the official [graphql](https://www.npmjs.com/package/graphql) NPM package. See\n[this blog post](https://blog.apollographql.com/three-ways-to-represent-your-graphql-schema-a41f4175100d)\nfor more information. For simplicity, the NPM package comes with a helper script that should be\nsuitable for most users. See below.\n\n#### Example\n\n```sh\n# Download a schema JSON from an endpoint and write to my_schema.json\nyarn run qlc-download-schema https://\u003cFQDN\u003e/graphql my_schema.json\n\n# Run qlc searching the src/ directory with schema JSON located at my_schema.json\nyarn run qlc -s my_schema.json src\n\n# There are some other options available for more complex requirements.\nyarn run qlc --help\n```\n\nMany of the options can also be configured through a camelcased JSON file (by default\n`.qlcrc.json`). For example:\n\n```json\n{ \"useCustomScalars\": true, \"numThreads\": 2 }\n```\n\n#### Typed Document Nodes\n\n`qlc` outputs \"typed\" GraphQL document nodes so that clients can auto infer result and variable\ntypes. Reference implementations are included in the `@notarize/qlc-cli/typed-documentnode` module.\nThis requires the optional `graphql` dependency. One can choose not to use this implementation by\noverriding the `--typed-graphql-documentnode-module-name` option. For example:\n\n```sh\nyarn run qlc --typed-graphql-documentnode-module-name 'my-typenode'\n```\n\n```ts\n// In my-typenode.ts, something like:\n\nexport type QueryDocumentNode\u003cData, Vars\u003e = unknown;\n// more types for Mutation, Subscription, etc.\n```\n\n### Benchmarking\n\nHow much faster is \"faster\"? All results below are collected on MacOS, a 2.8 GHz quad-core machine\nwith an NVMe storage device, with the operating system's IO cache hot. The `hyperfine` utility\nmeasured runtime. The directory in question has 4523 files and 534 `.graphql` files.\n\n| Command                                     | Version               | Mean Time ± σ      | NPM Dependencies |\n| ------------------------------------------- | --------------------- | ------------------ | ---------------- |\n| `qlc`                                       | 0.6.0                 | 118.8 ms ± 10.8 ms | 1 (itself)       |\n| `apollo client:codegen --target=typescript` | 2.31.1 (node 14.15.0) | 4.817 s ± 0.475 s  | 355              |\n\n### Development\n\nTo develop qlc, one needs a working `cargo`, `rustc`, `node`, and `yarn` installation. The repository\nprovides this via a Nix shell (`shell.nix`) for ease. `node` and `yarn` are used for some tasks, like\npackaging the NPM release (see `pkg/npm`), as well as creating a mock schema JSON for testing.\n\nHere are a number of reminders for useful commands, most of which also are executed in CI:\n\n```shell\n# If using the nix shell, the `just` command runner can be utilized to list recipes\njust\n\n# Static tools\njust lint\njust format\n\n# Benchmarking on a `src` directory (using hyperfine)\nhyperfine --warmup 2 -p 'find src -name \"*.graphql.d.ts\" -type f -exec rm {} +' '../qlc/target/release/qlc src'\n\n# Testing\n## Test Setup\njust build-test-schema\n\n## Run all tests\njust test\n\n## Run matching test\njust test union_with_typename\n\n## Instruct cargo test not to capture stdout/stderr so that one can see `dbg!()` output, etc.\njust test -- --nocapture\n\n## Instruct the test harness not to delete temporary directories created during testing for debugging\nKEEP_TEST_TEMPDIRS=t just test\n\n## Instruct the test harness overwrite expected fixtures with actual output -- useful for large swath compiler output changes\n## Warning: will change repo files on disk\nOVERWRITE_FIXTURES=t just test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnotarize%2Fqlc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnotarize%2Fqlc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnotarize%2Fqlc/lists"}