Build Typed GraphQL Queries

Common errors

• Argument of type 'GraphQLQuery<...>' is not assignable to parameter of type 'string'.

  cause Attempting to pass the `typed-graphqlify` query object directly to a GraphQL execution client method that expects a raw GraphQL query string.
  fix Call the `.toString()` method on your generated query object to convert it into a GraphQL string: `executeGraphql(myQuery.toString())`.

• Property 'data' does not exist on type 'GraphQLQuery<...>'

  cause Incorrectly trying to directly access `data` property on the `typed-graphqlify` query builder object for type inference.
  fix To infer the type of the GraphQL response data, use `typeof myQuery.data` (e.g., `const result: typeof myQuery.data = ...`). The `.data` property is a type-only construct.

• Cannot find name 'query'. (or 'types', 'alias')

  cause The necessary functions or objects (`query`, `types`, `alias`) were not imported from the `typed-graphqlify` package.
  fix Ensure you have correctly imported the required symbols using named imports: `import { query, types, alias } from 'typed-graphqlify';`.

Warnings

• gotcha typed-graphqlify functions as a GraphQL query builder and type generator, not a full-fledged GraphQL client. It generates the GraphQL query string and corresponding TypeScript types, but you must use a separate library (e.g., Apollo Client, `fetch`) to execute the generated query string against a GraphQL endpoint.
  Fix: Integrate `typed-graphqlify` with an existing GraphQL client or an HTTP request library for query execution.
• gotcha The `types` helper object (e.g., `types.number`, `types.optional.string`, `types.oneOf`) is crucial for defining the correct GraphQL scalar, optional, and enum types within your query object. Incorrectly using these helpers or omitting them can lead to generated GraphQL strings that do not match your backend schema or incorrect TypeScript type inference.
  Fix: Always use the `types` helpers provided by the library to correctly define the data types for your GraphQL fields. Refer to the documentation for specific usage of `types.oneOf` for enums and `types.array` for lists.
• deprecated When defining enum fields, the README mentions `types.enum` is deprecated. Users should instead use `types.oneOf` with an array or plain object for better type inference and compatibility.
  Fix: Replace `types.enum` with `types.oneOf` and provide an array of possible values or a plain object mapping, e.g., `status: types.oneOf(['ACTIVE', 'INACTIVE'])`.

Install

• npm install typed-graphqlify npm
• yarn add typed-graphqlify yarn
• pnpm add typed-graphqlify pnpm

Imports

• query
  wrong:

  const query = require('typed-graphqlify').query

  correct:

  import { query } from 'typed-graphqlify'

  Used to define a GraphQL query operation. Typed-graphqlify is primarily an ESM-first library.
• types
  wrong:

  import types from 'typed-graphqlify'

  correct:

  import { types } from 'typed-graphqlify'

  The `types` object provides helpers (e.g., `types.number`, `types.optional.string`) for defining scalar and complex types within the query structure. It is a named import.
• alias
  wrong:

  import { Alias } from 'typed-graphqlify'

  correct:

  import { alias } from 'typed-graphqlify'

  Used for aliasing fields in GraphQL queries. It is a named import.
• mutation

  import { mutation } from 'typed-graphqlify'

  Used for defining GraphQL mutation operations, similar to `query` but for write operations.

Quickstart

This example demonstrates how to define a typed GraphQL query, generate its string representation, and type-safely consume its result.

import { query, types } from 'typed-graphqlify';

// Mock an execution function for demonstration purposes
async function executeGraphql<T>(graphqlQuery: string): Promise<T> {
  console.log('Executing GraphQL query:\n', graphqlQuery);
  // In a real application, this would make an actual network request
  // to your GraphQL endpoint (e.g., using fetch, axios, or a GraphQL client).
  // For this example, we'll return a mock data structure that matches the
  // query's expected type, simulating a successful response.
  return Promise.resolve({
    user: {
      id: 123,
      name: 'John Doe',
      bankAccount: {
        id: 456,
        branch: 'Main Branch', // Or undefined if optional and not present
      },
    },
  } as T);
}

// Define a GraphQL query using typed-graphqlify's DSL
const getUserQuery = query('GetUser', {
  user: {
    id: types.number,
    name: types.string,
    bankAccount: {
      id: types.number,
      branch: types.optional.string, // Define 'branch' as an optional string
    },
  },
});

console.log('Generated GraphQL Query:\n', getUserQuery.toString());

// Execute the GraphQL query and infer the result type safely
const data: typeof getUserQuery.data = await executeGraphql(getUserQuery.toString());

console.log('Received data:', data);
// Demonstrate type-safety: 'data' is strongly typed based on the query definition
console.log(`User ID: ${data.user.id}`);
console.log(`User Name: ${data.user.name}`);
if (data.user.bankAccount.branch) {
  console.log(`Bank Branch: ${data.user.bankAccount.branch}`);
} else {
  console.log('Bank Branch: Not provided');
}