Language Processing

/**
 * Parse a GraphQL document into an AST
 * @param source - GraphQL document string or Source object
 * @param options - Parsing options
 * @returns DocumentNode AST
 */
function parse(source: string | Source, options?: ParseOptions): DocumentNode;

/**
 * Parse a GraphQL value into an AST
 * @param source - GraphQL value string or Source object  
 * @param options - Parsing options
 * @returns ValueNode AST
 */
function parseValue(source: string | Source, options?: ParseOptions): ValueNode;

/**
 * Parse a constant GraphQL value into an AST
 * @param source - GraphQL constant value string or Source object
 * @param options - Parsing options  
 * @returns ConstValueNode AST
 */
function parseConstValue(source: string | Source, options?: ParseOptions): ConstValueNode;

/**
 * Parse a GraphQL type into an AST
 * @param source - GraphQL type string or Source object
 * @param options - Parsing options
 * @returns TypeNode AST
 */
function parseType(source: string | Source, options?: ParseOptions): TypeNode;

interface ParseOptions {
  /** Disable location information in AST nodes */
  noLocation?: boolean;
  /** Allow legacy SDL syntax for empty fields */
  allowLegacySDLEmptyFields?: boolean;  
  /** Allow legacy SDL syntax for implements interfaces */
  allowLegacySDLImplementsInterfaces?: boolean;
  /** Enable experimental fragment variables feature */
  experimentalFragmentVariables?: boolean;
}

import { parse, parseValue, parseType } from "graphql";

// Parse a complete GraphQL document
const document = parse(`
  query GetUser($id: ID!) {
    user(id: $id) {
      id
      name
      posts {
        title
        content
      }
    }
  }
`);

// Parse just a value
const value = parseValue(`"hello world"`);
const listValue = parseValue(`[1, 2, 3]`);
const objectValue = parseValue(`{ name: "John", age: 30 }`);

// Parse just a type
const type = parseType(`[String!]!`);
const complexType = parseType(`User`);

// Parse with options
const documentNoLoc = parse(source, { noLocation: true });

/**
 * Convert an AST node back to GraphQL string representation
 * @param ast - Any AST node
 * @returns GraphQL syntax string
 */
function print(ast: ASTNode): string;

import { parse, print } from "graphql";

const document = parse(`
  query GetUser {
    user {
      id
      name
    }
  }
`);

// Print the entire document
const printed = print(document);
console.log(printed);
// query GetUser {
//   user {
//     id
//     name
//   }
// }

// Print individual nodes
const operation = document.definitions[0];
const operationString = print(operation);

/**
 * Visit AST nodes using the visitor pattern
 * @param root - Root AST node to start traversal
 * @param visitor - Visitor object with enter/leave functions
 * @returns Transformed AST or other value
 */
function visit(root: ASTNode, visitor: ASTVisitor): any;

/**
 * Combine multiple visitors into a single parallel visitor
 * @param visitors - Array of visitor objects
 * @returns Combined visitor
 */
function visitInParallel(visitors: ReadonlyArray<ASTVisitor>): ASTVisitor;

/**
 * Break constant to stop visitor traversal
 */
const BREAK: symbol;

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

type ASTVisitFn = (
  node: ASTNode,
  key: string | number | undefined,
  parent: ASTNode | ReadonlyArray<ASTNode> | undefined,
  path: ReadonlyArray<string | number>,
  ancestors: ReadonlyArray<ASTNode | ReadonlyArray<ASTNode>>
) => any;

import { parse, visit, print, Kind } from "graphql";

const document = parse(`
  query GetUser {
    user {
      id
      name
      email
    }
  }
`);

// Simple visitor to collect field names
const fieldNames: string[] = [];
visit(document, {
  Field(node) {
    fieldNames.push(node.name.value);
  }
});
console.log(fieldNames); // ['user', 'id', 'name', 'email']

// Transform AST - remove email field
const transformed = visit(document, {
  Field(node) {
    if (node.name.value === 'email') {
      return null; // Remove this field
    }
  }
});

// Visitor with enter/leave
visit(document, {
  Field: {
    enter(node) {
      console.log(`Entering field: ${node.name.value}`);
    },
    leave(node) {
      console.log(`Leaving field: ${node.name.value}`);
    }
  }
});

// Stop traversal with BREAK
visit(document, {
  Field(node) {
    if (node.name.value === 'user') {
      return BREAK; // Stop visiting this branch
    }
  }
});

/**
 * Source document representation
 */
class Source {
  constructor(body: string, name?: string, locationOffset?: Location);
  
  readonly body: string;
  readonly name: string;
  readonly locationOffset: Location;
}

/**
 * Location in source document
 */
interface Location {
  readonly start: number;
  readonly end: number;
  readonly startToken?: Token;
  readonly endToken?: Token;
  readonly source?: Source;
}

/**
 * Source location with line and column
 */
interface SourceLocation {
  readonly line: number;
  readonly column: number;
}

/**
 * Get line and column for a position in source
 * @param source - Source document
 * @param position - Character position
 * @returns Line and column information
 */
function getLocation(source: Source, position: number): SourceLocation;

/**
 * Print location information
 * @param location - Location object
 * @returns Formatted location string
 */
function printLocation(location: Location): string;

