URL

[Estable: 2 - Estable]

Código fuente: lib/url.js

El módulo node:url proporciona utilidades para la resolución y el análisis de URLs. Se puede acceder a él usando:

ESMCJS

import url from 'node:url';

const url = require('node:url');

Cadenas de URL y objetos de URL

Una cadena de URL es una cadena estructurada que contiene múltiples componentes significativos. Cuando se analiza, se devuelve un objeto de URL que contiene propiedades para cada uno de estos componentes.

El módulo node:url proporciona dos APIs para trabajar con URLs: una API heredada que es específica de Node.js y una API más nueva que implementa el mismo Estándar de URL de WHATWG utilizado por los navegadores web.

A continuación, se proporciona una comparación entre las APIs WHATWG y la heredada. Encima de la URL 'https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash', se muestran las propiedades de un objeto devuelto por el url.parse() heredado. Debajo, se encuentran las propiedades de un objeto URL de WHATWG.

La propiedad origin de la URL de WHATWG incluye protocol y host, pero no username o password.

text

┌────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                              href                                              │
├──────────┬──┬─────────────────────┬────────────────────────┬───────────────────────────┬───────┤
│ protocol │  │        auth         │          host          │           path            │ hash  │
│          │  │                     ├─────────────────┬──────┼──────────┬────────────────┤       │
│          │  │                     │    hostname     │ port │ pathname │     search     │       │
│          │  │                     │                 │      │          ├─┬──────────────┤       │
│          │  │                     │                 │      │          │ │    query     │       │
"  https:   //    user   :   pass   @ sub.example.com : 8080   /p/a/t/h  ?  query=string   #hash "
│          │  │          │          │    hostname     │ port │          │                │       │
│          │  │          │          ├─────────────────┴──────┤          │                │       │
│ protocol │  │ username │ password │          host          │          │                │       │
├──────────┴──┼──────────┴──────────┼────────────────────────┤          │                │       │
│   origin    │                     │         origin         │ pathname │     search     │ hash  │
├─────────────┴─────────────────────┴────────────────────────┴──────────┴────────────────┴───────┤
│                                              href                                              │
└────────────────────────────────────────────────────────────────────────────────────────────────┘
(Todos los espacios en la línea "" deben ignorarse. Son puramente para formatear.)

Analizando la cadena de URL usando la API de WHATWG:

const myURL =
  new URL('https://user::8080/p/a/t/h?query=string#hash');

Analizando la cadena de URL usando la API heredada:

ESMCJS

import url from 'node:url';
const myURL =
  url.parse('https://user::8080/p/a/t/h?query=string#hash');

const url = require('node:url');
const myURL =
  url.parse('https://user::8080/p/a/t/h?query=string#hash');

Construcción de una URL a partir de componentes y obtención de la cadena construida

Es posible construir una URL WHATWG a partir de componentes utilizando los setters de propiedad o una cadena de plantilla literal:

const myURL = new URL('https://example.org');
myURL.pathname = '/a/b/c';
myURL.search = '?d=e';
myURL.hash = '#fgh';

const pathname = '/a/b/c';
const search = '?d=e';
const hash = '#fgh';
const myURL = new URL(`https://example.org${pathname}${search}${hash}`);

Para obtener la cadena URL construida, utilice el descriptor de acceso de la propiedad href:

console.log(myURL.href);

La API URL de WHATWG

Clase: `URL`

[Historia]

Versión	Cambios
v10.0.0	La clase ahora está disponible en el objeto global.
v7.0.0, v6.13.0	Añadido en: v7.0.0, v6.13.0

Clase URL compatible con el navegador, implementada siguiendo el estándar URL de WHATWG. En el propio estándar se pueden encontrar ejemplos de URLs analizadas. La clase URL también está disponible en el objeto global.

De acuerdo con las convenciones del navegador, todas las propiedades de los objetos URL se implementan como captadores y establecedores en el prototipo de la clase, en lugar de como propiedades de datos en el propio objeto. Por lo tanto, a diferencia de los objetos urlObject heredados, el uso de la palabra clave delete en cualquier propiedad de los objetos URL (por ejemplo, delete myURL.protocol, delete myURL.pathname, etc.) no tiene ningún efecto, pero seguirá devolviendo true.

`new URL(input[, base])`

[Historia]

Versión	Cambios
v20.0.0, v18.17.0	Se elimina el requisito de ICU.

input <string> La URL de entrada absoluta o relativa que se va a analizar. Si input es relativa, entonces base es obligatoria. Si input es absoluta, la base se ignora. Si input no es una cadena, primero se convierte en una cadena.
base <string> La URL base con la que se va a resolver si la input no es absoluta. Si base no es una cadena, primero se convierte en una cadena.

Crea un nuevo objeto URL analizando la input en relación con la base. Si base se pasa como una cadena, se analizará de forma equivalente a new URL(base).

const myURL = new URL('/foo', 'https://example.org/');
// https://example.org/foo

El constructor URL es accesible como una propiedad en el objeto global. También se puede importar desde el módulo url incorporado:

ESMCJS

import { URL } from 'node:url';
console.log(URL === globalThis.URL); // Imprime 'true'.

console.log(URL === require('node:url').URL); // Imprime 'true'.

Se lanzará un TypeError si la input o la base no son URLs válidas. Tenga en cuenta que se hará un esfuerzo para coaccionar los valores dados en cadenas. Por ejemplo:

const myURL = new URL({ toString: () => 'https://example.org/' });
// https://example.org/

Los caracteres Unicode que aparezcan dentro del nombre de host de input se convertirán automáticamente a ASCII utilizando el algoritmo Punycode.

const myURL = new URL('https://測試');
// https://xn--g6w251d/

En los casos en que no se sepa de antemano si la input es una URL absoluta y se proporciona una base, se aconseja validar que el origin del objeto URL es el esperado.

let myURL = new URL('http://Example.com/', 'https://example.org/');
// http://example.com/

myURL = new URL('https://Example.com/', 'https://example.org/');
// https://example.com/

myURL = new URL('foo://Example.com/', 'https://example.org/');
// foo://Example.com/

myURL = new URL('http:Example.com/', 'https://example.org/');
// http://example.com/

myURL = new URL('https:Example.com/', 'https://example.org/');
// https://example.org/Example.com/

myURL = new URL('foo:Example.com/', 'https://example.org/');
// foo:Example.com/

`url.hash`

<string>

Obtiene y establece la porción de fragmento de la URL.

const myURL = new URL('https://example.org/foo#bar');
console.log(myURL.hash);
// Imprime #bar

myURL.hash = 'baz';
console.log(myURL.href);
// Imprime https://example.org/foo#baz

Los caracteres URL inválidos incluidos en el valor asignado a la propiedad hash están codificados por porcentaje. La selección de qué caracteres codificar por porcentaje puede variar un poco de lo que los métodos url.parse() y url.format() producirían.

`url.host`

<string>

Obtiene y establece la porción de host de la URL.

const myURL = new URL('https://example.org:81/foo');
console.log(myURL.host);
// Imprime example.org:81

myURL.host = 'example.com:82';
console.log(myURL.href);
// Imprime https://example.com:82/foo

Los valores de host inválidos asignados a la propiedad host se ignoran.

`url.hostname`

