Manipulando Parâmetros de URL em JavaScript com a API URLSearchParams

A manipulação manual de Query Strings por meio de expressões regulares ou cortes de string (split) é suscetível a bugs de encoding e formatação. Utilizar a API nativa URLSearchParams resolve esse problema, oferecendo uma interface limpa para ler, adicionar, atualizar e remover parâmetros em URLs sem a necessidade de bibliotecas externas.

JavaScript

/**
 * Utilitário para manipular e atualizar parâmetros de Query String em uma URL
 * @param {string} urlString - URL completa ou apenas a query string
 * @param {Object} novosParametros - Parâmetros a serem adicionados ou alterados
 * @returns {string} URL atualizada com os novos parâmetros
 */
function atualizarQueryParams(urlString, novosParametros) {
  const url = new URL(urlString);
  // Instancia o URLSearchParams a partir da search string da URL
  const params = new URLSearchParams(url.search);

  // Percorre o objeto e atualiza ou insere novos parâmetros
  Object.entries(novosParametros).forEach(([chave, valor]) => {
    if (valor === null || valor === undefined) {
      params.delete(chave); // Remove o parâmetro se o valor for nulo
    } else {
      params.set(chave, valor); // Adiciona ou substitui o valor existente
    }
  });

  // Atualiza a busca na instância da URL
  url.search = params.toString();
  return url.toString();
}

// Exemplo prático de uso
const urlOriginal = 'https://api.exemplo.com/produtos?categoria=tech&pagina=1';

// Lendo parâmetros existentes
const paramsAtuais = new URLSearchParams(new URL(urlOriginal).search);
console.log('Página atual:', paramsAtuais.get('pagina')); // "1"

// Alterando e adicionando parâmetros
const urlAtualizada = atualizarQueryParams(urlOriginal, {
  pagina: 2,           // Altera parâmetro existente
  ordem: 'asc',         // Adiciona novo parâmetro
  categoria: null      // Remove o parâmetro 'categoria'
});

console.log('URL Final:', urlAtualizada);
// Resultado: "https://api.exemplo.com/produtos?pagina=2&ordem=asc"

Pontos-chave

• Encoder Automático: O URLSearchParams realiza o percent-encoding (como converter espaços em %20 ou +) de forma nativa e automática, prevenindo URLs malformadas.
• Diferença entre .set() e .append(): O método .set() substitui o valor de uma chave existente ou a cria caso não exista. Já o .append() adiciona uma nova chave mesmo que ela já exista na URL (útil para cenários de filtros múltiplos com a mesma chave).
• Consumo de Parâmetros: Métodos de leitura como .get('chave') retornam uma string (ou null se ausente). Lembre-se de converter para tipo numérico (Number()) ao lidar com paginação ou IDs.
• Integração com a API URL: É altamente recomendado instanciar o URLSearchParams através da propriedade url.search do objeto URL nativo, garantindo suporte completo a protocolos, portas e caminhos relativos.