@teages/oh-my-graphql

Another simple GraphQL client, base on 😱ofetch.

Quick Start

Install package:

# ✨ Auto-detect
npx nypm install @teages/oh-my-graphql

# npm
npm install @teages/oh-my-graphql

# yarn
yarn add @teages/oh-my-graphql

# pnpm
pnpm install @teages/oh-my-graphql

# bun
bun install @teages/oh-my-graphql

Example:

import { createClient } from '@teages/oh-my-graphql'

const client = createClient('https://graphql-test.teages.xyz/graphql-user')

const res = await client.query('query { hello }')
console.log(res) // { hello: 'hello, World' }

Usage Reference

Create Client

function createClient(url: string, options?: ClientOptions): GraphQLClient

Example:

const client = createClient('https://graphql-test.teages.xyz/graphql-user', {
  preferMethod: 'POST',
  headers: {
    Authorization: 'Bearer token'
  }
})

Request

function request<
  Result = Record<string, any>,
  Variables = Record<string, any>
>(
  query: DocumentInput<Result, Variables>,
  variables?: Variables,
  optionsOverride?: ClientOptions
): Promise<Result>

Example:

const res = await client.request('query { hello }')
console.log(res) // { hello: 'hello, World' }

You can use client.query or client.mutation to limit the type of your query.

Example:

const res = await client.mutation('query { hello }') // will throw error

Prepare

Create a request function to reuse the query.

function request<
  Result = Record<string, any>,
  Variables = Record<string, any>
>(
  query: DocumentInput<Result, Variables>,
  optionsOverride?: ClientOptions
): GraphQLPreparedRequest<Result, Variables>

interface GraphQLPreparedRequest<Result, Variables> {
  (
    variables?: Variables,
    optionsOverride?: ClientOptions
  ): Promise<Result>
}

Example:

const fetchHello = client.prepare('query { hello }')
const res = await fetchHello()
console.log(res) // { hello: 'hello, World' }

Error Handling

The client throws errors when the request failed or server response with errors.

You may need GraphQLClientError type.

Example:

import { GraphQLClientError } from '@teages/oh-my-graphql'
import { FetchError } from 'ofetch'

try {
  await client.request('query { hello }')
}
catch (error: GraphQLClientError) {
  if (error instanceof FetchError) {
    console.log(error.response) // network error or other fetch error
  }
  console.log(error.errors) // graphql errors
}

Type Reference

ClientOptions

export type ClientOptions = Omit<
  FetchOptions, // from 'ofetch'
  'body' | 'method' | 'ResponseType'
> & {
  /**
   * Default method to use for query.
   * Only effective when `type` is `'query'`.
   * @default 'POST'
   */
  preferMethod: 'POST' | 'GET'
}

GraphQLClientError

export type GraphQLClientError = FetchError | GraphQLErrors

export class GraphQLErrors extends Error {
  errors: GraphQLError[]
  // ...
}

Development

• Clone this repository
• Install latest LTS version of Node.js
• Enable Corepack using corepack enable
• Install dependencies using pnpm install
• Run interactive tests using pnpm dev

License

Published under MIT License.