gql-query-builder AGENTS.md

gql-query-builder — Agent Guide

Zero-runtime-dependency TypeScript library that generates GraphQL query/mutation/subscription strings (plus a variables object) from plain JavaScript objects. Published to npm as gql-query-builder.

Commands

Package manager is pnpm (see packageManager in package.json). Node >= 22.

Task	Command
Install	pnpm install
Build (ESM + CJS + d.ts to dist/)	pnpm build
Typecheck (no emit)	pnpm typecheck
Lint + format check (Biome)	pnpm lint
Auto-fix lint/format	pnpm format
Test (Vitest)	pnpm test
Single test file	pnpm exec vitest run src/__tests__/query.test.ts
Coverage	pnpm coverage
Validate published package shape	pnpm check-package (publint + arethetypeswrong)

Layout

• src/index.ts — public entry: query(), mutation(), subscription(), adapters, plus all public types (named exports only).
• src/types.ts — option/result types (QueryBuilderOptions, Fields, NestedField, VariableOptions, Operation, OperationResult) and the isNestedField guard. Deprecated I* aliases live here too.
• src/utils.ts — shared pure helpers (field maps, variable resolution, GraphQL type inference).
• src/adapters/types.ts — adapter contracts (QueryAdapter, MutationAdapter, SubscriptionAdapter) and their constructor types.
• src/adapters/default-{query,mutation,subscription}-adapter.ts — default string-generation classes (use native #private fields).
• src/adapters/app-sync-{query,mutation}-adapter.ts — AWS AppSync variants, bundled in the adapters export.
• src/__tests__/ — Vitest suites (globals enabled, no imports of describe/it needed).
• docs/api.md — compact API reference with canonical examples.

Public API contract

query/mutation/subscription(options, adapter?, config?) returns { query: string, variables: object }. options is { operation, fields?, variables? } or an array of those. See docs/api.md for the full options/variables shapes and examples.