{
  "compilerOptions": {
    "target": "ES2018",
    "module": "CommonJS",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true
  }
}

3. If you import directly from the source (not the npm package), set up a path alias so your code resolves cleanly:

{
  "compilerOptions": {
    "paths": {
      "graphql-src/*": ["./src/graphql-js/*"]
    }
  }
}

4. No environment variables are required. For production servers, set NODE_ENV=production to disable development-only assertion checks inside the library, which measurably improves throughput.

5. If you are using the npm package rather than the raw source, no additional wiring is needed—import directly from "graphql".

Public API

graphql

import { graphql } from 'graphql';

async function graphql(args: GraphQLArgs): Promise<ExecutionResult>;

interface GraphQLArgs {
  schema: GraphQLSchema;
  source: string | Source;
  rootValue?: unknown;
  contextValue?: unknown;
  variableValues?: Maybe<{ readonly [variable: string]: unknown }>;
  operationName?: Maybe<string>;
  fieldResolver?: Maybe<GraphQLFieldResolver<any, any>>;
  typeResolver?: Maybe<GraphQLTypeResolver<any, any>>;
}

Use this as the single entry point when you want to parse, validate, and execute a GraphQL request in one call. It returns a Promise, making it suitable for async request handlers. Use graphqlSync when you are certain all resolvers are synchronous.

execute

import { execute, executeSync } from 'graphql';

function execute(args: ExecutionArgs): PromiseOrValue<ExecutionResult>;
function executeSync(args: ExecutionArgs): ExecutionResult;

interface ExecutionResult<TData = ObjMap<unknown>, TExtensions = ObjMap<unknown>> {
  errors?: ReadonlyArray<GraphQLError>;
  data?: TData | null;
  extensions?: TExtensions;
}

Use execute when you have already parsed and validated a document and want direct control over execution. executeSync throws if any resolver returns a Promise, so reserve it for fully synchronous schemas.

parse

import { parse } from 'graphql';
import type { ParseOptions, DocumentNode } from 'graphql';

function parse(source: string | Source, options?: ParseOptions): DocumentNode;

Converts a GraphQL query string into an AST DocumentNode. Use this to inspect, transform, or cache the parsed representation before execution. Throws GraphQLError with location information on syntax errors.

GraphQLSchema

import { GraphQLSchema } from 'graphql';

class GraphQLSchema {
  constructor(config: GraphQLSchemaConfig);
}

The central class that wires together your type definitions. Passed to every execution and validation call. Construct once at startup and reuse across requests.

GraphQLError

import { GraphQLError } from 'graphql';

class GraphQLError extends Error {
  readonly message: string;
  readonly locations: ReadonlyArray<SourceLocation> | undefined;
  readonly path: ReadonlyArray<string | number> | undefined;
  readonly extensions: GraphQLErrorExtensions;
  toJSON(): GraphQLFormattedError;
}

The standard error class used throughout the library. Inspect locations for editor-friendly line/column info and path to find which field in the response failed.

Working examples

Scenario - Minimal schema with a hello field

Define a schema with a single string field and run a query against it.

import {
  graphql,
  GraphQLSchema,
  GraphQLObjectType,
  GraphQLString,
} from 'graphql';

const schema = new GraphQLSchema({
  query: new GraphQLObjectType({
    name: 'Query',
    fields: {
      hello: {
        type: GraphQLString,
        resolve: () => 'world',
      },
    },
  }),
});

const result = await graphql({ schema, source: '{ hello }' });
console.log(result); // { data: { hello: 'world' } }

Scenario - Parse, validate, then execute separately

For production servers, parse once, validate once, then execute per request to avoid redundant work.

import {
  parse,
  validate,
  execute,
  GraphQLSchema,
  GraphQLObjectType,
  GraphQLString,
  GraphQLInt,
} from 'graphql';

const schema = new GraphQLSchema({
  query: new GraphQLObjectType({
    name: 'Query',
    fields: {
      roll: {
        type: GraphQLInt,
        resolve: () => Math.floor(Math.random() * 6) + 1,
      },
    },
  }),
});

const source = '{ roll }';
const document = parse(source);

const errors = validate(schema, document);
if (errors.length > 0) {
  console.error('Validation failed:', errors);
  process.exit(1);
}

// Reuse parsed + validated document for each request
const result = await execute({ schema, document });
console.log(result); // { data: { roll: 4 } }

Scenario - Structured error handling with GraphQLError

Inspect and format errors returned from execution.

import {
  graphql,
  GraphQLSchema,
  GraphQLObjectType,
  GraphQLString,
  GraphQLError,
  formatError,
} from 'graphql';

const schema = new GraphQLSchema({
  query: new GraphQLObjectType({
    name: 'Query',
    fields: {
      boom: {
        type: GraphQLString,
        resolve: () => {
          throw new GraphQLError('Something went wrong', {
            extensions: { code: 'INTERNAL_ERROR' },
          });
        },
      },
    },
  }),
});

const result = await graphql({ schema, source: '{ boom }' });

if (result.errors) {
  for (const err of result.errors) {
    const formatted = formatError(err);
    console.error(formatted);
    // { message: 'Something went wrong', locations: [...], path: ['boom'], extensions: { code: 'INTERNAL_ERROR' } }
  }
}

