Usage

Creating a client

The most basic version is to create a new instance of the class providing your API endpoint and calling the gimme() method. This will return a function you can then invoke.

import { GoGet } from "@/modules/goget"

const client = new GoGet("http://").gimme()

The client has a few additional options you can pass & the ability to assign a logger (For example, Tracer)

Tracer

Here is an example of setting every config & a logger. All the config options are optional and have some defaults set.

import { GoGet } from "@/modules/goget"
import { trace } from "@/modules/utility/trace"

const client = new GoGet("http://", {
  enableQueryDebug: process.env['DEBUG_QUERY'] === 'true',
  defaultHeaders: {
    Authorization: `Bearer ...`,
  },
  maxRequestByteSize: 1024 * 10,
  totalRetries: 1
})
  .setLogger(trace)
  .gimme()

Here are the options:

enableQueryDebug: (boolean, default: false) This is determine if additional logging is needed. It goes hand-in-hand with maxRequestByteSize and will log out if you’re getting close to hitting that limit.
defaultHeaders: (object, default: {}) A list of default headers that should be sent along with the request. A good place to add any authorisation tokens. Don’t worry, when you call the client you can pass in request specific headers, or override these defaults if needed.
maxRequestByteSize: (number, default: 8192) This is mainly to help figure out if you might be hitting the limitation of a request size set by the platform. If you want to read a fun story about that, read Optimising GraphQL queries for ContentStack.
totalRetries: (number, default: 5) Specifies the number of times the request will retry if a 429 status code is sent back from the platform. Helps with rate-limiting issues.

Using the client

Once you have this client (or whatever you called it, I like to do GoGetFromXX because its fun) you will want to use it to get some data.

The gimme() method returns a function that you call with some parameters.

const { data, error, rawJson } = await client({
  query: `gql...`,
  variables: { ... },
  headers: { ... },
})

query: (string, required) This is your GraphQL query you want to send to the API. I recommend pairing this with Pigeon.
variables: (object, optional) This is where you can pass in any variables that your query may need. The client function accepts a generic typescript param if you wanted to type that up. client<unknown, QueryVariables>({...}).
headers: (object, optional) These are any additional or override headers you want to provide.
strategy: see Using a strategy

The client will return 3 values.

data: This is the response from the API, you can add type inference to the client client<QueryResponse>. However, I’d recommend running some validation on the data instead of TypeScript magic.
error: If one returned, this will be a Error object.
rawJson: This is the result of calling response.json(), the type of this will be unknown. I’d recommend running some validation on this object before doing anything with it.

I’ve tried to return something for all these fields, but they are all T | null, so do what is right and check the data before doing anything.

Using a strategy

The package exports a QueryStrategy interface that you can implement to run reusable code to alter the request init and/or on the returned response.

import type { QueryStrategy, RequestInit } from "@/modules/goget"

export class NoCacheStrategy implements QueryStrategy {
  alterInit(init: RequestInit): RequestInit {
    const _init = structuredClone(init)
    _init.cache = "no-store"
    return _init
  }
}

Also, notice I am also pulling in the RequestInit from the package, this is because you may change from the base web standard RequestInit when a library decides to patch the fetch API… *cough* Next *cough*.

Once you have these strategies you can pass that into the client call.

import { NoCacheStrategy } from '...'

const { data, error, rawJson } = await client({
  ...,
  strategy: new NoCacheStrategy()
})

This is quite a simple example, but you can imagine with Next.js you can set specific next.tags or next.revalidate values. Set up a strategy to add a consistent 5 day revalidate period to requests to ensure your team are using a consistent revalidate property.