Sqids é uma pequena biblioteca de código aberto que pode produzir IDs curtos, únicos e com aparência aleatória a partir de números.

A melhor maneira de pensar sobre isso é como um conversor decimal para hexadecimal, mas com alguns recursos extras.

Encurtamento de links, geração de IDs de eventos únicos para registro, geração de IDs para produtos/objetos em um site (como o YouTube faz para vídeos), geração de IDs curtos para mensagens de texto, códigos de confirmação em e-mails, etc.

Quaisquer dados que sejam sensíveis. IDs gerados não são hashes e podem ser decodificados de volta para números. Por exemplo, eles podem não ser uma boa escolha para IDs de usuário, porque uma vez decodificados, podem revelar a contagem de usuários do seu aplicativo.

Sim. Sqids pode codificar um ou muitos números não negativos em um único ID. Não há limite para quantos números você pode codificar, mas há um limite para o tamanho do número que você pode codificar (dependendo da linguagem de implementação).

Isso é útil por várias razões: você pode codificar um carimbo de data/hora UNIX e criar IDs que expiram, ou você pode codificar um número de fragmento de banco de dados junto com uma chave primária e economizar em consultas extras ao banco de dados.

Sim, os IDs gerados são únicos para a entrada e para o alfabeto.

Lembre-se, porém, de que o alfabeto padrão contém letras maiúsculas e minúsculas, então os IDs padrão são sensíveis a maiúsculas e minúsculas.

Sqids não pode codificar números negativos.

O comprimento mínimo do alfabeto é de 3 caracteres.

O alfabeto não pode conter caracteres multibyte.

Sqids não pode gerar IDs de um comprimento específico, apenas no mínimo de um certo comprimento. O intervalo do parâmetro de comprimento mínimo varia entre 0 e 255.

Sqids pode tentar regenerar IDs até o comprimento do alfabeto, menos um.

A biblioteca aceita um alfabeto personalizado a partir do qual pode gerar IDs. Basta pré-embaralhar o alfabeto padrão fornecido.

Por favor, tenha em mente que, com esforço suficiente, alguém poderia fazer engenharia reversa do seu alfabeto embaralhado, então esta não é de forma alguma uma técnica para esconder dados sensíveis.

O alfabeto padrão pode ser encontrado aqui .

Você pode usar qualquer uma das ferramentas online de embaralhamento de strings ou o nosso playground .

Depende do seu caso de uso. Um alfabeto mais curto produzirá IDs mais longos e um alfabeto mais longo produzirá IDs mais curtos. Você pode usar o playground para testar como seus IDs podem parecer.

Sim. Tenha em mente que os IDs gerados ainda são strings e podem começar com um zero.

Não. Sqids não suporta caracteres multibyte para o alfabeto. Isso inclui emojis, bem como muitos outros caracteres.

A biblioteca pode estender os IDs com caracteres aleatórios para fazê-los parecer mais longos. Isso é útil para que não seja tão óbvio se você está codificando um número pequeno como 1 ou um número grande como 1000000.

A decodificação não é afetada.

Sim, a biblioteca aceita um parâmetro de comprimento mínimo que garante que os IDs tenham pelo menos esse comprimento.

Por favor, note que não há garantia de quão longos serão seus IDs - apenas que eles não serão mais curtos do que o comprimento que você especificar.

Até certo ponto.

Definir o comprimento máximo é impossível porque mais cedo ou mais tarde seus IDs vão transbordar com uma entrada grande o suficiente. É por isso que apenas o parâmetro de comprimento mínimo é suportado, e o comprimento exato ou máximo não.

Uma lista de bloqueio pode impedir que certas palavras apareçam nos seus IDs. Isso é benéfico porque os IDs gerados devem aparecer em lugares públicos, como o URL.

Sqids vem com a lista de bloqueio padrão que contém as palavras mais básicas de palavrões e termos inapropriados de várias línguas. É claro que você pode estender essa lista de bloqueio com suas próprias palavras.

A correspondência de palavras na lista de bloqueio não diferencia maiúsculas de minúsculas.

Palavras curtas com menos de 3 caracteres não serão bloqueadas. Palavras com 3 caracteres precisam corresponder exatamente aos IDs. Palavras com 4 caracteres ou mais desencadearão uma correspondência se forem um subconjunto do ID.

Se as palavras da lista de bloqueio contiverem números (leetspeak), elas só desencadearão uma correspondência se estiverem no início ou no final do ID.

A lista de bloqueio padrão contém os palavrões mais comuns e termos inapropriados de várias línguas. Você pode encontrar a lista completa aqui .

Quando o ID gerado corresponde a uma palavra na lista de bloqueio, a biblioteca tenta regenerá-lo.

Se todas as tentativas de regenerar o ID falharem, a função de codificação falhará e retornará um erro. O tratamento desse erro fica por conta do usuário.