<string>

Obtiene y establece la porción del nombre de host de la URL. La diferencia clave entre url.host y url.hostname es que url.hostname no incluye el puerto.

const myURL = new URL('https://example.org:81/foo');
console.log(myURL.hostname);
// Imprime example.org

// Establecer el nombre de host no cambia el puerto
myURL.hostname = 'example.com';
console.log(myURL.href);
// Imprime https://example.com:81/foo

// Use myURL.host para cambiar el nombre de host y el puerto
myURL.host = 'example.org:82';
console.log(myURL.href);
// Imprime https://example.org:82/foo

Los valores de nombre de host inválidos asignados a la propiedad hostname se ignoran.

`url.href`

<string>

Obtiene y establece la URL serializada.

const myURL = new URL('https://example.org/foo');
console.log(myURL.href);
// Imprime https://example.org/foo

myURL.href = 'https://example.com/bar';
console.log(myURL.href);
// Imprime https://example.com/bar

Obtener el valor de la propiedad href es equivalente a llamar a url.toString().

Establecer el valor de esta propiedad a un nuevo valor es equivalente a crear un nuevo objeto URL usando new URL(value). Cada una de las propiedades del objeto URL será modificada.

Si el valor asignado a la propiedad href no es una URL válida, se lanzará un TypeError.

`url.origin`

[Historia]

Versión	Cambios
v15.0.0	El esquema "gopher" ya no es especial y `url.origin` ahora devuelve `'null'` para él.

<string>

Obtiene la serialización de solo lectura del origen de la URL.

const myURL = new URL('https://example.org/foo/bar?baz');
console.log(myURL.origin);
// Imprime https://example.org

const idnURL = new URL('https://測試');
console.log(idnURL.origin);
// Imprime https://xn--g6w251d

console.log(idnURL.hostname);
// Imprime xn--g6w251d

`url.password`

<string>

Obtiene y establece la parte de la contraseña de la URL.

const myURL = new URL('https://abc:');
console.log(myURL.password);
// Imprime xyz

myURL.password = '123';
console.log(myURL.href);
// Imprime https://abc:/

Los caracteres inválidos de URL incluidos en el valor asignado a la propiedad password están codificados por porcentaje. La selección de qué caracteres codificar por porcentaje puede variar un poco de lo que los métodos url.parse() y url.format() producirían.

`url.pathname`

<string>

Obtiene y establece la parte de la ruta de la URL.

const myURL = new URL('https://example.org/abc/xyz?123');
console.log(myURL.pathname);
// Imprime /abc/xyz

myURL.pathname = '/abcdef';
console.log(myURL.href);
// Imprime https://example.org/abcdef?123

Los caracteres inválidos de URL incluidos en el valor asignado a la propiedad pathname están codificados por porcentaje. La selección de qué caracteres codificar por porcentaje puede variar un poco de lo que los métodos url.parse() y url.format() producirían.

`url.port`

[Historia]

Versión	Cambios
v15.0.0	El esquema "gopher" ya no es especial.

<string>

Obtiene y establece la porción del puerto de la URL.

El valor del puerto puede ser un número o una cadena que contenga un número en el rango de 0 a 65535 (inclusive). Establecer el valor al puerto predeterminado de los objetos URL dado un protocol resultará en que el valor del port se convierta en una cadena vacía ('').

El valor del puerto puede ser una cadena vacía en cuyo caso el puerto depende del protocolo/esquema:

protocolo	puerto
"ftp"	21
"file"
"http"	80
"https"	443
"ws"	80
"wss"	443
Al asignar un valor al puerto, primero se convertirá el valor a una cadena usando `.toString()`.

Si esa cadena no es válida pero comienza con un número, el número inicial se asigna a port. Si el número se encuentra fuera del rango denotado anteriormente, se ignora.

const myURL = new URL('https://example.org:8888');
console.log(myURL.port);
// Imprime 8888

// Los puertos predeterminados se transforman automáticamente en la cadena vacía
// (El puerto predeterminado del protocolo HTTPS es 443)
myURL.port = '443';
console.log(myURL.port);
// Imprime la cadena vacía
console.log(myURL.href);
// Imprime https://example.org/

myURL.port = 1234;
console.log(myURL.port);
// Imprime 1234
console.log(myURL.href);
// Imprime https://example.org:1234/

// Las cadenas de puerto completamente inválidas se ignoran
myURL.port = 'abcd';
console.log(myURL.port);
// Imprime 1234

// Los números iniciales se tratan como un número de puerto
myURL.port = '5678abcd';
console.log(myURL.port);
// Imprime 5678

// Los no enteros se truncan
myURL.port = 1234.5678;
console.log(myURL.port);
// Imprime 1234

// Los números fuera de rango que no están representados en notación científica
// se ignorarán.
myURL.port = 1e10; // 10000000000, se verificará el rango como se describe a continuación
console.log(myURL.port);
// Imprime 1234

Los números que contienen un punto decimal, como los números de punto flotante o los números en notación científica, no son una excepción a esta regla. Los números iniciales hasta el punto decimal se establecerán como el puerto de la URL, suponiendo que sean válidos:

myURL.port = 4.567e21;
console.log(myURL.port);
// Imprime 4 (porque es el número inicial en la cadena '4.567e21')

`url.protocol`

<string>

Obtiene y establece la porción de protocolo de la URL.

const myURL = new URL('https://example.org');
console.log(myURL.protocol);
// Imprime https:

myURL.protocol = 'ftp';
console.log(myURL.href);
// Imprime ftp://example.org/

Los valores de protocolo de URL no válidos asignados a la propiedad protocol se ignoran.

Esquemas especiales

[Historial]

Versión	Cambios
v15.0.0	El esquema "gopher" ya no es especial.

El Estándar de URL de WHATWG considera que un puñado de esquemas de protocolo de URL son especiales en términos de cómo se analizan y serializan. Cuando se analiza una URL utilizando uno de estos protocolos especiales, la propiedad url.protocol se puede cambiar a otro protocolo especial, pero no se puede cambiar a un protocolo no especial, y viceversa.

Por ejemplo, cambiar de http a https funciona:

const u = new URL('http://example.org');
u.protocol = 'https';
console.log(u.href);
// https://example.org/

Sin embargo, cambiar de http a un protocolo hipotético fish no lo hace porque el nuevo protocolo no es especial.

const u = new URL('http://example.org');
u.protocol = 'fish';
console.log(u.href);
// http://example.org/

Del mismo modo, tampoco se permite cambiar de un protocolo no especial a un protocolo especial:

const u = new URL('fish://example.org');
u.protocol = 'http';
console.log(u.href);
// fish://example.org

Según el Estándar de URL de WHATWG, los esquemas de protocolo especiales son ftp, file, http, https, ws y wss.

`url.search`

<string>

Obtiene y establece la porción de consulta serializada de la URL.

const myURL = new URL('https://example.org/abc?123');
console.log(myURL.search);
// Imprime ?123

myURL.search = 'abc=xyz';
console.log(myURL.href);
// Imprime https://example.org/abc?abc=xyz

Cualquier carácter de URL no válido que aparezca en el valor asignado a la propiedad search se codificará como porcentaje. La selección de qué caracteres codificar como porcentaje puede variar un poco de lo que producirían los métodos url.parse() y url.format().

