# @probitas/client-graphql

> Version: 0.6.0

GraphQL client for [Probitas](https://github.com/probitas-test/probitas) scenario testing framework.

This package provides a GraphQL client designed for integration testing of GraphQL APIs.

## Features

- **Query & Mutation**: Full support for GraphQL operations
- **Variables Support**: Pass typed variables to queries and mutations
- **Duration Tracking**: Built-in timing for performance monitoring
- **Error Inspection**: Inspect GraphQL errors and their structure
- **Resource Management**: Implements `AsyncDisposable` for proper cleanup
- **Template Literals**: Re-exports `outdent` for clean multi-line queries

## Installation

```bash
deno add jsr:@probitas/client-graphql
```

## Quick Start

```ts
import { createGraphqlClient, outdent } from "@probitas/client-graphql";

const client = createGraphqlClient({ url: "http://localhost:4000/graphql" });

// Query with variables
const res = await client.query(outdent`
  query GetUser($id: ID!) {
    user(id: $id) { id name email }
  }
`, { id: "123" });
console.log("User:", res.data);

// Mutation
const created = await client.mutation(outdent`
  mutation CreateUser($input: CreateUserInput!) {
    createUser(input: $input) { id name }
  }
`, { input: { name: "Jane", email: "jane@example.com" } });
console.log("Created:", created.data);

await client.close();
```

## Using with `using` Statement

```ts
import { createGraphqlClient } from "@probitas/client-graphql";

await using client = createGraphqlClient({ url: "http://localhost:4000/graphql" });

const res = await client.query(`{ __typename }`);
console.log(res.data);
// Client automatically closed when block exits
```

## Related Packages

| Package | Description |
|---------|-------------|
| [`@probitas/client`](https://jsr.io/@probitas/client) | Core utilities and types |
| [`@probitas/client-http`](https://jsr.io/@probitas/client-http) | HTTP client |

## Links

- [GitHub Repository](https://github.com/probitas-test/probitas-client)
- [Probitas Framework](https://github.com/probitas-test/probitas)


## Classes

### `GraphqlExecutionError`

```typescript
class GraphqlExecutionError extends ClientError
```

Error thrown for GraphQL execution errors.

This error is returned when the GraphQL server processes the request
but returns errors in the response (validation errors, resolver errors, etc.).

**Constructor:**

```typescript
new GraphqlExecutionError(
  errors: readonly GraphqlErrorItem[],
  options?: ErrorOptions,
)
```

**Properties:**

- [readonly] `name`: `string`
- [readonly] `kind`: `"graphql"`
- [readonly] `errors`: `readonly GraphqlErrorItem[]` — GraphQL errors from response

---

### `GraphqlNetworkError`

```typescript
class GraphqlNetworkError extends ClientError
```

Error thrown for network-level failures.

This error indicates that the request could not reach or be processed
by the GraphQL server (connection refused, HTTP errors, etc.).

**Constructor:**

```typescript
new GraphqlNetworkError(message: string, options?: ErrorOptions)
```

**Properties:**

- [readonly] `name`: `string`
- [readonly] `kind`: `"network"`

---

## Interfaces

### `GraphqlErrorItem`

```typescript
interface GraphqlErrorItem
```

GraphQL error item as per GraphQL specification.

**Properties:**

- [readonly] `message`: `string` — Error message
- [readonly] `locations`: `readonly { line: number; column: number }[] | null` — Location(s) in the GraphQL document where the error occurred
- [readonly] `path`: `readonly unknown[] | null` — Path to the field that caused the error
- [readonly] `extensions`: `Record<string, unknown> | null` — Additional error metadata

---

### `GraphqlResponseError`

```typescript
interface GraphqlResponseError<T = any> extends GraphqlResponseBase<T>
```

GraphQL response with execution errors.

Note: GraphQL allows partial success where both data and errors are present.
Use data() to access any partial data.

**Properties:**

- [readonly] `processed`: `true`
- [readonly] `ok`: `false`
- [readonly] `error`: `GraphqlExecutionError`
- [readonly] `status`: `number` — HTTP status code.
- [readonly] `headers`: `Headers` — HTTP response headers.
- [readonly] `extensions`: `Record<string, unknown> | null` — Response extensions.
- [readonly] `raw`: `globalThis.Response` — Raw Web standard Response.
- [readonly] `data`: `T | null` — Response data (null if no data, may be partial data with errors).

---

### `GraphqlResponseFailure`

```typescript
interface GraphqlResponseFailure<T = any> extends GraphqlResponseBase<T>
```

Failed GraphQL request (network error, HTTP error, etc.).

The request did not reach GraphQL processing.

**Properties:**

- [readonly] `processed`: `false`
- [readonly] `ok`: `false`
- [readonly] `error`: `GraphqlFailureError`
- [readonly] `extensions`: `null` — Response extensions (always null for failures).
- [readonly] `status`: `null` — HTTP status code (null for network failures).
- [readonly] `headers`: `null` — HTTP response headers (null for failures).
- [readonly] `raw`: `null` — No raw response (request didn't reach server).
- [readonly] `data`: `null` — No data (request didn't reach server).

---

### `GraphqlResponseSuccess`

```typescript
interface GraphqlResponseSuccess<T = any> extends GraphqlResponseBase<T>
```

Successful GraphQL response (no errors).

**Properties:**

- [readonly] `processed`: `true`
- [readonly] `ok`: `true`
- [readonly] `error`: `null`
- [readonly] `status`: `number` — HTTP status code.
- [readonly] `headers`: `Headers` — HTTP response headers.
- [readonly] `extensions`: `Record<string, unknown> | null` — Response extensions.
- [readonly] `raw`: `globalThis.Response` — Raw Web standard Response.
- [readonly] `data`: `T | null` — Response data (null if no data).

---

### `GraphqlOptions`

```typescript
interface GraphqlOptions extends CommonOptions
```

Options for individual GraphQL requests.

**Properties:**

- [readonly] `headers?`: `HeadersInit` — Additional request headers
- [readonly] `operationName?`: `string` — Operation name (for documents with multiple operations)
- [readonly] `throwOnError?`: `boolean` — Whether to throw GraphqlError when response contains errors or request fails.

---

### `GraphqlConnectionConfig`

```typescript
interface GraphqlConnectionConfig extends CommonConnectionConfig
```

GraphQL connection configuration.

Extends CommonConnectionConfig with GraphQL-specific options.

**Properties:**

- [readonly] `protocol?`: `"http" | "https"` — Protocol to use.
- [readonly] `path?`: `string` — GraphQL endpoint path.

---

### `GraphqlClientConfig`

```typescript
interface GraphqlClientConfig extends CommonOptions
```

GraphQL client configuration.

**Properties:**

- [readonly] `url`: `string | GraphqlConnectionConfig` — GraphQL endpoint URL.

Can be a URL string or a connection configuration object.

- [readonly] `headers?`: `HeadersInit` — Default headers for all requests
- [readonly] `wsEndpoint?`: `string` — WebSocket endpoint URL (for subscriptions)
- [readonly] `fetch?`: `fetch` — Custom fetch implementation (for testing/mocking)
- [readonly] `throwOnError?`: `boolean` — Whether to throw GraphqlError when response contains errors or request fails.
Can be overridden per-request via GraphqlOptions.

---

### `GraphqlClient`

```typescript
interface GraphqlClient extends AsyncDisposable
```

GraphQL client interface.

**Properties:**

- [readonly] `config`: `GraphqlClientConfig` — Client configuration

**Methods:**

```typescript
query<TData = any, TVariables = Record<string, any>>(
  query: string,
  variables?: TVariables,
  options?: GraphqlOptions,
): Promise<GraphqlResponse<TData>>
```

Execute a GraphQL query

```typescript
mutation<TData = any, TVariables = Record<string, any>>(
  mutation: string,
  variables?: TVariables,
  options?: GraphqlOptions,
): Promise<GraphqlResponse<TData>>
```

Execute a GraphQL mutation

```typescript
execute<TData = any, TVariables = Record<string, any>>(
  document: string,
  variables?: TVariables,
  options?: GraphqlOptions,
): Promise<GraphqlResponse<TData>>
```

Execute a GraphQL document (query or mutation)

```typescript
subscribe<TData = any, TVariables = Record<string, any>>(
  document: string,
  variables?: TVariables,
  options?: GraphqlOptions,
): AsyncIterable<GraphqlResponse<TData>>
```

Subscribe to a GraphQL subscription via WebSocket

```typescript
close(): Promise<void>
```

Close the client and release resources

---

### `GraphqlResponseSuccessParams`

```typescript
interface GraphqlResponseSuccessParams<T>
```

Parameters for creating a successful GraphqlResponse.

**Properties:**

- [readonly] `url`: `string`
- [readonly] `data`: `T | null`
- [readonly] `extensions`: `Record<string, unknown> | null`
- [readonly] `duration`: `number`
- [readonly] `status`: `number`
- [readonly] `raw`: `globalThis.Response`

---

### `GraphqlResponseErrorParams`

```typescript
interface GraphqlResponseErrorParams<T>
```

Parameters for creating an error GraphqlResponse.

**Properties:**

- [readonly] `url`: `string`
- [readonly] `data`: `T | null`
- [readonly] `error`: `GraphqlExecutionError`
- [readonly] `extensions`: `Record<string, unknown> | null`
- [readonly] `duration`: `number`
- [readonly] `status`: `number`
- [readonly] `raw`: `globalThis.Response`

---

### `GraphqlResponseFailureParams`

```typescript
interface GraphqlResponseFailureParams
```

Parameters for creating a failure GraphqlResponse.

**Properties:**

- [readonly] `url`: `string`
- [readonly] `error`: `GraphqlFailureError`
- [readonly] `duration`: `number`

---

## Functions

### `createGraphqlClient`

```typescript
function createGraphqlClient(config: GraphqlClientConfig): GraphqlClient
```

Create a new GraphQL client instance.

The client provides methods for executing GraphQL queries, mutations,
and subscriptions with automatic error handling and response parsing.


**Parameters:**

- `config`: `GraphqlClientConfig` — - Client configuration including URL and default options

**Returns:** `GraphqlClient`

A new GraphQL client instance


**Example:**

Basic query
```ts
import { createGraphqlClient } from "@probitas/client-graphql";

const client = createGraphqlClient({
  url: "http://localhost:4000/graphql",
});

const response = await client.query(`
  query GetUser($id: ID!) {
    user(id: $id) { id name email }
  }
`, { id: "123" });

console.log(response.data);
await client.close();
```

Using connection config object
```ts
import { createGraphqlClient } from "@probitas/client-graphql";

const client = createGraphqlClient({
  url: { host: "api.example.com", port: 443, protocol: "https" },
});
await client.close();
```

Mutation with error handling
```ts
import { createGraphqlClient } from "@probitas/client-graphql";

const client = createGraphqlClient({ url: "http://localhost:4000/graphql" });

const response = await client.mutation(`
  mutation CreateUser($input: CreateUserInput!) {
    createUser(input: $input) { id }
  }
`, { input: { name: "Alice", email: "alice@example.com" } });

if (response.ok) {
  console.log("Created user:", (response.data as any).createUser.id);
}

await client.close();
```

Using `await using` for automatic cleanup
```ts
import { createGraphqlClient } from "@probitas/client-graphql";

await using client = createGraphqlClient({
  url: "http://localhost:4000/graphql",
});
const response = await client.query(`{ __typename }`);
// Client automatically closed when scope exits
```

---

## Types

### `GraphqlResponse`

```typescript
type GraphqlResponse<T = any> = GraphqlResponseSuccess<T> | GraphqlResponseError<T> | GraphqlResponseFailure<T>
```

GraphQL response union type.

Use `processed` to distinguish between server responses and failures:
- `processed === true`: Server responded (Success or Error)
- `processed === false`: Request failed (Failure)

Use `ok` to check for success:
- `ok === true`: Success (no errors)
- `ok === false`: Error or Failure

---

### `GraphqlFailureError`

```typescript
type GraphqlFailureError = GraphqlNetworkError | AbortError | TimeoutError
```

Error types that indicate the operation was not processed.
These are errors that occur before the request reaches the GraphQL server.

---

## Variables

### `outdent`

```typescript
const outdent: Outdent
```

---

## Related Links

### This Package

- [`GraphqlClient`](https://probitas-test.github.io/documents/api/client-graphql#GraphqlClient)
- [`GraphqlClientConfig`](https://probitas-test.github.io/documents/api/client-graphql#GraphqlClientConfig)
- [`GraphqlConnectionConfig`](https://probitas-test.github.io/documents/api/client-graphql#GraphqlConnectionConfig)
- [`GraphqlErrorItem`](https://probitas-test.github.io/documents/api/client-graphql#GraphqlErrorItem)
- [`GraphqlExecutionError`](https://probitas-test.github.io/documents/api/client-graphql#GraphqlExecutionError)
- [`GraphqlFailureError`](https://probitas-test.github.io/documents/api/client-graphql#GraphqlFailureError)
- [`GraphqlNetworkError`](https://probitas-test.github.io/documents/api/client-graphql#GraphqlNetworkError)
- [`GraphqlOptions`](https://probitas-test.github.io/documents/api/client-graphql#GraphqlOptions)
- [`GraphqlResponse`](https://probitas-test.github.io/documents/api/client-graphql#GraphqlResponse)
- [`GraphqlResponseError`](https://probitas-test.github.io/documents/api/client-graphql#GraphqlResponseError)
- [`GraphqlResponseFailure`](https://probitas-test.github.io/documents/api/client-graphql#GraphqlResponseFailure)
- [`GraphqlResponseSuccess`](https://probitas-test.github.io/documents/api/client-graphql#GraphqlResponseSuccess)

### Other Packages

- [`AbortError`](https://probitas-test.github.io/documents/api/client#AbortError) (@probitas/client)
- [`CommonConnectionConfig`](https://probitas-test.github.io/documents/api/client#CommonConnectionConfig) (@probitas/client)
- [`CommonOptions`](https://probitas-test.github.io/documents/api/client#CommonOptions) (@probitas/client)
- [`Outdent`](https://probitas-test.github.io/documents/api/probitas#Outdent) (@probitas/probitas)
- [`TimeoutError`](https://probitas-test.github.io/documents/api/client#TimeoutError) (@probitas/client)

### Built-in Types

- [`AsyncIterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols)
- [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
- [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)

---

*Last updated: 2026-01-12*