@jumentix/key-value-storage — guia de uso

Responsabilidade no escopo

• Camada: persistência / adaptador de infraestrutura
• Responsável por: porta chave/valor + adapters InMemory/Redis
• Usado com: @jumentix/mutex-service
• Não responsável por: repositórios SQL/documentos, IndexedDB (Cana), SDKs HTTP

O que é

@jumentix/key-value-storage é a porta compartilhada chave/valor para caches, feature flags, blobs de sessão e backends de mutex nos serviços Jumentix. Cada adaptador implementa o mesmo contrato IKeyValueStorageClient: connect, get, set, del e disconnect.

Por que existe

Times júnior não deveriam reimplementar wiring de Redis, doubles em memória para testes e wrapping de resposta em cada app. Uma porta permite começar com InMemory no browser e nos testes unitários e trocar para Redis em servidores Node via configuração de ambiente — sem mudar os call sites.

Pré-requisitos

• Runtime: browser (só InMemory) ou Node/Bun (InMemory ou Redis).
• Para Redis: instância Redis rodando e dependência redis no app consumidor.
• Leitura prévia: Começando.
• Ambiente (Redis): JUMENTIX_KEYVALUESTORAGE_DRIVER=redis mais configuração de conexão documentada no seu deploy.

Glossário

Passos

1. Instalar (< 5 minutos)

bun add @jumentix/key-value-storage

Para Redis em Node, instale também o client Redis que seu deploy usa (versão suportada no README do pacote).

2. Primeiro sucesso — get/set em memória (< 10 minutos)

import { InMemoryKeyValueStorageClient } from '@jumentix/key-value-storage';

const client = InMemoryKeyValueStorageClient.compile();
await client.connect();

const write = await client.set('greeting', 'hello jumentix');
if (write.error) throw write.error;

const read = await client.get('greeting');
console.log(read.result); // 'hello jumentix'

await client.del('greeting');
await client.disconnect();

Verifique o sucesso: read.result === 'hello jumentix' e sem campo error.

3. Fluxo central — compilar por ambiente

Use a factory quando o driver deve seguir a config do deploy:

import { compileKeyValueStorageClient } from '@jumentix/key-value-storage';

// JUMENTIX_KEYVALUESTORAGE_DRIVER=inmemory | redis (padrão: redis)
const client = compileKeyValueStorageClient();
await client.connect();

4. Fluxo central — leituras seguras a erro

Nunca assuma que result existe — sempre trate error:

async function readFlag(client, key: string, fallback = false) {
  const { result, error } = await client.get(key);
  if (error) throw error;
  return result ?? fallback;
}

5. Fluxo central — parear com mutex-service

Locks de mutex são chaves KV sob prefixo configurável. Crie um client KV compartilhado e passe a MutexService.compile (veja o guia mutex-service).

6. Superfície completa — mapa da API

Experimente no playground de docs

### Chave/valor em memória

```ts
const client = api.createInMemory();
await client.connect();

await client.set('ui:selected-category', {
  id: 'work',
  name: 'Work',
  visibleTaskIds: ['task-1', 'task-3']
});
await client.set('ui:last-sort', 'priority-desc');

const selectedCategory = await client.get('ui:selected-category');
const lastSort = await client.get('ui:last-sort');
await client.del('ui:last-sort');
const deletedSort = await client.get('ui:last-sort');
await client.disconnect();

return {
  selectedCategory: selectedCategory.result,
  lastSort: lastSort.result,
  deletedSort: deletedSort.result
};
```

const client = api.createInMemory();
await client.connect();

await client.set('ui:selected-category', {
  id: 'work',
  name: 'Work',
  visibleTaskIds: ['task-1', 'task-3']
});
await client.set('ui:last-sort', 'priority-desc');

const selectedCategory = await client.get('ui:selected-category');
const lastSort = await client.get('ui:last-sort');
await client.del('ui:last-sort');
const deletedSort = await client.get('ui:last-sort');
await client.disconnect();

return {
  selectedCategory: selectedCategory.result,
  lastSort: lastSort.result,
  deletedSort: deletedSort.result
};

O stub do playground expõe API simplificada para demos:

const client = api.createInMemory();
await client.set('greeting', 'hello jumentix');
const value = await client.get('greeting');

Em apps reais, use InMemoryKeyValueStorageClient.compile() e trate ServiceResponse como acima.

Erros comuns

Checklist júnior (“Eu consigo …”)

• Instalar o pacote e executar ciclo in-memory set / get / del.
• Explicar por que todo método retorna ServiceResponse em vez de lançar exceção.
• Escolher InMemory vs Redis para um ambiente e justificar.
• Usar compileKeyValueStorageClient com a env var de driver correta.
• Ler valor com fallback seguro quando a chave não existe.
• Descrever como mutex-service se apoia nesta porta.

Próximo passo

Adicione acesso coordenado com mutex-service e continue a jornada de persistência a partir de Começando.