`url.searchParams`

<URLSearchParams>

Obtiene el objeto URLSearchParams que representa los parámetros de consulta de la URL. Esta propiedad es de solo lectura, pero el objeto URLSearchParams que proporciona se puede usar para mutar la instancia de URL; para reemplazar la totalidad de los parámetros de consulta de la URL, use el establecedor url.search. Consulte la documentación de URLSearchParams para obtener más detalles.

Tenga cuidado al usar .searchParams para modificar la URL porque, según la especificación WHATWG, el objeto URLSearchParams usa diferentes reglas para determinar qué caracteres deben codificarse como porcentaje. Por ejemplo, el objeto URL no codificará como porcentaje el carácter tilde ASCII (~), mientras que URLSearchParams siempre lo codificará:

const myURL = new URL('https://example.org/abc?foo=~bar');

console.log(myURL.search);  // Imprime ?foo=~bar

// Modificar la URL a través de searchParams...
myURL.searchParams.sort();

console.log(myURL.search);  // Imprime ?foo=%7Ebar

`url.username`

<string>

Obtiene y establece la parte del nombre de usuario de la URL.

const myURL = new URL('https://abc:');
console.log(myURL.username);
// Imprime abc

myURL.username = '123';
console.log(myURL.href);
// Imprime https://123:/

Cualquier carácter de URL no válido que aparezca en el valor asignado a la propiedad username se codificará como porcentaje. La selección de qué caracteres codificar como porcentaje puede variar un poco de lo que los métodos url.parse() y url.format() producirían.

`url.toString()`

Devuelve: <string>

El método toString() en el objeto URL devuelve la URL serializada. El valor devuelto es equivalente al de url.href y url.toJSON().

`url.toJSON()`

Agregado en: v7.7.0, v6.13.0

Devuelve: <string>

El método toJSON() en el objeto URL devuelve la URL serializada. El valor devuelto es equivalente al de url.href y url.toString().

Este método se llama automáticamente cuando un objeto URL se serializa con JSON.stringify().

const myURLs = [
  new URL('https://www.example.com'),
  new URL('https://test.example.org'),
];
console.log(JSON.stringify(myURLs));
// Prints ["https://www.example.com/","https://test.example.org/"]

`URL.createObjectURL(blob)`

Agregado en: v16.7.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

blob <Blob>
Devuelve: <string>

Crea una cadena URL 'blob:nodedata:...' que representa el objeto <Blob> dado y se puede usar para recuperar el Blob más tarde.

const {
  Blob,
  resolveObjectURL,
} = require('node:buffer');

const blob = new Blob(['hello']);
const id = URL.createObjectURL(blob);

// later...

const otherBlob = resolveObjectURL(id);
console.log(otherBlob.size);

Los datos almacenados por el <Blob> registrado se conservarán en la memoria hasta que se llame a URL.revokeObjectURL() para eliminarlo.

Los objetos Blob se registran dentro del hilo actual. Si se utilizan hilos de trabajo, los objetos Blob registrados dentro de un trabajador no estarán disponibles para otros trabajadores o el hilo principal.

`URL.revokeObjectURL(id)`

Agregado en: v16.7.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

id <string> Una cadena URL 'blob:nodedata:... devuelta por una llamada anterior a URL.createObjectURL().

Elimina el <Blob> almacenado identificado por el ID dado. Intentar revocar un ID que no está registrado fallará silenciosamente.

`URL.canParse(input[, base])`

Agregado en: v19.9.0, v18.17.0

input <string> La URL de entrada absoluta o relativa a analizar. Si input es relativa, entonces base es obligatoria. Si input es absoluta, la base se ignora. Si input no es una cadena, primero se convierte en una cadena.
base <string> La URL base con la que se debe resolver si la input no es absoluta. Si base no es una cadena, primero se convierte en una cadena.
Devuelve: <boolean>

Verifica si una input relativa a la base puede ser analizada como una URL.

const isValid = URL.canParse('/foo', 'https://example.org/'); // true

const isNotValid = URL.canParse('/foo'); // false

`URL.parse(input[, base])`

Agregado en: v22.1.0

input <string> La URL de entrada absoluta o relativa a analizar. Si input es relativa, entonces base es obligatoria. Si input es absoluta, la base se ignora. Si input no es una cadena, primero se convierte en una cadena.
base <string> La URL base con la que se debe resolver si la input no es absoluta. Si base no es una cadena, primero se convierte en una cadena.
Devuelve: <URL> | <null>

Analiza una cadena como una URL. Si se proporciona base, se utilizará como la URL base con el propósito de resolver las URLs de input no absolutas. Devuelve null si input no es válida.

Clase: `URLSearchParams`

[Historial]

Versión	Cambios
v10.0.0	La clase ahora está disponible en el objeto global.
v7.5.0, v6.13.0	Añadido en: v7.5.0, v6.13.0

La API URLSearchParams proporciona acceso de lectura y escritura a la consulta de una URL. La clase URLSearchParams también se puede utilizar de forma independiente con uno de los cuatro constructores siguientes. La clase URLSearchParams también está disponible en el objeto global.

La interfaz WHATWG URLSearchParams y el módulo querystring tienen un propósito similar, pero el propósito del módulo querystring es más general, ya que permite la personalización de caracteres delimitadores (& e =). Por otro lado, esta API está diseñada puramente para cadenas de consulta de URL.

const myURL = new URL('https://example.org/?abc=123');
console.log(myURL.searchParams.get('abc'));
// Imprime 123

myURL.searchParams.append('abc', 'xyz');
console.log(myURL.href);
// Imprime https://example.org/?abc=123&abc=xyz

myURL.searchParams.delete('abc');
myURL.searchParams.set('a', 'b');
console.log(myURL.href);
// Imprime https://example.org/?a=b

const newSearchParams = new URLSearchParams(myURL.searchParams);
// Lo anterior es equivalente a
// const newSearchParams = new URLSearchParams(myURL.search);

newSearchParams.append('a', 'c');
console.log(myURL.href);
// Imprime https://example.org/?a=b
console.log(newSearchParams.toString());
// Imprime a=b&a=c

// newSearchParams.toString() se llama implícitamente
myURL.search = newSearchParams;
console.log(myURL.href);
// Imprime https://example.org/?a=b&a=c
newSearchParams.delete('a');
console.log(myURL.href);
// Imprime https://example.org/?a=b&a=c

`new URLSearchParams()`

Instanciar un nuevo objeto URLSearchParams vacío.

`new URLSearchParams(string)`

string <string> Una cadena de consulta

Analice la string como una cadena de consulta y utilícela para instanciar un nuevo objeto URLSearchParams. Un '?' inicial, si está presente, se ignora.

let params;

params = new URLSearchParams('user=abc&query=xyz');
console.log(params.get('user'));
// Imprime 'abc'
console.log(params.toString());
// Imprime 'user=abc&query=xyz'

params = new URLSearchParams('?user=abc&query=xyz');
console.log(params.toString());
// Imprime 'user=abc&query=xyz'

`new URLSearchParams(obj)`

Añadido en: v7.10.0, v6.13.0

obj <Object> Un objeto que representa una colección de pares clave-valor

