# Biblioteca Azion KV

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

A biblioteca **KV** fornece uma interface similar ao Redis para interagir com o **KV Store** da Azion. Esta biblioteca oferece padrões familiares do Redis, incluindo tratamento de erros baseado em eventos, gerenciamento de conexão e operações de hash.

<DocButton href="/pt-br/documentacao/produtos/azion-lib/visao-geral/" label="Ir para Visão Geral das Bibliotecas Azion" kind="secondary" size="medium" />

Você pode interagir com a API usando um `client` com padrões de encadeamento similares ao Redis. O cliente suporta tanto provedores nativos do runtime quanto baseados em API com detecção automática.

Este é um exemplo de como um arquivo `.env` com suas variáveis de ambiente pode parecer:

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

| Variável | Descrição |
|----------|-----------|
| `AZION_TOKEN` | Seu token de API da Azion. |
| `AZION_DEBUG` | Habilitar modo de depuração (true/false). |

---

## Uso

### Criando um cliente

Crie um cliente KV usando o padrão de encadeamento similar ao Redis:

```typescript
import { createClient } from 'azion/kv';
import type { KVClient } from 'azion/kv';

// Criar um cliente com padrão de encadeamento similar ao Redis
const client: KVClient = await createClient()
  .on('error', (err) => console.log('Erro do Cliente KV', err))
  .connect();
```

Você também pode criar um cliente com opções personalizadas:

```typescript
import { createClient } from 'azion/kv';

const client = await createClient({
  namespace: 'meu-namespace',
  apiToken: 'meu-token',
})
  .on('error', (err) => console.error('Erro KV:', err))
  .connect();
```

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `options` | `KVClientOptions` (opcional) | Opções de configuração para o cliente. |
| `options.namespace` | `string` (opcional) | O namespace a ser usado para operações KV. |
| `options.apiToken` | `string` (opcional) | O token de API para autenticação. |

**Retorno**:

| Tipo de Retorno | Descrição |
|-----------------|-----------|
| `KVClient` | Um objeto cliente com métodos para interagir com o KV Store. |

---

### `get`

Recupera um valor pela chave.

```typescript
const value = await client.get('minha-chave');
console.log(value);
```

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `key` | `string` | A chave a ser recuperada. |
| `options` | `KVGetOptions` (opcional) | Opções para a operação de get. |

**Retorno**:

| Tipo de Retorno | Descrição |
|-----------------|-----------|
| `Promise<KVGetValue \| null>` | O valor ou null se não encontrado. |

---

### `getWithMetadata`

Recupera um valor junto com seus metadados.

```typescript
const result = await client.getWithMetadata('minha-chave');
console.log(result.value, result.metadata);
```

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `key` | `string` | A chave a ser recuperada. |
| `options` | `KVGetOptions` (opcional) | Opções para a operação de get. |

**Retorno**:

| Tipo de Retorno | Descrição |
|-----------------|-----------|
| `Promise<KVGetResult>` | Um objeto contendo o valor e os metadados. |

---

### `set`

Armazena um valor com expiração e metadados opcionais.

```typescript
// Set simples
await client.set('minha-chave', 'meu-valor');

// Set com opções
await client.set('minha-chave', 'meu-valor', {
  expiration: {
    type: 'EX',
    value: 10, // 10 segundos
  },
  metadata: { userId: '123' },
});
```

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `key` | `string` | A chave a ser armazenada. |
| `value` | `KVValue` | O valor a ser armazenado. |
| `options` | `KVSetOptions` (opcional) | Opções para a operação de set. |

O objeto `KVSetOptions` suporta as seguintes propriedades:

| Opção | Tipo | Descrição |
|-------|------|-----------|
| `expiration` | `object` (opcional) | Configuração de expiração. |
| `expiration.type` | `'EX' \| 'PX' \| 'EXAT' \| 'PXAT'` | Tipo de expiração. |
| `expiration.value` | `number` | Valor de expiração. |
| `metadata` | `object` (opcional) | Metadados a serem associados à chave. |