/**
 * Print source location with context
 * @param source - Source document
 * @param position - Character position
 * @returns Formatted source location with context
 */
function printSourceLocation(source: Source, position: number): string;

/**
 * GraphQL lexer for tokenizing source text
 */
class Lexer {
  constructor(source: Source);
  
  readonly source: Source;
  lastToken: Token;
  token: Token;
  
  /** Advance to next token */
  advance(): Token;
  /** Look ahead to next token without advancing */
  lookahead(): Token;
}

/**
 * Lexical token
 */
interface Token {
  readonly kind: TokenKindEnum;
  readonly start: number;
  readonly end: number;
  readonly line: number;
  readonly column: number;
  readonly value?: string;
  readonly prev?: Token;
  readonly next?: Token;
}

enum TokenKind {
  SOF = '<SOF>',
  EOF = '<EOF>',
  BANG = '!',
  DOLLAR = '$',
  AMP = '&',
  PAREN_L = '(',
  PAREN_R = ')',
  SPREAD = '...',
  COLON = ':',
  EQUALS = '=',
  AT = '@',
  BRACKET_L = '[',
  BRACKET_R = ']',
  BRACE_L = '{',
  BRACE_R = '}',
  PIPE = '|',
  NAME = 'Name',
  INT = 'Int',
  FLOAT = 'Float',
  STRING = 'String',
  BLOCK_STRING = 'BlockString',
  COMMENT = 'Comment'
}

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

type DefinitionNode = 
  | ExecutableDefinitionNode
  | TypeSystemDefinitionNode
  | TypeSystemExtensionNode;

type ExecutableDefinitionNode = 
  | OperationDefinitionNode
  | FragmentDefinitionNode;

interface OperationDefinitionNode extends ASTNode {
  readonly kind: Kind.OPERATION_DEFINITION;
  readonly operation: OperationTypeNode;
  readonly name?: NameNode;
  readonly variableDefinitions?: ReadonlyArray<VariableDefinitionNode>;
  readonly directives?: ReadonlyArray<DirectiveNode>;
  readonly selectionSet: SelectionSetNode;
}

interface VariableDefinitionNode extends ASTNode {
  readonly kind: Kind.VARIABLE_DEFINITION;
  readonly variable: VariableNode;
  readonly type: TypeNode;
  readonly defaultValue?: ConstValueNode;
  readonly directives?: ReadonlyArray<ConstDirectiveNode>;
}

interface VariableNode extends ASTNode {
  readonly kind: Kind.VARIABLE;
  readonly name: NameNode;
}

enum OperationTypeNode {
  QUERY = 'query',
  MUTATION = 'mutation', 
  SUBSCRIPTION = 'subscription'
}

interface SelectionSetNode extends ASTNode {
  readonly kind: Kind.SELECTION_SET;
  readonly selections: ReadonlyArray<SelectionNode>;
}

type SelectionNode = 
  | FieldNode
  | FragmentSpreadNode  
  | InlineFragmentNode;

interface FieldNode extends ASTNode {
  readonly kind: Kind.FIELD;
  readonly alias?: NameNode;
  readonly name: NameNode;
  readonly arguments?: ReadonlyArray<ArgumentNode>;
  readonly directives?: ReadonlyArray<DirectiveNode>;
  readonly selectionSet?: SelectionSetNode;
}

interface ArgumentNode extends ASTNode {
  readonly kind: Kind.ARGUMENT;
  readonly name: NameNode;
  readonly value: ValueNode;
}

type ValueNode = 
  | VariableNode
  | IntValueNode
  | FloatValueNode
  | StringValueNode
  | BooleanValueNode
  | NullValueNode
  | EnumValueNode
  | ListValueNode
  | ObjectValueNode;

interface IntValueNode extends ASTNode {
  readonly kind: Kind.INT;
  readonly value: string;
}

interface StringValueNode extends ASTNode {
  readonly kind: Kind.STRING;
  readonly value: string;
  readonly block?: boolean;
}

interface ListValueNode extends ASTNode {
  readonly kind: Kind.LIST;
  readonly values: ReadonlyArray<ValueNode>;
}

interface ObjectValueNode extends ASTNode {
  readonly kind: Kind.OBJECT;
  readonly fields: ReadonlyArray<ObjectFieldNode>;
}

interface ObjectFieldNode extends ASTNode {
  readonly kind: Kind.OBJECT_FIELD;
  readonly name: NameNode;
  readonly value: ValueNode;
}

function isDefinitionNode(node: ASTNode): node is DefinitionNode;
function isExecutableDefinitionNode(node: ASTNode): node is ExecutableDefinitionNode;
function isSelectionNode(node: ASTNode): node is SelectionNode;
function isValueNode(node: ASTNode): node is ValueNode;
function isConstValueNode(node: ASTNode): node is ConstValueNode;
function isTypeNode(node: ASTNode): node is TypeNode;
function isTypeSystemDefinitionNode(node: ASTNode): node is TypeSystemDefinitionNode;
function isTypeDefinitionNode(node: ASTNode): node is TypeDefinitionNode;
function isTypeSystemExtensionNode(node: ASTNode): node is TypeSystemExtensionNode;
function isTypeExtensionNode(node: ASTNode): node is TypeExtensionNode;