Instancia un nuevo objeto URLSearchParams con un mapa hash de consulta. La clave y el valor de cada propiedad de obj siempre se fuerzan a cadenas.

A diferencia del módulo querystring, no se permiten claves duplicadas en forma de valores de array. Los arrays se convierten en cadenas utilizando array.toString(), que simplemente une todos los elementos del array con comas.

const params = new URLSearchParams({
  user: 'abc',
  query: ['first', 'second'],
});
console.log(params.getAll('query'));
// Imprime [ 'first,second' ]
console.log(params.toString());
// Imprime 'user=abc&query=first%2Csecond'

`new URLSearchParams(iterable)`

Añadido en: v7.10.0, v6.13.0

iterable <Iterable> Un objeto iterable cuyos elementos son pares clave-valor

Instancia un nuevo objeto URLSearchParams con un mapa iterable de una manera similar al constructor de Map. iterable puede ser un Array o cualquier objeto iterable. Eso significa que iterable puede ser otro URLSearchParams, en cuyo caso el constructor simplemente creará un clon del URLSearchParams proporcionado. Los elementos de iterable son pares clave-valor, y pueden ser ellos mismos cualquier objeto iterable.

Se permiten claves duplicadas.

let params;

// Usando un array
params = new URLSearchParams([
  ['user', 'abc'],
  ['query', 'first'],
  ['query', 'second'],
]);
console.log(params.toString());
// Imprime 'user=abc&query=first&query=second'

// Usando un objeto Map
const map = new Map();
map.set('user', 'abc');
map.set('query', 'xyz');
params = new URLSearchParams(map);
console.log(params.toString());
// Imprime 'user=abc&query=xyz'

// Usando una función generadora
function* getQueryPairs() {
  yield ['user', 'abc'];
  yield ['query', 'first'];
  yield ['query', 'second'];
}
params = new URLSearchParams(getQueryPairs());
console.log(params.toString());
// Imprime 'user=abc&query=first&query=second'

// Cada par clave-valor debe tener exactamente dos elementos
new URLSearchParams([
  ['user', 'abc', 'error'],
]);
// Lanza TypeError [ERR_INVALID_TUPLE]:
//        Cada par de consulta debe ser una tupla iterable [nombre, valor]

`urlSearchParams.append(name, value)`

name <string>
value <string>

Añade un nuevo par nombre-valor a la cadena de consulta.

`urlSearchParams.delete(name[, value])`

[Historial]

Versión	Cambios
v20.2.0, v18.18.0	Añade soporte para el argumento opcional `value`.

name <string>
value <string>

Si se proporciona value, elimina todos los pares nombre-valor donde el nombre es name y el valor es value.

Si no se proporciona value, elimina todos los pares nombre-valor cuyo nombre es name.

`urlSearchParams.entries()`

Devuelve: <Iterator>

Devuelve un Iterator ES6 sobre cada uno de los pares nombre-valor en la consulta. Cada elemento del iterador es un Array de JavaScript. El primer elemento del Array es el name, el segundo elemento del Array es el value.

Alias para urlSearchParams[@@iterator]().

`urlSearchParams.forEach(fn[, thisArg])`

[Historial]

Versión	Cambios
v18.0.0	Pasar una retrollamada inválida al argumento `fn` ahora lanza `ERR_INVALID_ARG_TYPE` en lugar de `ERR_INVALID_CALLBACK`.

fn <Function> Se invoca para cada par nombre-valor en la consulta
thisArg <Object> Se utilizará como valor this cuando se llame a fn

Itera sobre cada par nombre-valor en la consulta e invoca la función dada.

const myURL = new URL('https://example.org/?a=b&c=d');
myURL.searchParams.forEach((value, name, searchParams) => {
  console.log(name, value, myURL.searchParams === searchParams);
});
// Prints:
//   a b true
//   c d true

`urlSearchParams.get(name)`

name <string>
Devuelve: <string> | <null> Una cadena o null si no hay ningún par nombre-valor con el name dado.

Devuelve el valor del primer par nombre-valor cuyo nombre es name. Si no existen tales pares, se devuelve null.

`urlSearchParams.getAll(name)`

name <string>
Devuelve: <string[]>

Devuelve los valores de todos los pares nombre-valor cuyo nombre es name. Si no existen tales pares, se devuelve un array vacío.

`urlSearchParams.has(name[, value])`

[Historial]

Versión	Cambios
v20.2.0, v18.18.0	Se añadió soporte para el argumento opcional `value`.

name <string>
value <string>
Devuelve: <boolean>

Comprueba si el objeto URLSearchParams contiene pares clave-valor basados en name y un argumento opcional value.

Si se proporciona value, devuelve true cuando existe un par nombre-valor con el mismo name y value.

Si no se proporciona value, devuelve true si hay al menos un par nombre-valor cuyo nombre es name.

`urlSearchParams.keys()`

Devuelve: <Iterator>

Devuelve un Iterator ES6 sobre los nombres de cada par nombre-valor.

const params = new URLSearchParams('foo=bar&foo=baz');
for (const name of params.keys()) {
  console.log(name);
}
// Prints:
//   foo
//   foo

`urlSearchParams.set(name, value)`

name <string>
value <string>

Establece el valor en el objeto URLSearchParams asociado con name a value. Si existen pares nombre-valor preexistentes cuyos nombres son name, establece el valor del primer par a value y elimina todos los demás. Si no, añade el par nombre-valor a la cadena de consulta.

const params = new URLSearchParams();
params.append('foo', 'bar');
params.append('foo', 'baz');
params.append('abc', 'def');
console.log(params.toString());
// Imprime foo=bar&foo=baz&abc=def

params.set('foo', 'def');
params.set('xyz', 'opq');
console.log(params.toString());
// Imprime foo=def&abc=def&xyz=opq

`urlSearchParams.size`

Agregado en: v19.8.0, v18.16.0

El número total de entradas de parámetros.

`urlSearchParams.sort()`

Agregado en: v7.7.0, v6.13.0

Ordena todos los pares nombre-valor existentes en el lugar por sus nombres. La ordenación se realiza con un algoritmo de ordenación estable, por lo que se conserva el orden relativo entre los pares nombre-valor con el mismo nombre.

Este método se puede utilizar, en particular, para aumentar los aciertos de la caché.

const params = new URLSearchParams('query[]=abc&type=search&query[]=123');
params.sort();
console.log(params.toString());
// Imprime query%5B%5D=abc&query%5B%5D=123&type=search

`urlSearchParams.toString()`

Devuelve: <string>

Devuelve los parámetros de búsqueda serializados como una cadena, con los caracteres codificados en porcentaje donde sea necesario.

`urlSearchParams.values()`

Devuelve: <Iterator>

Devuelve un Iterator ES6 sobre los valores de cada par nombre-valor.

`urlSearchParams[Symbol.iterator]()`

Devuelve: <Iterador>

Devuelve un Iterador ES6 sobre cada uno de los pares nombre-valor en la cadena de consulta. Cada elemento del iterador es un Array de JavaScript. El primer elemento del Array es el nombre, el segundo elemento del Array es el valor.

Alias para urlSearchParams.entries().

const params = new URLSearchParams('foo=bar&xyz=baz');
for (const [name, value] of params) {
  console.log(name, value);
}
// Imprime:
//   foo bar
//   xyz baz

