or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

ast-extraction.mddirectives.mddocument-transformation.mdfragments.mdindex.mdstore-utilities.mdutility-functions.md
tile.json

index.mddocs/

Apollo Utilities

Apollo Utilities is a TypeScript library that provides essential utilities for working with GraphQL Abstract Syntax Trees (ASTs). It offers comprehensive functions for manipulating fragments, handling directives, transforming documents, extracting AST information, and managing store utilities for caching operations.

Package Information

  • Package Name: apollo-utilities
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install apollo-utilities

Core Imports

import {
  // Directive utilities
  shouldInclude,
  getDirectiveNames,
  hasDirectives,
  // Fragment utilities
  getFragmentQueryDocument,
  // AST extraction
  getOperationDefinition,
  getFragmentDefinitions,
  getMainDefinition,
  // Document transformation
  removeDirectivesFromDocument,
  addTypenameToDocument,
  // Store utilities
  storeKeyNameFromField,
  argumentsObjectFromField,
  isField,
  // Utility functions
  cloneDeep,
  isEqual,
  assign,
  mergeDeep
} from "apollo-utilities";

For CommonJS:

const {
  shouldInclude,
  getOperationDefinition,
  removeDirectivesFromDocument,
  storeKeyNameFromField,
  cloneDeep
} = require("apollo-utilities");

Basic Usage

import { 
  getOperationDefinition, 
  shouldInclude, 
  storeKeyNameFromField,
  addTypenameToDocument 
} from "apollo-utilities";
import { parse } from "graphql";

// Parse a GraphQL query
const query = parse(`
  query GetUser($id: ID!) {
    user(id: $id) @include(if: $showUser) {
      name
      email
    }
  }
`);

// Extract operation definition
const operation = getOperationDefinition(query);
console.log(operation?.operation); // "query"

// Check if a field should be included based on directives
const userField = operation?.selectionSet.selections[0];
const variables = { showUser: true };
const include = shouldInclude(userField, variables);
console.log(include); // true

// Add __typename fields for caching
const queryWithTypename = addTypenameToDocument(query);

// Generate store keys for fields
const field = userField;
const storeKey = storeKeyNameFromField(field, variables);
console.log(storeKey); // "user({"id":"$id"})"

Architecture

Apollo Utilities is organized into several key modules:

  • Directive Module: Functions for handling GraphQL directives (@skip, @include, @client, etc.)
  • Fragment Module: Utilities for working with GraphQL fragments
  • AST Extraction Module: Functions for extracting and analyzing parts of GraphQL documents
  • Document Transformation Module: Functions for modifying and transforming GraphQL documents
  • Store Utils Module: Utilities for generating store keys and handling cached data
  • Utility Modules: General-purpose helper functions for deep cloning, equality checks, merging, etc.

Capabilities

Directive Handling

Functions for working with GraphQL directives including conditional inclusion (@skip/@include), client-side directives (@client), and directive extraction.

function shouldInclude(
  selection: SelectionNode,
  variables?: { [name: string]: any }
): boolean;

function getDirectiveNames(doc: DocumentNode): string[];

function hasDirectives(names: string[], doc: DocumentNode): boolean;

Directive Handling

Fragment Operations

Utilities for manipulating GraphQL fragments and converting them into executable query documents.

function getFragmentQueryDocument(
  document: DocumentNode,
  fragmentName?: string
): DocumentNode;

Fragment Operations

AST Extraction and Analysis

Functions for extracting operations, fragments, and other components from GraphQL documents, plus utilities for analyzing document structure.

function getOperationDefinition(doc: DocumentNode): OperationDefinitionNode | undefined;

function getFragmentDefinitions(doc: DocumentNode): FragmentDefinitionNode[];

function getMainDefinition(
  queryDoc: DocumentNode
): OperationDefinitionNode | FragmentDefinitionNode;

interface FragmentMap {
  [fragmentName: string]: FragmentDefinitionNode;
}

function createFragmentMap(fragments?: FragmentDefinitionNode[]): FragmentMap;

AST Extraction and Analysis

Document Transformation

Functions for modifying GraphQL documents including removing directives, adding __typename fields, and transforming document structure.

function removeDirectivesFromDocument(
  directives: RemoveDirectiveConfig[],
  doc: DocumentNode
): DocumentNode | null;

function addTypenameToDocument(doc: DocumentNode): DocumentNode;

function buildQueryFromSelectionSet(document: DocumentNode): DocumentNode;

interface RemoveDirectiveConfig {
  name?: string;
  test?: (node: DirectiveNode) => boolean;
  remove?: boolean;
}

Document Transformation

Store Utilities

Functions for generating store keys, extracting field arguments, and working with cached data structures in GraphQL clients.

function storeKeyNameFromField(field: FieldNode, variables?: Object): string;

function argumentsObjectFromField(
  field: FieldNode | DirectiveNode,
  variables: Object
): Object;

function isField(selection: SelectionNode): selection is FieldNode;

function valueFromNode(
  node: ValueNode,
  onVariable?: (node: VariableNode) => any
): any;

Store Utilities

Utility Functions

General-purpose utility functions for object manipulation, environment detection, error handling, and data processing.

function cloneDeep<T>(value: T): T;

function isEqual(a: any, b: any): boolean;

function assign(target: any, ...sources: Array<any>): any;

function mergeDeep<T extends any[]>(...sources: T): TupleToIntersection<T>;

function getEnv(): string | undefined;

function isProduction(): boolean;

Utility Functions

Core Types

// Store value types
interface IdValue {
  type: 'id';
  id: string;
  generated: boolean;
  typename: string | undefined;
}

interface JsonValue {
  type: 'json';
  json: any;
}

type StoreValue = 
  | number 
  | string 
  | string[] 
  | IdValue 
  | ListValue 
  | JsonValue 
  | null 
  | undefined 
  | void 
  | Object;

// Directive types
type DirectiveInfo = {
  [fieldName: string]: { [argName: string]: any };
};

type InclusionDirectives = Array<{
  directive: DirectiveNode;
  ifArgument: ArgumentNode;
}>;

// Fragment types
interface FragmentMap {
  [fragmentName: string]: FragmentDefinitionNode;
}

// Configuration types
interface RemoveNodeConfig<N> {
  name?: string;
  test?: (node: N) => boolean;
  remove?: boolean;
}

interface GetNodeConfig<N> {
  name?: string;
  test?: (node: N) => boolean;
}