**Tipos de expiração**:

| Tipo | Descrição |
|------|-----------|
| `EX` | Expira em segundos a partir de agora. |
| `PX` | Expira em milissegundos a partir de agora. |
| `EXAT` | Expira em um timestamp Unix específico (segundos). |
| `PXAT` | Expira em um timestamp Unix específico (milissegundos). |

**Retorno**:

| Tipo de Retorno | Descrição |
|-----------------|-----------|
| `Promise<void>` | Resolve quando a operação é concluída. |

---

### `delete` / `del`

Exclui uma chave do armazenamento.

```typescript
await client.delete('minha-chave');
// ou
await client.del('minha-chave');
```

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `key` | `string` | A chave a ser excluída. |

**Retorno**:

| Tipo de Retorno | Descrição |
|-----------------|-----------|
| `Promise<void>` | Resolve quando a operação é concluída. |

---

### Operações de hash

A biblioteca KV suporta operações de hash similares ao Redis para armazenar pares campo-valor.

#### `hSet` / `HSET`

Define um campo em um hash.

```typescript
await client.hSet('minha-chave', 'campo', 'valor');
await client.HSET('minha-chave', 'campo', 'valor');
```

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `key` | `string` | A chave do hash. |
| `field` | `string` | O nome do campo. |
| `value` | `KVValue` | O valor a ser armazenado. |

**Retorno**:

| Tipo de Retorno | Descrição |
|-----------------|-----------|
| `Promise<void>` | Resolve quando a operação é concluída. |

#### `hGetAll` / `HGETALL`

Obtém todos os campos e valores de um hash.

```typescript
const result = await client.hGetAll('minha-chave');
const result = await client.HGETALL('minha-chave');
```

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `key` | `string` | A chave do hash. |

**Retorno**:

| Tipo de Retorno | Descrição |
|-----------------|-----------|
| `Promise<KVGetValue \| null>` | Os dados do hash ou null se não encontrado. |

#### `hVals` / `HVALS`

Obtém todos os valores de um hash.

```typescript
const result = await client.hVals('minha-chave');
const result = await client.HVALS('minha-chave');
```

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `key` | `string` | A chave do hash. |

**Retorno**:

| Tipo de Retorno | Descrição |
|-----------------|-----------|
| `Promise<KVGetValue[] \| null>` | Um array de valores ou null se não encontrado. |

---

### Gerenciamento de conexão

#### `disconnect` / `quit`

Desconecta do KV store.

```typescript
await client.disconnect();
// ou
await client.quit();
```

**Retorno**:

| Tipo de Retorno | Descrição |
|-----------------|-----------|
| `Promise<void>` | Resolve quando desconectado. |

---

### Detecção de provedor

#### `getProviderType`

Retorna o tipo de provedor atual sendo usado.

```typescript
const providerType = client.getProviderType();
console.log(providerType); // 'native' ou 'api'
```

**Retorno**:

| Tipo de Retorno | Descrição |
|-----------------|-----------|
| `'native' \| 'api'` | O tipo de provedor. |

O cliente detecta automaticamente o ambiente:
- **native**: Usado quando executando no Azion Runtime (Functions).
- **api**: Usado quando executando fora do Azion Runtime (desenvolvimento local, servidores externos).

---

## Tratamento de erros

O cliente KV usa um padrão de tratamento de erros baseado em eventos similar ao Redis:

```typescript
const client = await createClient()
  .on('error', (err) => {
    console.error('Erro do Cliente KV:', err);
    // Trate o erro apropriadamente
  })
  .connect();
```

Você também pode usar try-catch para operações individuais:

```typescript
try {
  const value = await client.get('minha-chave');
} catch (error) {
  console.error('Falha ao obter valor:', error);
}
```

---

## Exemplo completo