`url.domainToASCII(domain)`

[Historial]

Versión	Cambios
v20.0.0, v18.17.0	Se elimina el requisito de ICU.
v7.4.0, v6.13.0	Añadido en: v7.4.0, v6.13.0

domain <string>
Devuelve: <string>

Devuelve la serialización ASCII Punycode del dominio. Si domain es un dominio inválido, se devuelve la cadena vacía.

Realiza la operación inversa a url.domainToUnicode().

ESMCJS

import url from 'node:url';

console.log(url.domainToASCII('español.com'));
// Imprime xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'));
// Imprime xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'));
// Imprime una cadena vacía

const url = require('node:url');

console.log(url.domainToASCII('español.com'));
// Imprime xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'));
// Imprime xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'));
// Imprime una cadena vacía

`url.domainToUnicode(domain)`

[Historial]

Versión	Cambios
v20.0.0, v18.17.0	Se elimina el requisito de ICU.
v7.4.0, v6.13.0	Añadido en: v7.4.0, v6.13.0

domain <string>
Devuelve: <string>

Devuelve la serialización Unicode del dominio. Si domain es un dominio inválido, se devuelve la cadena vacía.

Realiza la operación inversa a url.domainToASCII().

ESMCJS

import url from 'node:url';

console.log(url.domainToUnicode('xn--espaol-zwa.com'));
// Imprime español.com
console.log(url.domainToUnicode('xn--fiq228c.com'));
// Imprime 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'));
// Imprime una cadena vacía

const url = require('node:url');

console.log(url.domainToUnicode('xn--espaol-zwa.com'));
// Imprime español.com
console.log(url.domainToUnicode('xn--fiq228c.com'));
// Imprime 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'));
// Imprime una cadena vacía

`url.fileURLToPath(url[, options])`

[Historial]

Versión	Cambios
v22.1.0, v20.13.0	El argumento `options` ahora se puede usar para determinar cómo analizar el argumento `path`.
v10.12.0	Añadido en: v10.12.0

url <URL> | <string> La cadena de URL de archivo u objeto URL para convertir a una ruta.
options <Object>
- windows <boolean> | <undefined> true si la path debe devolverse como una ruta de archivo de Windows, false para posix y undefined para el sistema predeterminado. Predeterminado: undefined.
Devuelve: <string> La ruta de archivo de Node.js específica de la plataforma totalmente resuelta.

Esta función garantiza la decodificación correcta de los caracteres codificados por porcentaje, así como también garantiza una cadena de ruta absoluta válida entre plataformas.

ESMCJS

import { fileURLToPath } from 'node:url';

const __filename = fileURLToPath(import.meta.url);

new URL('file:///C:/path/').pathname;      // Incorrecto: /C:/path/
fileURLToPath('file:///C:/path/');         // Correcto:   C:\path\ (Windows)

new URL('file://nas/foo.txt').pathname;    // Incorrecto: /foo.txt
fileURLToPath('file://nas/foo.txt');       // Correcto:   \\nas\foo.txt (Windows)

new URL('file:///你好.txt').pathname;      // Incorrecto: /%E4%BD%A0%E5%A5%BD.txt
fileURLToPath('file:///你好.txt');         // Correcto:   /你好.txt (POSIX)

new URL('file:///hello world').pathname;   // Incorrecto: /hello%20world
fileURLToPath('file:///hello world');      // Correcto:   /hello world (POSIX)

const { fileURLToPath } = require('node:url');
new URL('file:///C:/path/').pathname;      // Incorrecto: /C:/path/
fileURLToPath('file:///C:/path/');         // Correcto:   C:\path\ (Windows)

new URL('file://nas/foo.txt').pathname;    // Incorrecto: /foo.txt
fileURLToPath('file://nas/foo.txt');       // Correcto:   \\nas\foo.txt (Windows)

new URL('file:///你好.txt').pathname;      // Incorrecto: /%E4%BD%A0%E5%A5%BD.txt
fileURLToPath('file:///你好.txt');         // Correcto:   /你好.txt (POSIX)

new URL('file:///hello world').pathname;   // Incorrecto: /hello%20world
fileURLToPath('file:///hello world');      // Correcto:   /hello world (POSIX)

`url.format(URL[, options])`

Agregado en: v7.6.0

URL <URL> Un objeto WHATWG URL
options <Object>
- auth <boolean> true si la cadena URL serializada debe incluir el nombre de usuario y la contraseña, false en caso contrario. Predeterminado: true.
- fragment <boolean> true si la cadena URL serializada debe incluir el fragmento, false en caso contrario. Predeterminado: true.
- search <boolean> true si la cadena URL serializada debe incluir la consulta de búsqueda, false en caso contrario. Predeterminado: true.
- unicode <boolean> true si los caracteres Unicode que aparecen en el componente host de la cadena URL deben codificarse directamente en lugar de codificarse con Punycode. Predeterminado: false.
Devuelve: <string>

Devuelve una serialización personalizable de una representación String URL de un objeto WHATWG URL.

El objeto URL tiene tanto un método toString() como una propiedad href que devuelven serializaciones de cadena de la URL. Sin embargo, estos no son personalizables de ninguna manera. El método url.format(URL[, options]) permite la personalización básica de la salida.

ESMCJS

import url from 'node:url';
const myURL = new URL('https://a:b@測試?abc#foo');

console.log(myURL.href);
// Prints https://a:b@xn--g6w251d/?abc#foo

console.log(myURL.toString());
// Prints https://a:b@xn--g6w251d/?abc#foo

console.log(url.format(myURL, { fragment: false, unicode: true, auth: false }));
// Prints 'https://測試/?abc'

const url = require('node:url');
const myURL = new URL('https://a:b@測試?abc#foo');

console.log(myURL.href);
// Prints https://a:b@xn--g6w251d/?abc#foo

console.log(myURL.toString());
// Prints https://a:b@xn--g6w251d/?abc#foo

console.log(url.format(myURL, { fragment: false, unicode: true, auth: false }));
// Prints 'https://測試/?abc'

`url.pathToFileURL(path[, options])`

[Historial]

Versión	Cambios
v22.1.0, v20.13.0	Ahora se puede usar el argumento `options` para determinar cómo devolver el valor de `path`.
v10.12.0	Añadido en: v10.12.0

path <string> La ruta a convertir a una URL de archivo.
options <Object>
- windows <boolean> | <undefined> true si la path debe tratarse como una ruta de archivo de Windows, false para posix, y undefined para el valor predeterminado del sistema. Predeterminado: undefined.
Devuelve: <URL> El objeto URL de archivo.

Esta función asegura que path se resuelva de forma absoluta, y que los caracteres de control de la URL se codifiquen correctamente al convertir a una URL de archivo.

ESMCJS

import { pathToFileURL } from 'node:url';

new URL('/foo#1', 'file:');           // Incorrecto: file:///foo#1
pathToFileURL('/foo#1');              // Correcto:   file:///foo%231 (POSIX)

new URL('/some/path%.c', 'file:');    // Incorrecto: file:///some/path%.c
pathToFileURL('/some/path%.c');       // Correcto:   file:///some/path%25.c (POSIX)

