🧮 Gleam BR: Erlang ETS

*Wrapper seguro e tipado (type-safe) em Gleam para o ETS (Erlang Term Storage).*

Uma biblioteca de nível militar construída para trazer o poder do ETS nativo da BEAM para o ecossistema Gleam, sem abrir mão da segurança de tipos e da ergonomia.

*Built-in term storage:*

Este módulo é uma interface para as BIFs (Binary Format Functions) de armazenamento de termos integradas do Erlang. Elas permitem armazenar grandes quantidades de dados em um sistema de tempo de execução Erlang, com tempo de acesso constante aos dados. (No caso de ordered_set, veja abaixo, o tempo de acesso é proporcional ao logaritmo do número de objetos armazenados.)

Os dados são organizados como um conjunto de tabelas dinâmicas, que podem armazenar tuplas. Cada tabela é criada por um processo. Quando o processo termina, a tabela é destruída automaticamente. Cada tabela possui direitos de acesso definidos no momento da criação.

As tabelas são divididas em quatro tipos diferentes: tabelas de índice, tabelas de índice set, orderedsettabelas bagde índice e tabelas de índice duplicatebag. Uma tabela de índice setou orderedsettabela de índice só pode ter um objeto associado a cada chave. Uma tabela de índice bagou duplicatebagtabela de índice pode ter vários objetos associados a cada chave.

Os tempos de inserção e busca em tabelas do tipo table setsão constantes, independentemente do tamanho da tabela. Para tabelas do tipo table bag, duplicate_bago tempo é proporcional ao número de objetos com a mesma chave. Mesmo chaves aparentemente não relacionadas podem fazer com que a busca linear seja ignorada enquanto se procura pela chave de interesse (devido a colisões de hash).

🎯 Por que o gbr_ets existe?

O ETS (Erlang Term Storage) é um banco de dados em memória incrivelmente rápido e poderoso, nativo da máquina virtual Erlang (BEAM). Ele é a base de muitos sistemas de alta concorrência, oferecendo operações de leitura não-bloqueantes (read_concurrency) e escritas atômicas.

No entanto, a utilização do ETS diretamente em Gleam através de chamadas FFI (@external) pode ser perigosa e suja: - O ETS requer Atoms e estruturas de dados específicas do Erlang. - O mapeamento incorreto de tipos Gleam para a FFI do Erlang frequentemente causa crashes de badarg na BEAM. - O uso de tuplas dinâmicas quebra a principal promessa do Gleam: *Type Safety*.

O gbr_ets resolve esse problema abstraindo toda a "fiação pesada" do FFI dentro de código Erlang puro encapsulado, expondo para o desenvolvedor Gleam apenas uma *API limpa, segura e 100% tipada (Custom Types)*.

📦 Instalação

Adicione o gbr_ets ao seu projeto Gleam:

gleam add gbr_ets

🛠️ Como Utilizar

O gbr_ets fornece tipos personalizados (Access, TableType, Option) para garantir que você não cometa erros ao definir as opções da sua tabela.

import gbr_ets
import gleam/dynamic

pub fn main() {
  // 1. Criação da Tabela com Concorrência de Leitura
  // A tabela é tipada, impedindo o uso de atoms brutos ou opções inválidas.
  let table =
    gbr_ets.new(
      name: "minha_tabela_rapida",
      table_type: gbr_ets.Set,
      access: gbr_ets.Public,
      options: [gbr_ets.NamedTable, gbr_ets.ReadConcurrency(True)],
    )

  // 2. Preparação dos Dados (Usando Dynamic para flexibilidade e segurança na ponte FFI)
  let key = dynamic.from("usuario_1")
  let value = dynamic.from(#("João", 30, "Ativo"))

  // 3. Inserção Atômica
  gbr_ets.insert(table, key, value)

  // 4. Consulta (Lookup) Ultra-Rápida
  let result = gbr_ets.lookup(table, key)

  case result {
    [encontrado] -> {
      // Valor encontrado!
      // Use gleam/dynamic para decodificar o valor em seus tipos originais
    }
    [] -> {
      // Chave não existe
    }
    _ -> {
      // Trata outras condições
    }
  }
}

🚦 Quando usar (e quando não usar)

✅ Use o gbr_ets quando: - Você precisa de um *Registry* ou *Cache* super rápido, compartilhado entre vários atores. - Você tem uma situação de *leitura massiva* concorrente onde um Ator com um Dict no estado causaria um gargalo (funil) no sistema. - Precisa de estado compartilhado lock-free com performance na velocidade da memória RAM.

❌ Não use o gbr_ets se: - Você está compilando para o target javascript (ETS só existe na BEAM). *Dica: para JS, use gbr_jsdb.* - O estado não é compartilhado e pertence a um único processo/Ator. Neste caso, manter o estado em um Dict ou variáveis normais e passá-las adiante via funções puras é a maneira mais idiomática e correta no Gleam. - Você está criando tabelas do tipo Bag ou DuplicateBag para armazenar quantidades massivas de objetos sob a mesma chave. (Isso degrada a performance de inserção e leitura, afetando o tempo real do ambiente de execução).

🤝 Contribuindo

Seja bem-vindo(a) à comunidade! O ecossistema gleam-br é construído com carinho para todos. Consulte nosso Guia de Contribuição antes de abrir uma Pull Request.

Desenvolvido por e para a comunidade Gleam. 🚀