# Azion `Purge` library

import DocButton from '~/components/webkit/DocButton.vue';

The **Purge** library provides methods to interact with the **Cache Purge** API, allowing you to purge URLs, cache keys, and wildcard expressions from the cache. This client is configurable and supports both debug mode and environment variable-based configuration.

<DocButton href="/en/documentation/products/azion-lib/overview/" label="Go to Azion Libraries Overview" kind="secondary" size="medium" />

You can interact with the API using a `client` or calling the methods directly from the library. When making direct calls, you can use the environment variables to configure the `client` without passing the token and debug parameters directly.

This is an example of how a `.env` file with your environment variables may look like:

```sh
AZION_TOKEN=<your-api-token>
AZION_DEBUG=true
```

| Variable | Description |
|----------|-------------|
| `AZION_TOKEN` | Your Azion API token. |
| `AZION_DEBUG` | Enable debug mode (true/false). |

:::tip
Setting `AZION_DEBUG` to `true` enables **debug mode**. This mode provides detailed logging of the API requests and responses.
:::

If you want to create a specific `client` for interacting with **Purge**, do it by calling the `createClient` method from the library:

```typescript
import { createClient } from 'azion/purge';
import type { AzionPurgeClient, AzionPurgeResponse, AzionPurge } from 'azion/purge';

const client: AzionPurgeClient = createClient({ token: 'your-api-token', options: { debug: true } });

const { data: purgeURLResponse, error }: AzionPurgeResponse<AzionPurge> = await client.purgeURL([
  'http://www.domain.com/path/image.jpg',
]);
if (purgeURLResponse) {
  console.log('Purge successful:', purgeURLResponse);
} else {
  console.error('Purge failed', error);
}
```

The `createClient` method has the following **parameters** and **return value**:

**Parameters**:

| Parameter | Type | Description |
|-----------|------|-------------|
| `config` | `Partial<{ token: string; options?: OptionsParams }>` | Configuration options for the Purge client. |

**Returns**:

| Return Type | Description |
|-------------|-------------|
| `AzionPurgeClient` | An object with methods to interact with Purge. |

:::note
In the following examples, the methods are called directly without the creation of a `client`. For more information on how to interact with services and products using a `client`, check the [Azion Lib Client documentation](/en/documentation/products/azion-lib/client/).
:::

---

## Usage

### `purgeURL`

Purges a URL from the Cache.

Example:

```typescript
import { purgeURL } from 'azion/purge';
import type { AzionPurgeResponse, AzionPurge } from 'azion/purge';

const url: string[] = ['http://www.domain.com/path/image.jpg'];
const { data: response, error }: AzionPurgeResponse<AzionPurge> = await purgeURL(url, { debug: true });
if (response) {
  console.log('Purge successful:', response);
} else {
  console.error('Purge failed', error);
}
```

**Parameters**:

| Parameter | Type | Description |
|-----------|------|-------------|
| `url` | `string[]` | URL(s) to purge. |
| `options` | `AzionClientOptions` (optional) | Client options including debug mode. |

**Returns**:

| Return Type | Description |
|-------------|-------------|
| `Promise<AzionPurgeResponse<AzionPurge>>` | The purge response or error in case of failure. |

### `purgeCacheKey`

Purges a cache key from the cache.

Example:

```typescript
import { purgeCacheKey } from 'azion/purge';
import type { AzionPurgeResponse, AzionPurge } from 'azion/purge';

const cacheKey: string[] = ['http://www.domain.com/path/image.jpg'];
const { data: response, error }: AzionPurgeResponse<AzionPurge> = await purgeCacheKey(cacheKey, { debug: true });
if (response) {
  console.log('Purge successful:', response);
} else {
  console.error('Purge failed', error);
}
```

**Parameters**:

| Parameter | Type | Description |
|-----------|------|-------------|
| `cacheKey` | `string[]` | Cache key(s) to purge. |
| `options` | `AzionClientOptions` (optional) | Client options including debug mode. |

**Returns**:

| Return Type | Description |
|-------------|-------------|
| `Promise<AzionPurgeResponse<AzionPurge>>` | The purge response or error in case of failure. |

### `purgeWildCard`

Purges using a wildcard expression from the cache.

Example:

```typescript
import { purgeWildCard } from 'azion/purge';
import type { AzionPurgeResponse, AzionPurge } from 'azion/purge';

const wildcard: string[] = ['http://www.domain.com/path/image.jpg*'];
const { data: response, error }: AzionPurgeResponse<AzionPurge> = await purgeWildCard(wildcard, { debug: true });
if (response) {
  console.log('Purge successful:', response);
} else {
  console.error('Purge failed', error);
}
```

**Parameters**:

| Parameter | Type | Description |
|-----------|------|-------------|
| `wildcard` | `string[]` | Wildcard expression(s) to purge. |
| `options` | `AzionClientOptions` (optional) | Client options including debug mode. |

**Returns**:

| Return Type | Description |
|-------------|-------------|
| `Promise<AzionPurgeResponse<AzionPurge>>` | The purge response or error in case of failure. |

---

## Types

This section defines the various types and interfaces used in the **Purge** library.

### `ClientConfig`

Configuration options for the Purge client.

| Parameter | Type | Description |
|-----------|------|-------------|
| `token` | `string` (optional) | Your Azion API token. |
| `options` | `AzionClientOptions` (optional) | Additional options for the client. |

### `PurgeClient`

An object with methods to interact with Purge.

| Method | Parameters | Return Type |
|--------|------------|-------------|
| `purgeURL` | `urls: string[]`, `options?: AzionClientOptions` | `Promise<AzionPurgeResponse<AzionPurge>>` |
| `purgeCacheKey` | `cacheKeys: string[]`, `options?: AzionClientOptions` | `Promise<AzionPurgeResponse<AzionPurge>>` |
| `purgeWildCard` | `wildcards: string[]`, `options?: AzionClientOptions` | `Promise<AzionPurgeResponse<AzionPurge>>` |

### `Purge`

The response object from a purge request.

| Property | Type | Description |
|----------|------|-------------|
| `state` | `executed` | 'pending'` | The state of the purge request. |
| `items` | `string[]` | The items that were purged. |