{"id":16253,"library":"typed-graphqlify","title":"Build Typed GraphQL Queries","description":"typed-graphqlify is a TypeScript library designed to streamline the process of building GraphQL queries by providing a single source of truth for both the GraphQL query structure and its corresponding TypeScript types. It eliminates the common problem of redundancy found in many GraphQL client setups where developers must define a GraphQL query string and then separately define a matching TypeScript interface. The library, currently at version 3.1.6, generally sees minor updates every few weeks to months, focusing on dependency updates and minor feature enhancements. Its core differentiator lies in its ability to generate GraphQL query strings and strong TypeScript types directly from a GraphQL-like JavaScript object structure, using dedicated `types` helpers for scalar and optional fields. It primarily acts as a query builder, providing the necessary string for execution, but does not handle the network request itself, integrating seamlessly with existing GraphQL clients like Apollo or Relay for actual data fetching.","status":"active","version":"3.1.6","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/acro5piano/typed-graphqlify","tags":["javascript","graphql","typescript","utility"],"install":[{"cmd":"npm install typed-graphqlify","lang":"bash","label":"npm"},{"cmd":"yarn add typed-graphqlify","lang":"bash","label":"yarn"},{"cmd":"pnpm add typed-graphqlify","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Used to define a GraphQL query operation. Typed-graphqlify is primarily an ESM-first library.","wrong":"const query = require('typed-graphqlify').query","symbol":"query","correct":"import { query } from 'typed-graphqlify'"},{"note":"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.","wrong":"import types from 'typed-graphqlify'","symbol":"types","correct":"import { types } from 'typed-graphqlify'"},{"note":"Used for aliasing fields in GraphQL queries. It is a named import.","wrong":"import { Alias } from 'typed-graphqlify'","symbol":"alias","correct":"import { alias } from 'typed-graphqlify'"},{"note":"Used for defining GraphQL mutation operations, similar to `query` but for write operations.","symbol":"mutation","correct":"import { mutation } from 'typed-graphqlify'"}],"quickstart":{"code":"import { query, types } from 'typed-graphqlify';\n\n// Mock an execution function for demonstration purposes\nasync function executeGraphql<T>(graphqlQuery: string): Promise<T> {\n  console.log('Executing GraphQL query:\\n', graphqlQuery);\n  // In a real application, this would make an actual network request\n  // to your GraphQL endpoint (e.g., using fetch, axios, or a GraphQL client).\n  // For this example, we'll return a mock data structure that matches the\n  // query's expected type, simulating a successful response.\n  return Promise.resolve({\n    user: {\n      id: 123,\n      name: 'John Doe',\n      bankAccount: {\n        id: 456,\n        branch: 'Main Branch', // Or undefined if optional and not present\n      },\n    },\n  } as T);\n}\n\n// Define a GraphQL query using typed-graphqlify's DSL\nconst getUserQuery = query('GetUser', {\n  user: {\n    id: types.number,\n    name: types.string,\n    bankAccount: {\n      id: types.number,\n      branch: types.optional.string, // Define 'branch' as an optional string\n    },\n  },\n});\n\nconsole.log('Generated GraphQL Query:\\n', getUserQuery.toString());\n\n// Execute the GraphQL query and infer the result type safely\nconst data: typeof getUserQuery.data = await executeGraphql(getUserQuery.toString());\n\nconsole.log('Received data:', data);\n// Demonstrate type-safety: 'data' is strongly typed based on the query definition\nconsole.log(`User ID: ${data.user.id}`);\nconsole.log(`User Name: ${data.user.name}`);\nif (data.user.bankAccount.branch) {\n  console.log(`Bank Branch: ${data.user.bankAccount.branch}`);\n} else {\n  console.log('Bank Branch: Not provided');\n}\n","lang":"typescript","description":"This example demonstrates how to define a typed GraphQL query, generate its string representation, and type-safely consume its result."},"warnings":[{"fix":"Integrate `typed-graphqlify` with an existing GraphQL client or an HTTP request library for query execution.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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'])`.","message":"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.","severity":"deprecated","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Call the `.toString()` method on your generated query object to convert it into a GraphQL string: `executeGraphql(myQuery.toString())`.","cause":"Attempting to pass the `typed-graphqlify` query object directly to a GraphQL execution client method that expects a raw GraphQL query string.","error":"Argument of type 'GraphQLQuery<...>' is not assignable to parameter of type 'string'."},{"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.","cause":"Incorrectly trying to directly access `data` property on the `typed-graphqlify` query builder object for type inference.","error":"Property 'data' does not exist on type 'GraphQLQuery<...>'"},{"fix":"Ensure you have correctly imported the required symbols using named imports: `import { query, types, alias } from 'typed-graphqlify';`.","cause":"The necessary functions or objects (`query`, `types`, `alias`) were not imported from the `typed-graphqlify` package.","error":"Cannot find name 'query'. (or 'types', 'alias')"}],"ecosystem":"npm"}