```typescript
import { createClient } from 'azion/kv';

async function main() {
  // Criar e conectar cliente
  const client = await createClient({
    namespace: 'meu-namespace',
  })
    .on('error', (err) => console.error('Erro KV:', err))
    .connect();

  // Armazenar um valor com expiração
  await client.set('user:123', JSON.stringify({ name: 'John', role: 'admin' }), {
    expiration: { type: 'EX', value: 3600 }, // 1 hora
    metadata: { createdBy: 'system' },
  });

  // Recuperar o valor
  const userData = await client.get('user:123');
  console.log('Dados do usuário:', userData);

  // Obter com metadados
  const result = await client.getWithMetadata('user:123');
  console.log('Valor:', result.value);
  console.log('Metadados:', result.metadata);

  // Operações de hash
  await client.hSet('config', 'theme', 'dark');
  await client.hSet('config', 'language', 'pt');
  const config = await client.hGetAll('config');
  console.log('Configuração:', config);

  // Verificar tipo de provedor
  console.log('Provedor:', client.getProviderType());

  // Excluir e desconectar
  await client.delete('user:123');
  await client.disconnect();
}

main();
```

---

## Tipos

Estes são os tipos usados pela biblioteca **KV**:

### `KVClient`

A interface principal do cliente para operações KV.

| Método | Parâmetros | Tipo de Retorno | Descrição |
|--------|------------|-----------------|-----------|
| `on` | `event: 'error', handler: (error: Error) => void` | `this` | Registra manipulador de evento de erro (encadeável). |
| `connect` | - | `Promise<this>` | Conecta ao KV store (encadeável). |
| `get` | `key: string, options?: KVGetOptions` | `Promise<KVGetValue \| null>` | Obtém um valor. |
| `getWithMetadata` | `key: string, options?: KVGetOptions` | `Promise<KVGetResult>` | Obtém valor com metadados. |
| `set` | `key: string, value: KVValue, options?: KVSetOptions` | `Promise<void>` | Define um valor. |
| `delete` | `key: string` | `Promise<void>` | Exclui uma chave. |
| `del` | `key: string` | `Promise<void>` | Alias para delete. |
| `disconnect` | - | `Promise<void>` | Desconecta do store. |
| `quit` | - | `Promise<void>` | Alias para disconnect. |
| `hSet` | `key: string, field: string, value: KVValue` | `Promise<void>` | Define campo de hash. |
| `HSET` | `key: string, field: string, value: KVValue` | `Promise<void>` | Alias para hSet. |
| `hGetAll` | `key: string` | `Promise<KVGetValue \| null>` | Obtém todos os campos do hash. |
| `HGETALL` | `key: string` | `Promise<KVGetValue \| null>` | Alias para hGetAll. |
| `hVals` | `key: string` | `Promise<KVGetValue[] \| null>` | Obtém todos os valores do hash. |
| `HVALS` | `key: string` | `Promise<KVGetValue[] \| null>` | Alias para hVals. |
| `getProviderType` | - | `'native' \| 'api'` | Obtém o tipo de provedor atual. |

### `KVClientOptions`

Opções de configuração para o cliente KV.

| Propriedade | Tipo | Descrição |
|-------------|------|-----------|
| `namespace` | `string` (opcional) | O namespace para operações KV. |
| `apiToken` | `string` (opcional) | O token de API para autenticação. |

### `KVSetOptions`

Opções para operações de set.

| Propriedade | Tipo | Descrição |
|-------------|------|-----------|
| `expiration` | `{ type: 'EX' \| 'PX' \| 'EXAT' \| 'PXAT', value: number }` (opcional) | Configuração de expiração. |
| `metadata` | `object` (opcional) | Metadados a serem associados à chave. |

### `KVGetResult`

Resultado da operação getWithMetadata.

| Propriedade | Tipo | Descrição |
|-------------|------|-----------|
| `value` | `KVGetValue \| null` | O valor recuperado. |
| `metadata` | `object \| null` | Os metadados associados. |