or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-execution.mderror-handling.mdexecution-engine.mdindex.mdlanguage-processing.mdschema-utilities.mdtype-system.mdvalidation-system.md
tile.json

tessl/npm-graphql

JavaScript reference implementation for GraphQL query language and runtime

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/graphql@16.11.x

To install, run

npx @tessl/cli install tessl/npm-graphql@16.11.0

index.mddocs/

GraphQL.js

GraphQL.js is the JavaScript reference implementation for GraphQL, a query language and runtime for APIs. It provides comprehensive functionality for building GraphQL type schemas, parsing GraphQL queries, validating them, and executing them against those schemas. The library supports both server-side implementations and client-side tooling with robust validation, execution, and error handling capabilities.

Package Information

  • Package Name: graphql
  • Package Type: npm
  • Language: TypeScript/JavaScript
  • Installation: npm install graphql

Core Imports

import { graphql, buildSchema, GraphQLSchema, GraphQLError } from "graphql";

For CommonJS:

const { graphql, buildSchema, GraphQLSchema, GraphQLError } = require("graphql");

Version Information

Access version information for the GraphQL.js library.

/**
 * A string containing the version of the GraphQL.js library
 */
const version: string;

/**
 * An object containing the components of the GraphQL.js version string
 */
const versionInfo: {
  readonly major: number;
  readonly minor: number;
  readonly patch: number;
  readonly preReleaseTag: string | null;
};

Usage Examples:

import { version, versionInfo } from "graphql";

console.log(`GraphQL.js version: ${version}`);
// "GraphQL.js version: 16.11.0"

console.log(`Major version: ${versionInfo.major}`);
// "Major version: 16"

console.log(versionInfo);
// { major: 16, minor: 11, patch: 0, preReleaseTag: null }

Basic Usage

import { graphql, buildSchema } from "graphql";

// Create a schema
const schema = buildSchema(`
  type Query {
    hello: String
  }
`);

// Define resolvers
const rootValue = {
  hello: () => "Hello world!"
};

// Execute a query
const result = await graphql({
  schema,
  source: '{ hello }',
  rootValue
});

console.log(result.data); // { hello: "Hello world!" }

Architecture

GraphQL.js is built around several key components:

  • Core Execution: The main graphql() function that orchestrates parsing, validation, and execution
  • Type System: Classes and utilities for defining GraphQL schemas with types, fields, and resolvers
  • Language Tools: Parser, lexer, and AST manipulation utilities for GraphQL documents
  • Validation System: Complete implementation of GraphQL validation rules with extensible validation context
  • Execution Engine: Runtime for executing GraphQL operations with support for async resolvers and subscriptions
  • Error Handling: Comprehensive error system with source location tracking and formatting
  • Schema Utilities: Tools for building, extending, introspecting, and comparing GraphQL schemas

Capabilities

Core Execution

Main entry point for executing GraphQL operations against schemas with support for variables, context, and custom resolvers.

function graphql(args: GraphQLArgs): Promise<ExecutionResult>;
function graphqlSync(args: GraphQLArgs): 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>>;
}

interface ExecutionResult {
  errors?: ReadonlyArray<GraphQLError>;
  data?: { [key: string]: unknown } | null;
  extensions?: { [key: string]: unknown };
}

Core Execution

Type System

Comprehensive type system for building GraphQL schemas including scalar types, object types, interfaces, unions, enums, and input types with full introspection support.

class GraphQLSchema {
  constructor(config: GraphQLSchemaConfig);
}

class GraphQLObjectType<TSource = any, TContext = any> {
  constructor(config: GraphQLObjectTypeConfig<TSource, TContext>);
}

class GraphQLScalarType<TInternal = any, TExternal = any> {
  constructor(config: GraphQLScalarTypeConfig<TInternal, TExternal>);
}

