---
sidebar_position: 4
title: GraphQL modules
---

# GraphQL modules

Importing a `.gql` or `.graphql` file produces a module with a single default export.

## <Fn /> Default export {#default-export}

The default export is a **factory function**. You call it (optionally with variables) and it returns an object with `query`, `subscribe`, and `unsubscribe` methods bound to that query.

```ts
(vars?: Record<string, any>) => { query, subscribe, unsubscribe }
```

| Parameter | Type | Description |
|---|---|---|
| `vars` | `Record<string, any>` | Optional. Variables to interpolate into the query — `$varName` tokens are replaced with their values. Strings are quoted; numbers and booleans are inserted as-is. |

### <Fn /> `query` {#gql-query}

```ts
query(): Promise<{ data?: any; errors?: any[] }>
```

Executes a one-shot GraphQL query. Resolves to the full GraphQL envelope. See [`yeet.graph.query`](./yeet-global#yeet-graph-query).

### <Fn /> `subscribe` {#gql-subscribe}

```ts
subscribe(cb: (data: any) => void): string
```

| Parameter | Type | Description |
|---|---|---|
| `cb` | `(data: any) => void` | Called each time new data arrives from the subscription. |

Returns a ticket string. See [`yeet.graph.subscribe`](./yeet-global#yeet-graph-subscribe).

### <Fn /> `unsubscribe` {#gql-unsubscribe}

```ts
unsubscribe(ticket: string): Promise<boolean>
```

| Parameter | Type | Description |
|---|---|---|
| `ticket` | `string` | The ticket returned by `subscribe`. |

Returns `true` if the subscription was found and removed, `false` otherwise. See [`yeet.graph.unsubscribe`](./yeet-global#yeet-graph-unsubscribe).

## Example

```js
import getStatus from './status.graphql';

// One-shot query
const { query } = getStatus({ nodeId: 42 });
const { data, errors } = await query();

// Live subscription
const { subscribe, unsubscribe } = getStatus();
const ticket = subscribe((data) => console.log(data));

// Cancel later
await unsubscribe(ticket);
```