Biblioteca Azion KV

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.

Ir para Visão Geral das Bibliotecas Azion

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:

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:

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:

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.

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.

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.

// 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.

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.

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.

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.

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.

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.

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:

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:

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

Exemplo completo

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.

Uso

Criando um cliente

get

getWithMetadata

set

delete / del

Operações de hash

hSet / HSET

hGetAll / HGETALL

hVals / HVALS

Gerenciamento de conexão

disconnect / quit

Detecção de provedor

getProviderType

Tratamento de erros

Exemplo completo

Tipos

KVClient

KVClientOptions

KVSetOptions

KVGetResult

`get`

`getWithMetadata`

`set`

`delete` / `del`

`hSet` / `HSET`

`hGetAll` / `HGETALL`

`hVals` / `HVALS`

`disconnect` / `quit`

`getProviderType`

`KVClient`

`KVClientOptions`

`KVSetOptions`

`KVGetResult`