GotQL

2.2.0 verified Fri May 01 auth: no javascript maintenance

GotQL v2.2.0 is a Node.js library that allows you to write GraphQL queries as JavaScript objects instead of strings, wrapping the Got HTTP client. It acts as a transpiler, converting JSON query definitions into proper GraphQL strings and sending them via HTTP. Key differentiators include built-in HTTP client (Got v11+), support for fragments, variables, enums via template literal helper, and nested fields. Release cadence: infrequent, last release Apr 2022. Requires Node >=18 and ESM.

Common errors

error ERR_REQUIRE_ESM: require() of ES Module /path/to/node_modules/gotql/index.js from /path/to/yourfile.js not supported. ↓

cause GotQL v2.2.0 is ESM-only, but you are using require()

fix

Switch to import syntax: import gotql from 'gotql'

error TypeError: gotql.query is not a function ↓

cause Using default import with CJS require; the module is ESM

fix

Use import gotql from 'gotql' or destructure: import { query } from 'gotql'

error Error: Invalid query: "operation" field required ↓

cause Query object is missing the operation property or it's malformed

fix

Ensure query object has structure: { operation: { name: 'operationName', fields: [...] } }

Warnings

breaking ESM-only since v2.2.0; require() will fail with ERR_REQUIRE_ESM ↓

fix Use import instead of require, or downgrade to v2.0.8 if CJS required

gotcha Modifying the query object after passing to query() may cause unexpected behavior due to mutation ↓

fix Create a new object or deep clone before modifying

deprecated Got v11 is used; older Got v10 options may not work ↓

fix Refer to Got v11 documentation for options like http2, timeout, etc.

gotcha Array arguments with more than one item may cause issues prior to v2.0.8 ↓

fix Upgrade to v2.0.8 or later

gotcha Falsy variables (0, false, null) treated as undefined prior to v2.0.5 ↓

fix Upgrade to v2.0.5 or later

Install

npm install gotql

yarn add gotql

pnpm add gotql

Imports

default
wrong
```
const gotql = require('gotql')
```
correct
```
import gotql from 'gotql'
```
ESM-only since v2.2.0, no default export in CJS

query

wrong

const { query } = require('gotql')

correct

import { query } from 'gotql'

Named export, works in ESM only

mutation

wrong

import mutation from 'gotql'

correct

import { mutation } from 'gotql'

Named export, not default

Quickstart

Shows basic usage with ESM import, constructing a JSON query object and using the query() function with an authorization header.

import gotql from 'gotql';

const query = {
  operation: {
    name: 'users',
    fields: ['id', 'name', 'email']
  }
};

const options = {
  headers: {
    Authorization: `Bearer ${process.env.API_KEY ?? ''}`
  }
};

try {
  const response = await gotql.query('https://api.example.com/graphql', query, options);
  console.log(response.data);
} catch (err) {
  console.error(err);
}