Documentação do Sift para Roblox: Guia de Configuração e Padrões de API

O Sift é uma biblioteca de dados imutáveis projetada para desenvolvimento em Luau e Roblox. Em vez de alterar uma tabela diretamente, um utilitário imutável cria e retorna um valor atualizado. Essa abordagem pode facilitar o rastreamento de alterações de estado, especialmente em sistemas que gerenciam dados de jogadores, estado da interface, inventários ou configurações replicadas.

A biblioteca está intimamente associada a operações com dicionários e coleções. Seu design é fortemente influenciado pelo Llama, enquanto sua implementação utiliza tipos nativos do Luau em vez de depender da verificação de tipos em tempo de execução. Essa distinção é importante ao criar um projeto: tipagem estática e validação são responsabilidades separadas, portanto as equipes devem decidir como desejam validar os dados recebidos.

Um bom ponto de partida é o repositório do Sift no GitHub. Ele contém notas de instalação, informações sobre versões, exemplos e links para a documentação gerada.

Para que o Sift é mais indicado

O Sift é mais útil quando seu código transforma repetidamente dados estruturados sem querer que todos os sistemas alterem a mesma referência de tabela. Exemplos comuns incluem:

• Criar um novo perfil de jogador a partir de várias fontes de dados.
• Mesclar configurações padrão com preferências salvas.
• Remover entradas sem chamar table.remove ou atribuir nil manualmente.
• Atualizar o estado da interface de maneira previsível.
• Compartilhar utilitários de coleções entre bases de código em Luau e roblox-ts.

Contexto importante do projeto

A biblioteca é um utilitário de código aberto, não uma experiência do Roblox ou um sistema de gameplay. Ela não fornece mapas, personagens, mecânicas de combate, missões ou recursos de progressão. Seu papel é ajudar desenvolvedores a estruturar e transformar dados dentro de projetos do Roblox.

O repositório identifica o Sift como licenciado sob MIT e oferece vários caminhos de distribuição. No entanto, o status atual de manutenção deve ser revisado antes da adoção. Uma equipe pode optar por fixar uma versão conhecida, inspecionar o código-fonte ou manter um fork caso seja necessário suporte de longo prazo.

O Sift pode ser adicionado a um projeto do Roblox por meio do Wally, do roblox-ts ou de um fluxo manual. Selecione uma rota e mantenha a organização das dependências consistente em toda a equipe. Misturar métodos de instalação sem um motivo claro pode dificultar o controle de versões e a implantação.

Comparação das rotas de instalação

Configuração do Wally

Para um projeto baseado em Wally, adicione o Sift como dependência em wally.toml:

[dependencies]
Sift = "csqrl/sift@x.x.x"

Substitua x.x.x pela versão selecionada para o seu projeto. Em seguida, execute:

wally install

Após a instalação, confirme que o pacote aparece no local esperado e que o mapeamento do Rojo do seu projeto inclui o caminho da dependência. A estrutura exata das pastas depende do modelo do seu projeto, portanto verifique a árvore gerada em vez de presumir que todos os repositórios usam a mesma estrutura.

Configuração do roblox-ts

O Sift inclui compatibilidade com TypeScript e uma API projetada para corresponder à sua contraparte em Luau. Um projeto roblox-ts pode instalar o pacote com:

npm install @rbxts/sift

Uma mesclagem simples de dicionários pode ser semelhante a esta:

import { Dictionary, Sift } from "@rbxts/sift"

const result = Dictionary.merge(
  { a: 1, c: 2 },
  { b: 3, c: Sift.None }
)

O comportamento importante é que o resultado é um novo dicionário. As entradas originais continuam sendo valores separados. Confirme a configuração do compilador e a versão do pacote antes de depender de uma exportação de tipo específica.

As operações com dicionários são o ponto de entrada mais prático para muitos sistemas do Roblox. Um dicionário é uma tabela de chave e valor, como um perfil contendo moedas, configurações e conteúdo desbloqueado. Com atualizações imutáveis, cada operação produz um valor substituto em vez de modificar a tabela compartilhada diretamente.

Objetivos comuns de transformação

O marcador Sift.None é especialmente útil em código baseado em mesclagem. No exemplo documentado, mesclar { a: 1, c: 2 } com { b: 3, c: Sift.None } produz { a: 1, b: 3 }. Isso comunica a exclusão como parte da transformação, em vez de misturar a lógica de exclusão em uma etapa separada de mutação.

