Módulo url

O módulo url do Node.js fornece utilitários para resolução, parsing e manipulação de URLs. Ele permite dividir um endereço web em partes significativas, construir URLs dinamicamente, manipular parâmetros de query string e validar URLs.

Importação do módulo URL

No Node.js, pode-se importar o módulo URL da maneira tradicional usando:

const url = require('url');

Ou, usando a sintaxe moderna de módulos ES com import (Node.js 14+):

import { URL, URLSearchParams } from 'node:url';

Construção de um objeto URL

Para criar um objeto URL a partir de uma string, usa-se o construtor URL:

const urlobj = new url.URL('https://www.example.com:8080/path/name?param1=value1&param2=value2#section');

Esse objeto possui várias propriedades úteis que correspondem às partes da URL:

• href: URL completa
• protocol: protocolo (ex: https:)
• host: hostname com porta (ex: www.example.com:8080)
• hostname: hostname (ex: www.example.com)
• port: porta (ex: 8080)
• pathname: caminho da URL (ex: /path/name)
• search: query string com interrogação (ex: ?param1=value1&param2=value2)
• searchParams: objeto para manipular os parâmetros de query
• hash: fragmento após # (ex: #section)

Exemplo:

console.log(url.protocol); // https:
console.log(url.host); // www.example.com:8080
console.log(url.pathname); // /path/name
console.log(url.searchParams.get('param1')); // value1
console.log(url.hash); // #section

Manipulação dos parâmetros de consulta (query string)

A propriedade searchParams é uma instância da classe URLSearchParams que permite manipular os parâmetros da query string de forma dinâmica.

Exemplos úteis:

const urlobj = new url.URL('https://www.example.com?foo=bar&baz=qux');

// Ler valor
console.log(urlobj.searchParams.get('foo')); // bar

// Adicionar novo parâmetro
urlobj.searchParams.append('newParam', 'newValue');
console.log(urlobj.href); // https://www.example.com/?foo=bar&baz=qux&newParam=newValue

// Modificar um parâmetro
urlobj.searchParams.set('foo', 'changed');
console.log(urlobj.href); // https://www.example.com/?foo=changed&baz=qux&newParam=newValue

// Remover um parâmetro
urlobj.searchParams.delete('baz');
console.log(urlobj.href); // https://www.example.com/?foo=changed&newParam=newValue

Construção de URLs relativas a uma base

O construtor URL aceita um segundo parâmetro que serve como a base para URLs relativas.

Exemplo:

const base = 'https://example.com/folder/';

const url1 = new URL('file.txt', base);
console.log(url1.href); // https://example.com/folder/file.txt

const url2 = new URL('/otherpath', base);
console.log(url2.href); // https://example.com/otherpath

Validação de URLs

Pode-se verificar se uma string é uma URL válida tentando criar um objeto URL dentro de um bloco try-catch:

function isValidUrl(string) {
  try {
    new URL(string);
    return true;
  } catch {
    return false;
  }
}

console.log(isValidUrl('https://test.com')); // true
console.log(isValidUrl('invalid-url')); // false

Exemplo completo resumido

const { URL } = require('url');

const url = new URL('https://user:pass@example.com:8080/path/name?foo=bar#hash');

console.log('Protocol:', url.protocol);
console.log('Host:', url.host);
console.log('Hostname:', url.hostname);
console.log('Port:', url.port);
console.log('Pathname:', url.pathname);
console.log('Search:', url.search);
console.log('Hash:', url.hash);
console.log('User:', url.username);
console.log('Password:', url.password);

url.searchParams.append('newParam', 'newValue');
console.log('URL com novo parâmetro:', url.href);