tiny-graphql-query-compiler

0.2.3 verified Fri May 01 auth: no javascript

A JavaScript DSL for constructing GraphQL queries programmatically. v0.2.3 (pre-1.0, experimental). Converts a plain object representation into a valid GraphQL query string with support for arguments, variables, and fragment composition. Key differentiators: extremely lightweight (~1KB), no runtime GraphQL parser, TypeScript-first with full type inference for fields and arguments, and includes compileWithVariableValues for extracting both query and variable bindings. Ideal for codebases that need to dynamically generate queries without the overhead of graphql-tag or Apollo.

Common errors

error TypeError: Call is not a function ↓

cause Missing named import for Call.

fix

Ensure you import Call: import { Call } from 'tiny-graphql-query-compiler'.

error SyntaxError: Cannot use import statement outside a module ↓

cause The package is ESM-only and cannot be required() without transpilation.

fix

Use import syntax in an ESM context, or configure Node.js to treat the package as ESM (e.g., set type: 'module' in package.json).

error ReferenceError: compile is not defined ↓

cause Using default import instead of named import.

fix

Use: import { compile } from 'tiny-graphql-query-compiler' (not import compile from ...).

Warnings

breaking Pre-1.0 API may change without major version bump. ↓

fix Pin to a specific version and monitor changelog.

deprecated Symbolic names for types (e.g., 'ID!') are string literals, not enums—this may change in future releases. ↓

fix Currently no fix; be prepared to update string literals if types are later represented as TypeScript enums.

gotcha Call and Var must be imported explicitly; they are not exported as part of a default object. ↓

fix Use named imports: import { Call, Var } from 'tiny-graphql-query-compiler'.

gotcha The library does not validate the resulting GraphQL; it only generates the string. Syntax errors in the object will produce incorrect queries. ↓

fix Always test generated queries against a real GraphQL endpoint or use a validator like graphql-js.

Install

npm install tiny-graphql-query-compiler

yarn add tiny-graphql-query-compiler

pnpm add tiny-graphql-query-compiler

Imports

compile
wrong
```
const compile = require('tiny-graphql-query-compiler').compile;
```
correct
```
import { compile } from 'tiny-graphql-query-compiler'
```
The library is ESM-only (no default export), so require() must use .compile property access—better to use ESM import.
Call
```
import { Call } from 'tiny-graphql-query-compiler'
```
Used to wrap a field call with arguments. Must be used inside a fields object.

Var

wrong

import { Var } from 'tiny-graphql-query-compiler/Var';

correct

import { Var } from 'tiny-graphql-query-compiler'

Do not use a subpath import; Var is a named export from the main package.

compileWithVariableValues

wrong

import compileWithVariableValues from 'tiny-graphql-query-compiler';

correct

import { compileWithVariableValues } from 'tiny-graphql-query-compiler'

It's a named export, not a default export.

Quickstart

Shows basic compile, arguments with Call and Var, and compileWithVariableValues for extracting query and variables.

import { compile, Call, Var, compileWithVariableValues } from 'tiny-graphql-query-compiler';

// Simple query
const simpleQuery = compile({
  type: 'query',
  fields: {
    hello: true
  }
});
console.log(simpleQuery);
// Output: query { hello }

// Query with arguments and variables
const { query, variables } = compileWithVariableValues({
  type: 'query',
  fields: {
    user: Call(
      { id: Var({ type: 'ID!', value: '1' }) },
      {
        name: true,
        email: true
      }
    )
  }
});
console.log(query);
// Output: query ($id: ID!) { user(id: $id) { name email } }
console.log(variables);
// Output: { id: '1' }