const { pathToFileURL } = require('node:url');
new URL(__filename);                  // Incorrecto: lanza (POSIX)
new URL(__filename);                  // Incorrecto: C:\... (Windows)
pathToFileURL(__filename);            // Correcto:   file:///... (POSIX)
pathToFileURL(__filename);            // Correcto:   file:///C:/... (Windows)

new URL('/foo#1', 'file:');           // Incorrecto: file:///foo#1
pathToFileURL('/foo#1');              // Correcto:   file:///foo%231 (POSIX)

new URL('/some/path%.c', 'file:');    // Incorrecto: file:///some/path%.c
pathToFileURL('/some/path%.c');       // Correcto:   file:///some/path%25.c (POSIX)

`url.urlToHttpOptions(url)`

[Historial]

Versión	Cambios
v19.9.0, v18.17.0	El objeto devuelto también contendrá todas las propiedades enumerables propias del argumento `url`.
v15.7.0, v14.18.0	Añadido en: v15.7.0, v14.18.0

url <URL> El objeto WHATWG URL para convertir en un objeto de opciones.
Devuelve: <Object> Objeto de opciones
- protocol <string> Protocolo a usar.
- hostname <string> Un nombre de dominio o dirección IP del servidor al que enviar la solicitud.
- hash <string> La porción de fragmento de la URL.
- search <string> La porción de consulta serializada de la URL.
- pathname <string> La porción de ruta de la URL.
- path <string> Ruta de la solicitud. Debe incluir la cadena de consulta si existe. P.ej. '/index.html?page=12'. Se lanza una excepción cuando la ruta de la solicitud contiene caracteres ilegales. Actualmente, solo se rechazan los espacios, pero eso puede cambiar en el futuro.
- href <string> La URL serializada.
- port <number> Puerto del servidor remoto.
- auth <string> Autenticación básica, es decir, 'usuario:contraseña' para calcular un encabezado de Autorización.

Esta función de utilidad convierte un objeto URL en un objeto de opciones ordinario, tal como esperan las API http.request() y https.request().

ESMCJS

import { urlToHttpOptions } from 'node:url';
const myURL = new URL('https://a:b@測試?abc#foo');

console.log(urlToHttpOptions(myURL));
/*
{
  protocol: 'https:',
  hostname: 'xn--g6w251d',
  hash: '#foo',
  search: '?abc',
  pathname: '/',
  path: '/?abc',
  href: 'https://a:b@xn--g6w251d/?abc#foo',
  auth: 'a:b'
}
*/

const { urlToHttpOptions } = require('node:url');
const myURL = new URL('https://a:b@測試?abc#foo');

console.log(urlToHttpOptions(myURL));
/*
{
  protocol: 'https:',
  hostname: 'xn--g6w251d',
  hash: '#foo',
  search: '?abc',
  pathname: '/',
  path: '/?abc',
  href: 'https://a:b@xn--g6w251d/?abc#foo',
  auth: 'a:b'
}
*/

API de URL heredado

[Historial]

Versión	Cambios
v15.13.0, v14.17.0	Revocada la obsolescencia. Estado cambiado a "Heredado".
v11.0.0	Esta API está obsoleta.

[Estable: 3 - Heredado]

Estable: 3 Estabilidad: 3 - Heredado: Utilice la API de URL WHATWG en su lugar.

`urlObject` heredado

[Historial]

Versión	Cambios
v15.13.0, v14.17.0	Revocada la obsolescencia. Estado cambiado a "Heredado".
v11.0.0	La API de URL heredada está obsoleta. Utilice la API de URL WHATWG.

[Estable: 3 - Heredado]

Estable: 3 Estabilidad: 3 - Heredado: Utilice la API de URL WHATWG en su lugar.

El urlObject heredado (require('node:url').Url o import { Url } from 'node:url') se crea y devuelve mediante la función url.parse().

`urlObject.auth`

La propiedad auth es la parte del nombre de usuario y la contraseña de la URL, también conocida como información del usuario. Este subconjunto de cadenas sigue al protocol y a las barras dobles (si están presentes) y precede al componente host, delimitado por @. La cadena es el nombre de usuario o el nombre de usuario y la contraseña separados por :.

Por ejemplo: 'user:pass'.

`urlObject.hash`

La propiedad hash es la parte del identificador de fragmento de la URL, incluido el carácter # inicial.

Por ejemplo: '#hash'.

`urlObject.host`

La propiedad host es la parte completa del host en minúsculas de la URL, incluido el port si se especifica.

Por ejemplo: 'sub.example.com:8080'.

`urlObject.hostname`

La propiedad hostname es la parte del nombre de host en minúsculas del componente host sin incluir el port.

Por ejemplo: 'sub.example.com'.

`urlObject.href`

La propiedad href es la cadena URL completa que se analizó con los componentes protocol y host convertidos a minúsculas.

Por ejemplo: 'http://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash'.

`urlObject.path`

La propiedad path es una concatenación de los componentes pathname y search.

Por ejemplo: '/p/a/t/h?query=string'.

No se realiza ninguna decodificación del path.

`urlObject.pathname`

