Resolva colisões de slug com um sufixo numérico

Quando o valor está disponível, ele o devolve sem alterações. Quando já está em uso, verifica alternativas numéricas como -2, -3 e as seguintes até encontrar a primeira livre. É um componente pequeno e determinístico para sistemas de publicação, importações, geradores de documentação e qualquer fluxo que precise atribuir uma rota de URL exclusiva sem substituir conteúdo existente por engano.

Preserve o slug desejado sempre que possível

Um bom resolvedor de colisões deve alterar uma URL somente quando for necessário. Envie o valor proposto em desired_slug e informe todos os valores ocupados em used_slugs. As comparações são exatas e diferenciam maiúsculas de minúsculas. Se a proposta não aparecer no conjunto ocupado, o resultado conterá o slug original e indicará que não houve colisão. A ferramenta não converte letras, não remove espaços nas extremidades, não translitera nem troca pontuação, pois essas transformações pertencem à etapa anterior de criação do slug. Separar as responsabilidades evita mudanças inesperadas de URL e torna a saída reproduzível em builds, migrações e testes. Um slug desejado vazio é rejeitado, em vez de virar um sufixo arbitrário, porque isso esconderia um título ausente ou um mapeamento anterior com defeito. Valores duplicados na lista não mudam a resposta; a consulta os consolida naturalmente, então você não precisa limpar a lista para obter um resultado estável.

Escolha o primeiro sufixo numérico disponível

Quando o slug exato está ocupado, a seleção começa em 2, seguindo a convenção comum em que a rota sem sufixo representa o primeiro item e o item seguinte recebe -2. Depois, os candidatos são verificados em ordem crescente: desejado-2, desejado-3, desejado-4 e assim por diante. O processo para no primeiro candidato ausente do conjunto informado. Dessa forma, as lacunas são reutilizadas de maneira previsível. Por exemplo, se report, report-2 e report-4 estiverem ocupados, o retorno será report-3. A comparação considera strings completas; portanto, annual-report e report-old não criam colisão. Uma terminação numérica já existente é tratada como parte literal do valor, sem interpretação ou reescrita: se release-2 for solicitado e estiver ocupado, o primeiro candidato será release-2-2. Esse comportamento evita suposições sobre a intenção e garante que entradas idênticas sempre produzam a mesma saída, sem depender de banco de dados, relógio, aleatoriedade, localidade ou ordem de execução.

Use o resultado com segurança na publicação

Esta capacidade é útil quando sua aplicação já sabe quais slugs estão reservados. Reúna esses valores, envie-os com o slug desejado e use o retorno no novo registro. A resposta também informa se houve colisão e, quando há sufixo, qual número foi selecionado. Esses dados podem alimentar logs, prévias ou mensagens que expliquem por que a URL ficou diferente da proposta inicial. A operação não reserva o valor retornado; sistemas com gravações simultâneas ainda devem impor uma restrição exclusiva e tentar novamente com a lista atualizada caso outro processo ocupe o mesmo slug. Em importações em lote, acrescente cada atribuição bem-sucedida ao conjunto local antes de resolver a próxima linha. Como a comparação é exata, aplique antes e de modo consistente sua política de URL: use um gerador de slugs se precisar normalizar caixa, Unicode, espaços ou pontuação. Cada solicitação de API custa US$ 0,002, e a mesma lógica determinística pode ser executada no navegador para verificações interativas.