const base = {
  displayName: "Builder",
  soundEnabled: true,
  tutorialSeen: true
}

const next = Dictionary.merge(base, {
  soundEnabled: false,
  tutorialSeen: Sift.None
})

O exemplo demonstra duas ideias úteis: uma substituição normal para soundEnabled e uma remoção explícita para tutorialSeen. Sempre teste o comportamento exato do auxiliar em relação à versão instalada pelo seu projeto, especialmente ao migrar de outra biblioteca imutável.

Por que preservar as entradas é importante

A mutação direta pode criar acoplamentos ocultos:

profile.Coins += 50

Qualquer sistema que mantenha a mesma referência da tabela pode observar essa alteração imediatamente. Isso pode ser aceitável em um script pequeno, mas fica mais difícil de entender quando os dados do perfil são compartilhados por sistemas de salvamento, interface, análise e gameplay.

Uma abordagem imutável torna a transição mais deliberada:

local updatedProfile = Dictionary.merge(profile, {
    Coins = profile.Coins + 50,
})

A importação exata do módulo depende da estrutura do seu projeto. A prática principal é calcular updatedProfile como um novo valor e depois passá-lo aos sistemas que precisam do estado atualizado.

Mantenha as transformações pequenas

Evite criar uma única transformação grande que altere partes não relacionadas de um perfil. Operações menores são mais fáceis de testar e revisar:

• Atualize as moedas separadamente das configurações.
• Mescle os padrões do servidor antes de aplicar as preferências do jogador.
• Remova campos temporários antes de salvar.
• Mantenha o estado exclusivo da interface fora dos dados persistentes do perfil.
• Dê nome aos valores intermediários quando uma transformação tiver várias etapas.

O Sift foi projetado para oferecer suporte a fluxos de trabalho em Luau e roblox-ts. A API conceitual deve permanecer semelhante, mas as ferramentas ao redor são diferentes. Projetos em Luau normalmente usam Wally e Rojo, enquanto projetos em roblox-ts usam npm e compilação TypeScript.

Escolhendo entre Luau e TypeScript

Testando o comportamento imutável

Um teste útil deve verificar tanto o resultado quanto a entrada original:

local original = {
    Coins = 100,
    Rank = 2,
}

local updated = Dictionary.merge(original, {
    Coins = 150,
})

assert(updated.Coins == 150)
assert(original.Coins == 100)

Esse teste é intencionalmente pequeno. Ele confirma a propriedade mais importante: o valor atualizado contém os novos dados enquanto o original permanece inalterado. Amplie a suíte de testes para dicionários aninhados, chaves ausentes, marcadores de exclusão e arrays usados pela sua aplicação.

Uma dependência faz parte da superfície técnica do seu projeto. Antes de usar o Sift em um novo sistema de produção, revise a atividade do repositório, o histórico de versões, a licença, a disponibilidade do pacote e a compatibilidade com a sua ferramenta atual do Roblox.

Checklist de revisão da dependência

Regras práticas de engenharia

1. Não altere o estado compartilhado acidentalmente. Trate as tabelas de perfil e configuração como valores que devem ser substituídos deliberadamente.
2. Mantenha limites claros entre os pacotes. Uma biblioteca utilitária deve transformar dados, enquanto os sistemas de persistência e rede devem assumir suas respectivas responsabilidades.
3. Valide nos limites. Tipos estáticos não podem garantir que os dados salvos ou as entradas remotas tenham o formato esperado.
4. Prefira valores intermediários explícitos. Nomes como mergedDefaults, playerSettings e nextProfile tornam as transformações mais fáceis de inspecionar.
5. Teste o comportamento de exclusão. Uma chave ausente, um valor nil e Sift.None podem ter significados diferentes em uma operação de mesclagem.
6. Documente a versão escolhida. Isso é especialmente importante quando o projeto pode ser mantido por colaboradores que não selecionaram a dependência original.

Estrutura de documentação sugerida

A documentação gerada e vinculada pelo ecossistema do projeto pode ajudar com assinaturas exatas, enquanto o repositório continua sendo o melhor lugar para revisar o código-fonte, as versões e as informações de licenciamento. Evite copiar exemplos sem verificar se a sintaxe corresponde à versão instalada no seu projeto.