CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-urql--core

The shared core for the highly customizable and versatile GraphQL client

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

@urql/core

@urql/core is the foundational GraphQL client library that provides a highly customizable and versatile approach to GraphQL operations. It implements a modular exchange system for handling requests, caching, subscriptions, and other GraphQL client concerns, with full TypeScript support and framework-agnostic design.

Package Information

  • Package Name: @urql/core
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @urql/core

Core Imports

import { Client, createClient, gql, cacheExchange, fetchExchange } from "@urql/core";

For CommonJS:

const { Client, createClient, gql, cacheExchange, fetchExchange } = require("@urql/core");

Basic Usage

import { createClient, gql, cacheExchange, fetchExchange } from "@urql/core";

// Create a client
const client = createClient({
  url: "https://api.example.com/graphql",
  exchanges: [cacheExchange, fetchExchange],
});

// Define a query
const GetUserQuery = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      id
      name
      email
    }
  }
`;

// Execute query
const result = await client.query(GetUserQuery, { id: "123" }).toPromise();

if (result.error) {
  console.error("GraphQL Error:", result.error);
} else {
  console.log("User data:", result.data.user);
}

Architecture

@urql/core is built around several key architectural components:

  • Client: Central hub managing GraphQL operations and their state
  • Exchange System: Modular pipeline for processing operations (caching, fetching, debugging, etc.)
  • Operation Flow: Request/response cycle using Wonka streams for reactive programming
  • Type Safety: Full TypeScript integration with strongly typed GraphQL operations
  • Framework Agnostic: Core functionality independent of any specific UI framework

Capabilities

Client Management

Core client creation and configuration for managing GraphQL operations and state.

interface ClientOptions {
  url: string;
  exchanges: Exchange[];
  fetchOptions?: RequestInit | (() => RequestInit);
  fetch?: typeof fetch;
  fetchSubscriptions?: boolean;
  suspense?: boolean;
  requestPolicy?: RequestPolicy;
  preferGetMethod?: boolean | 'force' | 'within-url-limit';
}

function createClient(options: ClientOptions): Client;

Client Management

GraphQL Operations

Execute queries, mutations, and subscriptions with full type safety and reactive streams.

class Client {
  query<Data = any, Variables extends AnyVariables = AnyVariables>(
    query: DocumentInput<Data, Variables>,
    variables: Variables,
    context?: Partial<OperationContext>
  ): OperationResultSource<OperationResult<Data, Variables>>;

  mutation<Data = any, Variables extends AnyVariables = AnyVariables>(
    query: DocumentInput<Data, Variables>,
    variables: Variables,
    context?: Partial<OperationContext>
  ): OperationResultSource<OperationResult<Data, Variables>>;

  subscription<Data = any, Variables extends AnyVariables = AnyVariables>(
    query: DocumentInput<Data, Variables>,
    variables: Variables,
    context?: Partial<OperationContext>
  ): OperationResultSource<OperationResult<Data, Variables>>;
}

GraphQL Operations

Exchange System

Modular pipeline system for handling caching, fetching, debugging, and custom operation processing.

type Exchange = (input: ExchangeInput) => ExchangeIO;
type ExchangeIO = (ops$: Source<Operation>) => Source<OperationResult>;

function cacheExchange(): Exchange;
function fetchExchange(): Exchange; 
function debugExchange(): Exchange;
function subscriptionExchange(options: SubscriptionExchangeOpts): Exchange;
function ssrExchange(params: SSRExchangeParams): SSRExchange;
function composeExchanges(exchanges: Exchange[]): Exchange;

Exchange System

GraphQL Parsing and Utilities

GraphQL document parsing, request creation, utility functions for operation processing, and internal HTTP transport utilities.

function gql<Data = any, Variables extends AnyVariables = AnyVariables>(
  strings: TemplateStringsArray,
  ...interpolations: Array<TypedDocumentNode | DocumentNode | string>
): TypedDocumentNode<Data, Variables>;

function createRequest<Data = any, Variables extends AnyVariables = AnyVariables>(
  query: DocumentInput<Data, Variables>,
  variables: Variables
): GraphQLRequest<Data, Variables>;

function makeOperation<Data = any, Variables extends AnyVariables = AnyVariables>(
  kind: OperationType,
  request: GraphQLRequest<Data, Variables>,
  context: OperationContext
): Operation<Data, Variables>;

Utilities and Parsing

Error Handling

Comprehensive error handling for GraphQL and network errors with detailed error information.

class CombinedError extends Error {
  constructor(params: {
    networkError?: Error;
    graphQLErrors?: readonly GraphQLError[];
    response?: Response;
  });
  networkError?: Error;
  graphQLErrors: GraphQLError[];
  response?: Response;
}

function makeErrorResult<Data = any, Variables extends AnyVariables = AnyVariables>(
  operation: Operation<Data, Variables>,
  error: Error | CombinedError,
  response?: ExecutionResult
): OperationResult<Data, Variables>;

Error Handling

Internal APIs (Advanced)

Low-level HTTP transport utilities for custom exchange development and advanced use cases.

function makeFetchBody<Data = any, Variables extends AnyVariables = AnyVariables>(
  request: Omit<GraphQLRequest<Data, Variables>, 'key'>
): FetchBody;

function makeFetchURL(operation: Operation, body?: FetchBody): string;

function makeFetchOptions(operation: Operation, body?: FetchBody): RequestInit;

function makeFetchSource(
  operation: Operation,
  url: string,
  fetchOptions: RequestInit
): Source<OperationResult>;

Internal APIs

Types

Core Operation Types

type OperationType = 'subscription' | 'query' | 'mutation' | 'teardown';

type RequestPolicy = 
  | 'cache-first' 
  | 'cache-and-network' 
  | 'network-only' 
  | 'cache-only';

type AnyVariables = { [prop: string]: any } | void | undefined;

type DocumentInput<Result = { [key: string]: any }, Variables = { [key: string]: any }> = 
  string | DocumentNode | TypedDocumentNode<Result, Variables>;

Request and Result Types

interface GraphQLRequest<Data = any, Variables extends AnyVariables = AnyVariables> {
  key: number;
  query: DocumentNode | PersistedDocument | TypedDocumentNode<Data, Variables>;
  variables: Variables;
  extensions?: RequestExtensions | undefined;
}

interface OperationResult<Data = any, Variables extends AnyVariables = AnyVariables> {
  operation: Operation<Data, Variables>;
  data?: Data;
  error?: CombinedError;
  extensions?: Record<string, any>;
  stale: boolean;
  hasNext: boolean;
}

Context and Configuration Types

interface OperationContext {
  url: string;
  fetchOptions?: RequestInit | (() => RequestInit);
  fetch?: typeof fetch;
  fetchSubscriptions?: boolean;
  requestPolicy: RequestPolicy;
  preferGetMethod?: boolean | 'force' | 'within-url-limit';
  suspense?: boolean;
  additionalTypenames?: string[];
  meta?: OperationDebugMeta;
  [key: string]: any;
}

interface Operation<Data = any, Variables extends AnyVariables = AnyVariables> 
  extends GraphQLRequest<Data, Variables> {
  readonly kind: OperationType;
  context: OperationContext;
}

Advanced Types

type OperationResultSource<T extends OperationResult> = Source<T> & 
  PromiseLike<T> & {
    toPromise(): Promise<T>;
    subscribe(onResult: (value: T) => void): Subscription;
  };

interface ExecutionResult<Data = any> {
  data?: Data;
  errors?: GraphQLError[];
  extensions?: Record<string, any>;
  incremental?: IncrementalPayload[];
  pending?: { id: string; path: Array<string | number> }[];
}

interface IncrementalPayload {
  id?: string;
  subPath?: Array<string | number>;
  path?: Array<string | number>;
  data?: any;
  errors?: GraphQLError[];
  extensions?: Record<string, any>;
}

interface PersistedDocument {
  documentId: string;
  definitions?: DefinitionNode[];
}

type FileMap = Map<string, File | Blob>;

interface FetchBody {
  query?: string;
  documentId?: string;
  operationName: string | undefined;
  variables: undefined | Record<string, any>;
  extensions: undefined | Record<string, any>;
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@urql/core@6.0.x
Publish Source
CLI
Badge
tessl/npm-urql--core badge