https://github.com/webpod/graphql-megaera
GraphQL to TypeScript Generator
https://github.com/webpod/graphql-megaera
code-generation graphql graphql-codegen typescript
Last synced: 12 months ago
JSON representation
GraphQL to TypeScript Generator
- Host: GitHub
- URL: https://github.com/webpod/graphql-megaera
- Owner: webpod
- License: mit
- Created: 2024-07-07T21:02:42.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-12-01T21:30:53.000Z (over 1 year ago)
- Last Synced: 2025-03-31T14:15:28.987Z (12 months ago)
- Topics: code-generation, graphql, graphql-codegen, typescript
- Language: TypeScript
- Homepage:
- Size: 71.3 KB
- Stars: 42
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# GraphQL Megaera
GraphQL to TypeScript Generator
## Example
From GraphQL
To TypeScript
```graphql
query IssuesQuery {
issues(first: 100) {
totalCount
nodes {
createdAt
closedAt
closed
author {
login
}
number
title
labels(first: 10) {
totalCount
nodes {
name
}
}
body
comments(first: 10) {
totalCount
nodes {
body
}
}
repository {
owner {
login
}
name
}
}
pageInfo {
hasNextPage
endCursor
}
}
rateLimit {
limit
cost
remaining
resetAt
}
}
```
```ts
type IssuesQuery = () => {
issues: {
totalCount: number
nodes: Array<{
createdAt: string
closedAt: string | null
closed: boolean
author: {
login: string
}
number: number
title: string
labels: {
totalCount: number
nodes: Array<{
name: string
}>
}
body: string
comments: {
totalCount: number
nodes: Array<{
body: string
}>
}
repository: {
owner: {
login: string
}
name: string
}
}>
pageInfo: {
hasNextPage: boolean
endCursor: string | null
}
}
rateLimit: {
limit: number
cost: number
remaining: number
resetAt: string
}
}
```
## Installation
```bash
npm install megaera
```
## Usage
```bash
megaera --schema=schema.graphql ./src/**/*.graphql
```
Megaera will generate TypeScript code for all queries in the specified files.
## FAQ
How to use Megaera?
Put your queries in `.graphql` files, and run `megaera` to generate TypeScript code from them.
Megaera will copy the query string to the generated TypeScript file, so you can
import it in your TypeScript code.
```ts
import { IssuesQuery } from './query.graphql.ts'
```
The `IssuesQuery` variable is a string with the GraphQL query. You can use it
directly in your code, or pass it to a function that accepts a query.
Also, `IssuesQuery` carries the type of the query, so you can use it to infer
the return type of the query, and the types of the input variables.
```ts
type Result = ReturnType
```
The type `IssuesQuery` can also be used independently:
```ts
import type { IssuesQuery } from './query.graphql.ts'
```
How to get the return type of a query?
Megaera generates TypeScript types for queries as functions.
```ts
type UserQuery = (vars: { login?: string }) => {
user: {
login: string
avatarUrl: string
name: string
}
}
```
To get the return type of a query, use the `ReturnType` utility type:
```ts
type Result = ReturnType
```
How to get the types of the variables of a query?
The first parameter of the query function is the variables.
You can use TypeScript's `Parameters` utility type to get the types of the variables:
```ts
type Variables = Parameters[0]
```
Or you can use the `Variables` utility type to get the types of the variables:
```ts
import { Variables } from 'megaera'
type Variables = Variables
```
Why query string is copied to TypeScript file as well?
To make it easier to import queries in TypeScript projects. As well to connect
generated output types with query source code.
This allows for library authors to create a function that accepts a query, and
infers the return type from the query, as well as the types of the variables.
For example, wrap [Octokit](https://github.com/octokit/octokit.js) in a function
that accepts a query and returns the result:
```ts
import { Query, Variables } from 'megaera'
import { IssuesQuery } from './query.graphql.ts'
function query(query: T, variables?: Variables) {
return octokit.graphql>(query, variables)
}
// Return type, and types of variables are inferred from the query.
const { issues } = await query(IssuesQuery, { login: 'webpod' })
```
Does Megaera support fragments?
Yes, Megaera fully supports fragments. Fragments are generated as separate types,
and can be used independently.
```graphql
query IssuesQuery($login: String) {
issues(login: $login) {
totalCount
nodes {
...Issue
}
}
}
fragment Issue on Issue {
number
author {
login
}
createdAt
closedAt
}
```
The generated TypeScript code will have a type `Issue` that can be used independently:
```ts
import { Issue, IssuesQuery } from './query.graphql.ts'
const firstIssue: Issue = query(IssuesQuery).issues.nodes[0]
```
Can Megaera extract queries from `.ts` files?
No. To simplify development of Megaera, it is only possible to extract queries
from `.graphql` files.
But it should be possible to create plugins for webpack, rollup, or other
bundlers that can extract queries from `.ts` files. If you are interested in
this, please open an issue.
## License
[MIT](LICENSE)