// Built-in scalar types
const GraphQLString: GraphQLScalarType;
const GraphQLInt: GraphQLScalarType;
const GraphQLFloat: GraphQLScalarType;
const GraphQLBoolean: GraphQLScalarType;
const GraphQLID: GraphQLScalarType;

Type System

Language Processing

Parser, lexer, and AST manipulation tools for working with GraphQL documents including syntax analysis, pretty printing, and visitor patterns.

function parse(source: string | Source, options?: ParseOptions): DocumentNode;
function print(ast: ASTNode): string;
function visit(root: ASTNode, visitor: ASTVisitor): any;

interface DocumentNode extends ASTNode {
  readonly kind: Kind.DOCUMENT;
  readonly definitions: ReadonlyArray<DefinitionNode>;
}

interface ASTVisitor {
  readonly [key: string]: ASTVisitFn | { readonly enter?: ASTVisitFn; readonly leave?: ASTVisitFn };
}

Language Processing

Execution Engine

Runtime execution system for GraphQL operations with support for async resolvers, subscriptions, and custom field resolution strategies.

function execute(args: ExecutionArgs): PromiseOrValue<ExecutionResult>;
function executeSync(args: ExecutionArgs): ExecutionResult;
function subscribe(args: ExecutionArgs): Promise<AsyncIterator<ExecutionResult> | ExecutionResult>;

function defaultFieldResolver(
  source: any,
  args: any,
  contextValue: any,
  info: GraphQLResolveInfo
): any;

Execution Engine

Validation System

Complete validation system implementing all GraphQL specification rules with extensible validation context and custom rule support.

function validate(
  schema: GraphQLSchema,
  documentAST: DocumentNode,
  rules?: ReadonlyArray<ValidationRule>
): ReadonlyArray<GraphQLError>;

const specifiedRules: ReadonlyArray<ValidationRule>;
const recommendedRules: ReadonlyArray<ValidationRule>;

class ValidationContext {
  constructor(schema: GraphQLSchema, ast: DocumentNode, typeInfo: TypeInfo);
}

Validation System

Error Handling

Comprehensive error system with source location tracking, path information, and response formatting for GraphQL errors.

class GraphQLError extends Error {
  constructor(
    message: string,
    options?: GraphQLErrorOptions
  );
  
  readonly locations?: ReadonlyArray<SourceLocation>;
  readonly path?: ReadonlyArray<string | number>;
  readonly source?: Source;
  readonly positions?: ReadonlyArray<number>;
  readonly originalError?: Error;
  readonly extensions?: GraphQLErrorExtensions;
}

function formatError(error: GraphQLError): GraphQLFormattedError;
function printError(error: GraphQLError): string;

Error Handling

Schema Utilities

Tools for building schemas from SDL, introspection, extension, comparison, and various schema manipulation operations.

function buildSchema(source: string | Source, options?: BuildSchemaOptions): GraphQLSchema;
function buildASTSchema(documentAST: DocumentNode, options?: BuildSchemaOptions): GraphQLSchema;
function buildClientSchema(introspection: IntrospectionQuery, options?: BuildSchemaOptions): GraphQLSchema;
function extendSchema(schema: GraphQLSchema, documentAST: DocumentNode, options?: BuildSchemaOptions): GraphQLSchema;

function getIntrospectionQuery(options?: IntrospectionOptions): string;
function introspectionFromSchema(schema: GraphQLSchema, options?: IntrospectionOptions): IntrospectionQuery;

function printSchema(schema: GraphQLSchema): string;
function lexicographicSortSchema(schema: GraphQLSchema): GraphQLSchema;

Schema Utilities

Types

Core Types

type Maybe<T> = T | null | undefined;
type PromiseOrValue<T> = Promise<T> | T;
type ObjMap<T> = { [key: string]: T };

interface Source {
  readonly body: string;
  readonly name: string;
  readonly locationOffset: Location;
}

interface Location {
  readonly line: number;
  readonly column: number;
}

interface SourceLocation {
  readonly line: number;
  readonly column: number;
}