File walkthrough

• graphql.ts - Implements graphql() and graphqlSync(), orchestrating parse → validate → execute.
• index.ts - Single barrel export; import anything from 'graphql' via this file.
• version.ts - Exports version: string and versionInfo: { major, minor, patch, ... }.
• error/GraphQLError.ts - Core error class; formatError serializes to spec-compliant JSON shape.
• error/locatedError.ts - Wraps arbitrary errors with location/path context during execution.
• error/syntaxError.ts - Produces GraphQLError instances from lexer/parser failures.
• execution/execute.ts - Main execution engine; resolves fields, handles promises, builds response.
• execution/subscribe.ts - Async-iterator-based subscription execution.
• execution/values.ts - Coerces and validates argument and variable values against the schema.
• execution/collectFields.ts - Determines which fields to resolve for a given object type and selection set.
• execution/mapAsyncIterator.ts - Utility to transform async iterables, used by subscriptions.
• jsutils/ - Internal helpers: inspect (safe serialization), invariant (dev assertions), Path (response path tracking), promiseReduce, suggestionList, and more.
• language/parser.ts - Recursive-descent parser producing a typed AST from a query string.
• language/lexer.ts - Tokenizes GraphQL source into the token stream consumed by the parser.
• language/printer.ts - Serializes an AST DocumentNode back to a formatted GraphQL string.
• language/visitor.ts - Generic AST traversal with enter/leave hooks; foundation for transforms.
• language/ast.ts - TypeScript types for every AST node kind.
• language/kinds.ts - Kind enum mapping every AST node type name.
• language/source.ts - Source class wrapping a query string with optional name and location offset.
• type/schema.ts - GraphQLSchema class; validates type consistency at construction time.
• type/definition.ts - All named type classes: GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType, GraphQLEnumType, GraphQLInputObjectType, GraphQLScalarType, GraphQLList, GraphQLNonNull.
• type/scalars.ts - Built-in scalars: GraphQLString, GraphQLInt, GraphQLFloat, GraphQLBoolean, GraphQLID.
• type/directives.ts - Built-in directives: @skip, @include, @deprecated, @specifiedBy.
• type/introspection.ts - Schema introspection types (__Schema, __Type, etc.).
• subscription/index.ts - Deprecated module; re-exports subscribe and createSourceEventStream from execution/.
• utilities/ - Schema SDL printing, introspection query helpers, type-map utilities, schema extenders.
• validation/ - validate() function and all specification-mandated validation rules.

Common pitfalls and fixes

• NODE_ENV not set in production: Development assertions run on every call and hurt throughput; always set NODE_ENV=production in your process environment for deployed servers.
• Mixing CommonJS and ESM: The npm package ships both formats; if your bundler resolves the ESM build but your test runner expects CJS, pin moduleResolution to "node" and use the CJS entry in Jest via transformIgnorePatterns or moduleNameMapper.
• graphqlSync throwing on async resolvers: Any resolver that returns a Promise causes executeSync to throw immediately; audit every resolver or use execute instead.
• Reusing DocumentNode across schemas: A parsed document is schema-agnostic, but the result of validate() is not—always re-validate when the schema changes.
• Integer bounds: GraphQL Int is 32-bit signed; the library enforces GRAPHQL_MIN_INT / GRAPHQL_MAX_INT (-2147483648 / 2147483647). Use GraphQLFloat or a custom scalar for larger numbers.
• Subscription cleanup: createSourceEventStream returns an AsyncIterable; always call .return() on the iterator when the client disconnects to avoid resource leaks.

Vibe-coding prompt template

I have dropped the GraphQL.js reference implementation source into `src/graphql-js/`
and there is a USAGE.md at the project root that documents the real API.

Upstream npm package: user@example.com
Source root: src/graphql-js/
Key modules:
  - src/graphql-js/graphql.ts        → graphql(), graphqlSync()
  - src/graphql-js/type/definition.ts → GraphQLObjectType, GraphQLSchema, etc.
  - src/graphql-js/language/parser.ts → parse()
  - src/graphql-js/execution/execute.ts → execute(), executeSync()
  - src/graphql-js/validation/index.ts  → validate()

Please integrate this library into my project step by step:
1. Read USAGE.md for correct import paths and signatures.
2. Create a GraphQLSchema using GraphQLObjectType and the built-in scalars.
3. Wire an Express (or Fastify) POST /graphql endpoint that reads `query` and
   `variables` from the request body, calls parse() → validate() → execute(),
   and returns the ExecutionResult as JSON.
4. Add structured error handling that serialises GraphQLError instances using
   formatError() before sending the response.
5. Do not invent any API symbols; use only what is documented in USAGE.md.

License and credit

GraphQL.js is released under the MIT License (see source/LICENSE if present, or the license field in the upstream package.json). It is maintained by the GraphQL Foundation.

Upstream repository and documentation: https://github.com/graphql/graphql-js npm package: https://www.npmjs.com/package/graphql

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Scalar Interactive API Reference and Client

Automation, Utilities & Developer Tools

Free