A melhor maneira de diminuir o número de tentativas de regeneração é ter um alfabeto mais longo, não definir um comprimento mínimo e fornecer uma lista de bloqueio menor. Fornecer uma lista de bloqueio vazia desabilitará completamente a função.

Decodificar IDs geralmente produzirá algum tipo de saída numérica, mas isso não significa necessariamente que o ID seja canônico. Para verificar se o ID é válido, você pode re-codificar os números decodificados e verificar se o ID corresponde.

A razão pela qual isso não é feito automaticamente é que se a lista de bloqueio padrão mudar no futuro, não queremos invalidar automaticamente o ID que foi gerado no passado e que agora pode corresponder a uma nova palavra na lista de bloqueio.

Vamos garantir de atualizar o CHANGELOG se e quando a lista de bloqueio padrão mudar.

Você precisa considerar cenários em que uma nova palavra pode ser adicionada à lista de bloqueio padrão. Nesse caso, re-codificar números pode produzir um ID diferente.

A melhor maneira de garantir que seus IDs permaneçam consistentes em futuras atualizações é fornecer uma lista de bloqueio personalizada, mesmo que seja idêntica à lista de bloqueio padrão atual.

Não, codificar números diferentes produzirá IDs únicos.

No entanto, devido ao design do algoritmo, a decodificação de IDs aleatórios às vezes pode produzir os mesmos números. A melhor maneira de verificar se o ID é canônico é simplesmente re-codificar os números decodificados e verificar se o ID corresponde.

Hashids foi a primeira versão desta biblioteca lançada por volta de 2013. Também produzia IDs curtos, mas usava um método ligeiramente diferente.

Hashids lidava com algumas coisas de maneira diferente.

Não suportava uma lista de bloqueio personalizada, mas dependia das palavras de palavrão mais comuns em inglês. Também usava o parâmetro salt para embaralhar o alfabeto, o que o tornava um pouco confuso, pois a biblioteca não tinha nada a ver com criptografia. Além disso, usava muitos caracteres reservados, o que resultava em IDs mais longos.

Portanto, decidimos fazer um upgrade e rebranding. O algoritmo foi simplificado, algumas funcionalidades foram adicionadas e os repositórios de código estão todos agora em um único local .

O parâmetro salt era usado para embaralhar o alfabeto e nunca foi destinado a estar associado à segurança ou proteção. Ambos Hashids e Sqids funcionam de maneira semelhante à conversão de decimal para hexadecimal, mas com algumas adaptações. Não há criptografia de nenhum tipo, então, para evitar confusão, esse parâmetro foi removido completamente.

Não, Sqids expande a funcionalidade de Hashids e tem objetivos e requisitos de design diferentes; portanto, os IDs gerados não são compatíveis com Hashids.

Como não há compatibilidade entre Hashids e Sqids, é impossível simplesmente substituir Hashids por Sqids.

No entanto, você pode mesclar os dois diferenciando a qual biblioteca cada ID pertence.

Uma das maneiras de fazer isso é pelo comprimento do ID - se estiver mudando para Sqids, você pode fornecer um comprimento mínimo mais alto. Outra maneira é anexar/prepender manualmente um caractere personalizado aos IDs recém-gerados.

Finalmente, você também pode tentar decodificar um ID com Hashids para ver se é válido. Se não for, decodifique e recodifique com Sqids para ver se funciona.

Cada implementação de linguagem neste site links para o repositório original de Hashids, se existir.

Se você deseja apoiar o projeto, agradecemos se estrelar nossos repositórios no Github para ter mais visibilidade.

Se você é um desenvolvedor e não vê uma implementação de Sqids para uma linguagem específica, ajude-nos a converter a biblioteca. O mesmo vale para uma linguagem de programação que não está listada.

Se você encontrar um bug na especificação ou em uma das implementações, crie um problema ou um pull request com uma correção sugerida no repositório apropriado.

Se você fala várias línguas, podemos usar sua ajuda para ajustar a lista de bloqueio e ajustar as traduções do site se encontrar algum problema.

Por fim, se você tem experiência com Hashids/Sqids, ajude a guiar nossa comunidade respondendo a quaisquer perguntas que alguém possa ter.

Se você gostaria de portar Sqids para uma das seguintes linguagens (ou uma nova não listada aqui):

D , Io , Raku , Smalltalk , T-SQL , Tcl , VBA

Faça um fork do repositório oficial para sua própria conta do Github e implemente a especificação junto com todos os testes. Você pode reutilizar qualquer um dos READMEs existentes (exemplo ).

Assim que a biblioteca estiver pronta, crie um pull request. Depois de aceito, atualizaremos o site.

Se o repositório não tiver mantenedores ativos, ficaríamos felizes em convidá-lo para gerenciar o repositório e se tornar um mantenedor oficial.