La propiedad pathname consiste en la sección completa del path de la URL. Esto es todo lo que sigue al host (incluyendo el port) y antes del inicio de los componentes query o hash, delimitado por el signo de interrogación ASCII (?) o el carácter hash (#).

Por ejemplo: '/p/a/t/h'.

No se realiza ninguna decodificación de la cadena del path.

`urlObject.port`

La propiedad port es la porción numérica del puerto del componente host.

Por ejemplo: '8080'.

`urlObject.protocol`

La propiedad protocol identifica el esquema del protocolo en minúsculas de la URL.

Por ejemplo: 'http:'.

`urlObject.query`

La propiedad query es o bien la cadena de consulta sin el signo de interrogación ASCII (?) inicial, o un objeto devuelto por el método parse() del módulo querystring. Si la propiedad query es una cadena o un objeto se determina por el argumento parseQueryString pasado a url.parse().

Por ejemplo: 'query=string' o {'query': 'string'}.

Si se devuelve como una cadena, no se realiza ninguna decodificación de la cadena de consulta. Si se devuelve como un objeto, tanto las claves como los valores se decodifican.

`urlObject.search`

La propiedad search consiste en la porción completa de la "cadena de consulta" de la URL, incluyendo el signo de interrogación ASCII (?) inicial.

Por ejemplo: '?query=string'.

No se realiza ninguna decodificación de la cadena de consulta.

`urlObject.slashes`

La propiedad slashes es un boolean con un valor de true si se requieren dos caracteres de barra diagonal ASCII (/) después de los dos puntos en el protocol.

`url.format(urlObject)`

[Historia]

Versión	Cambios
v17.0.0	Ahora lanza una excepción `ERR_INVALID_URL` cuando la conversión Punycode de un nombre de host introduce cambios que podrían causar que la URL se vuelva a analizar de manera diferente.
v15.13.0, v14.17.0	Revocada la obsolescencia. Estado cambiado a "Legacy".
v11.0.0	La API de URL Legacy está obsoleta. Use la API de URL WHATWG.
v7.0.0	Las URL con un esquema `file:` ahora siempre usarán el número correcto de barras diagonales independientemente de la opción `slashes`. Una opción `slashes` falsa sin protocolo ahora también se respeta en todo momento.
v0.1.25	Agregado en: v0.1.25

[Estable: 3 - Legacy]

Estable: 3 Estabilidad: 3 - Legacy: Use la API de URL WHATWG en su lugar.

urlObject <Object> | <string> Un objeto URL (como el devuelto por url.parse() o construido de otra manera). Si es una cadena, se convierte en un objeto pasándolo a url.parse().

El método url.format() devuelve una cadena URL formateada derivada de urlObject.

const url = require('node:url');
url.format({
  protocol: 'https',
  hostname: 'example.com',
  pathname: '/some/path',
  query: {
    page: 1,
    format: 'json',
  },
});

// => 'https://example.com/some/path?page=1&format=json'

Si urlObject no es un objeto o una cadena, url.format() lanzará un TypeError.

El proceso de formateo opera de la siguiente manera:

Se crea una nueva cadena vacía result.
Si urlObject.protocol es una cadena, se añade tal cual a result.
De lo contrario, si urlObject.protocol no es undefined y no es una cadena, se lanza un Error.
Para todos los valores de cadena de urlObject.protocol que no terminan con un carácter de dos puntos ASCII (:), la cadena literal : se añadirá a result.
Si cualquiera de las siguientes condiciones es verdadera, entonces la cadena literal // se añadirá a result:
- La propiedad urlObject.slashes es verdadera;
- urlObject.protocol comienza con http, https, ftp, gopher, o file;
Si el valor de la propiedad urlObject.auth es verdadero, y ya sea urlObject.host o urlObject.hostname no son undefined, el valor de urlObject.auth se coaccionará a una cadena y se añadirá a result seguido de la cadena literal @.
Si la propiedad urlObject.host es undefined entonces:
- Si urlObject.hostname es una cadena, se añade a result.
- De lo contrario, si urlObject.hostname no es undefined y no es una cadena, se lanza un Error.
- Si el valor de la propiedad urlObject.port es verdadero, y urlObject.hostname no es undefined:
- La cadena literal : se añade a result, y
- El valor de urlObject.port se coacciona a una cadena y se añade a result.
De lo contrario, si el valor de la propiedad urlObject.host es verdadero, el valor de urlObject.host se coacciona a una cadena y se añade a result.
Si la propiedad urlObject.pathname es una cadena que no es una cadena vacía:
- Si urlObject.pathname no comienza con una barra diagonal ASCII (/), entonces la cadena literal '/' se añade a result.
- El valor de urlObject.pathname se añade a result.
De lo contrario, si urlObject.pathname no es undefined y no es una cadena, se lanza un Error.
Si la propiedad urlObject.search es undefined y si la propiedad urlObject.query es un Object, la cadena literal ? se añade a result seguido de la salida de la llamada al método stringify() del módulo querystring pasando el valor de urlObject.query.
De lo contrario, si urlObject.search es una cadena:
- Si el valor de urlObject.search no comienza con el signo de interrogación ASCII (?), la cadena literal ? se añade a result.
- El valor de urlObject.search se añade a result.
De lo contrario, si urlObject.search no es undefined y no es una cadena, se lanza un Error.
Si la propiedad urlObject.hash es una cadena:
- Si el valor de urlObject.hash no comienza con el carácter hash ASCII (#), la cadena literal # se añade a result.
- El valor de urlObject.hash se añade a result.
De lo contrario, si la propiedad urlObject.hash no es undefined y no es una cadena, se lanza un Error.
result se devuelve.

`url.parse(urlString[, parseQueryString[, slashesDenoteHost]])`

[Historial]

Versión	Cambios
v19.0.0, v18.13.0	Deprecación solo en la documentación.
v15.13.0, v14.17.0	Deprecación revocada. Estado cambiado a "Legado".
v11.14.0	La propiedad `pathname` en el objeto URL devuelto ahora es `/` cuando no hay ruta y el esquema del protocolo es `ws:` o `wss:`.
v11.0.0	La API URL Legacy está obsoleta. Use la API URL de WHATWG.
v9.0.0	La propiedad `search` en el objeto URL devuelto ahora es `null` cuando no hay una cadena de consulta presente.
v0.1.25	Añadido en: v0.1.25

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto: Use la API URL de WHATWG en su lugar.

urlString <string> La cadena URL a analizar.
parseQueryString <boolean> Si es true, la propiedad query siempre se establecerá en un objeto devuelto por el método parse() del módulo querystring. Si es false, la propiedad query en el objeto URL devuelto será una cadena sin analizar y sin decodificar. Predeterminado: false.
slashesDenoteHost <boolean> Si es true, el primer token después de la cadena literal // y precediendo al siguiente / se interpretará como el host. Por ejemplo, dado //foo/bar, el resultado sería {host: 'foo', pathname: '/bar'} en lugar de {pathname: '//foo/bar'}. Predeterminado: false.

El método url.parse() toma una cadena URL, la analiza y devuelve un objeto URL.

Se lanza un TypeError si urlString no es una cadena.

Se lanza un URIError si la propiedad auth está presente pero no se puede decodificar.

url.parse() utiliza un algoritmo flexible y no estándar para analizar cadenas URL. Es propenso a problemas de seguridad, como la suplantación de nombres de host y el manejo incorrecto de nombres de usuario y contraseñas. No lo use con entradas que no sean de confianza. No se emiten CVE para las vulnerabilidades de url.parse(). Use la API URL de WHATWG en su lugar.

`url.resolve(from, to)`

[Historial]

Versión	Cambios
v15.13.0, v14.17.0	Revocada la obsolescencia. Estado cambiado a "Legacy".
v11.0.0	La API de URL Legacy está obsoleta. Utilice la API de URL WHATWG.
v6.6.0	Los campos `auth` ahora se mantienen intactos cuando `from` y `to` se refieren al mismo host.
v6.0.0	El campo `auth` ahora se borra cuando el parámetro `to` contiene un nombre de host.
v6.5.0, v4.6.2	El campo `port` ahora se copia correctamente.
v0.1.25	Agregado en: v0.1.25

[Estable: 3 - Legacy]

Estable: 3 Estabilidad: 3 - Legacy: Utilice la API de URL WHATWG en su lugar.

from <string> La URL base que se utilizará si to es una URL relativa.
to <string> La URL de destino a resolver.

El método url.resolve() resuelve una URL de destino relativa a una URL base de forma similar a como un navegador web resuelve una etiqueta de anclaje.

const url = require('node:url');
url.resolve('/one/two/three', 'four');         // '/one/two/four'
url.resolve('http://example.com/', '/one');    // 'http://example.com/one'
url.resolve('http://example.com/one', '/two'); // 'http://example.com/two'

Para lograr el mismo resultado utilizando la API de URL WHATWG:

function resolve(from, to) {
  const resolvedUrl = new URL(to, new URL(from, 'resolve://'));
  if (resolvedUrl.protocol === 'resolve:') {
    // `from` es una URL relativa.
    const { pathname, search, hash } = resolvedUrl;
    return pathname + search + hash;
  }
  return resolvedUrl.toString();
}

resolve('/one/two/three', 'four');         // '/one/two/four'
resolve('http://example.com/', '/one');    // 'http://example.com/one'
resolve('http://example.com/one', '/two'); // 'http://example.com/two'

Codificación de porcentaje en URLs

Las URLs solo pueden contener un cierto rango de caracteres. Cualquier carácter que quede fuera de ese rango debe estar codificado. Cómo se codifican tales caracteres y qué caracteres codificar depende completamente de dónde se encuentre el carácter dentro de la estructura de la URL.

API Legado

Dentro del API Legado, los espacios (' ') y los siguientes caracteres se escaparán automáticamente en las propiedades de los objetos URL:

text

< > " ` \r \n \t { } | \ ^ '

Por ejemplo, el carácter de espacio ASCII (' ') se codifica como %20. El carácter de barra inclinada ASCII (/) se codifica como %3C.

API WHATWG

El Estándar de URL WHATWG utiliza un enfoque más selectivo y preciso para seleccionar los caracteres codificados que el que utiliza el API Legado.

El algoritmo WHATWG define cuatro "conjuntos de codificación de porcentaje" que describen rangos de caracteres que deben codificarse con porcentaje:

El conjunto de codificación de porcentaje de control C0 incluye puntos de código en el rango U+0000 a U+001F (inclusive) y todos los puntos de código mayores que U+007E (~).
El conjunto de codificación de porcentaje de fragmento incluye el conjunto de codificación de porcentaje de control C0 y los puntos de código U+0020 SPACE, U+0022 ("), U+003C (<), U+003E (>), y U+0060 (`).
El conjunto de codificación de porcentaje de ruta incluye el conjunto de codificación de porcentaje de control C0 y los puntos de código U+0020 SPACE, U+0022 ("), U+0023 (#), U+003C (<), U+003E (>), U+003F (?), U+0060 (`), U+007B ({), y U+007D (}).
El conjunto de codificación de información de usuario incluye el conjunto de codificación de porcentaje de ruta y los puntos de código U+002F (/), U+003A (😃, U+003B (😉, U+003D (=), U+0040 (@), U+005B ([) a U+005E(^), y U+007C (|).

El conjunto de codificación de porcentaje de información de usuario se utiliza exclusivamente para el nombre de usuario y las contraseñas codificadas dentro de la URL. El conjunto de codificación de porcentaje de ruta se utiliza para la ruta de la mayoría de las URLs. El conjunto de codificación de porcentaje de fragmento se utiliza para los fragmentos de URL. El conjunto de codificación de porcentaje de control C0 se utiliza para el host y la ruta bajo ciertas condiciones específicas, además de todos los demás casos.

Cuando aparecen caracteres no ASCII dentro de un nombre de host, el nombre de host se codifica utilizando el algoritmo Punycode. Sin embargo, tenga en cuenta que un nombre de host puede contener tanto caracteres codificados con Punycode como caracteres codificados con porcentaje:

const myURL = new URL('https://%CF%80.example.com/foo');
console.log(myURL.href);
// Prints https://xn--1xa.example.com/foo
console.log(myURL.origin);
// Prints https://xn--1xa.example.com

URL ​

Cadenas de URL y objetos de URL ​

Construcción de una URL a partir de componentes y obtención de la cadena construida ​

La API URL de WHATWG ​

Clase: URL ​

new URL(input[, base]) ​

url.hash ​

url.host ​

url.hostname ​

url.href ​

url.origin ​

url.password ​

url.pathname ​

url.port ​

url.protocol ​

Esquemas especiales ​

url.search ​

url.searchParams ​

url.username ​

url.toString() ​

url.toJSON() ​

URL.createObjectURL(blob) ​

URL.revokeObjectURL(id) ​

URL.canParse(input[, base]) ​

URL.parse(input[, base]) ​

Clase: URLSearchParams ​

new URLSearchParams() ​

new URLSearchParams(string) ​

new URLSearchParams(obj) ​

new URLSearchParams(iterable) ​

urlSearchParams.append(name, value) ​

urlSearchParams.delete(name[, value]) ​

urlSearchParams.entries() ​

urlSearchParams.forEach(fn[, thisArg]) ​

urlSearchParams.get(name) ​

urlSearchParams.getAll(name) ​

urlSearchParams.has(name[, value]) ​

urlSearchParams.keys() ​

urlSearchParams.set(name, value) ​

urlSearchParams.size ​

urlSearchParams.sort() ​

urlSearchParams.toString() ​

urlSearchParams.values() ​

urlSearchParams[Symbol.iterator]() ​

url.domainToASCII(domain) ​

url.domainToUnicode(domain) ​

url.fileURLToPath(url[, options]) ​

url.format(URL[, options]) ​

url.pathToFileURL(path[, options]) ​

url.urlToHttpOptions(url) ​

API de URL heredado ​

urlObject heredado ​

urlObject.auth ​

urlObject.hash ​

urlObject.host ​

urlObject.hostname ​

urlObject.href ​

urlObject.path ​

urlObject.pathname ​

urlObject.port ​

urlObject.protocol ​

urlObject.query ​

urlObject.search ​

urlObject.slashes ​

url.format(urlObject) ​

url.parse(urlString[, parseQueryString[, slashesDenoteHost]]) ​

url.resolve(from, to) ​

Codificación de porcentaje en URLs ​

API Legado ​

API WHATWG ​

URL

Cadenas de URL y objetos de URL

Construcción de una URL a partir de componentes y obtención de la cadena construida

La API URL de WHATWG

Clase: `URL`

`new URL(input[, base])`

`url.hash`

`url.host`

`url.hostname`

`url.href`

`url.origin`

`url.password`

`url.pathname`

`url.port`

`url.protocol`

Esquemas especiales

`url.search`

`url.searchParams`

`url.username`

`url.toString()`

`url.toJSON()`

`URL.createObjectURL(blob)`

`URL.revokeObjectURL(id)`

`URL.canParse(input[, base])`

`URL.parse(input[, base])`

Clase: `URLSearchParams`

`new URLSearchParams()`

`new URLSearchParams(string)`

`new URLSearchParams(obj)`

`new URLSearchParams(iterable)`

`urlSearchParams.append(name, value)`

`urlSearchParams.delete(name[, value])`

`urlSearchParams.entries()`

`urlSearchParams.forEach(fn[, thisArg])`

`urlSearchParams.get(name)`

`urlSearchParams.getAll(name)`

`urlSearchParams.has(name[, value])`

`urlSearchParams.keys()`

`urlSearchParams.set(name, value)`

`urlSearchParams.size`

`urlSearchParams.sort()`

`urlSearchParams.toString()`

`urlSearchParams.values()`

`urlSearchParams[Symbol.iterator]()`

`url.domainToASCII(domain)`

`url.domainToUnicode(domain)`

`url.fileURLToPath(url[, options])`

`url.format(URL[, options])`

`url.pathToFileURL(path[, options])`

`url.urlToHttpOptions(url)`

API de URL heredado

`urlObject` heredado

`urlObject.auth`

`urlObject.hash`

`urlObject.host`

`urlObject.hostname`

`urlObject.href`

`urlObject.path`

`urlObject.pathname`

`urlObject.port`

`urlObject.protocol`

`urlObject.query`

`urlObject.search`

`urlObject.slashes`

`url.format(urlObject)`

`url.parse(urlString[, parseQueryString[, slashesDenoteHost]])`

`url.resolve(from, to)`

Codificación de porcentaje en URLs

API Legado

API WHATWG