URL dan Query String JavaScript: URL dan URLSearchParams

Berhenti mem-parse URL dengan trik string

Sebelum API URL ada, orang memotong URL dengan split('?'), regex, dan harapan. Biasanya berhasil, sampai sebuah nilai berisi &, =, spasi, atau karakter non-ASCII, dan saat itu gagal. Browser dan Node sama-sama menyediakan parser yang layak. Pakailah.

const u = new URL("https://shop.example.com/products?id=42&color=red#reviews");

console.log(u.protocol);   // "https:"
console.log(u.host);       // "shop.example.com"
console.log(u.pathname);   // "/products"
console.log(u.search);     // "?id=42&color=red"
console.log(u.hash);       // "#reviews"

Satu pemanggilan, dan setiap bagian URL sudah terpisah dan ter-decode dengan benar. Constructor-nya melempar TypeError pada input yang tidak valid, dan biasanya memang itulah yang kamu mau: URL sampah sebaiknya gagal dengan jelas daripada diam-diam menghasilkan sampah di tahap berikutnya.

Membaca parameter query

Setiap URL punya property .searchParams, yaitu object URLSearchParams yang tahu cara membaca dan menulis query string:

const u = new URL("https://example.com/search?q=javascript&page=2&tag=web&tag=beginner");

console.log(u.searchParams.get("q"));        // "javascript"
console.log(u.searchParams.get("page"));     // "2"
console.log(u.searchParams.getAll("tag"));   // ["web", "beginner"]
console.log(u.searchParams.has("sort"));     // false
console.log(u.searchParams.get("sort"));     // null

Beberapa hal yang perlu diperhatikan:

• Nilai yang kembali sudah di-decode. ?name=Ada%20Lovelace memberimu "Ada Lovelace".
• Semuanya berupa string. "2" bukan 2. Konversi dengan Number() kalau kamu butuh angka.
• Key yang berulang itu sah. get mengembalikan kecocokan pertama; getAll mengembalikan setiap kecocokan.
• Key yang tidak ada mengembalikan null, bukan undefined, jadi ?? "default" cocok dipakai bersamanya.

Menyusun query string

Kamu bisa menyusun query string dari nol dengan URLSearchParams, tanpa escape manual, tanpa menggabungkan dengan &:

const params = new URLSearchParams();
params.set("q", "hello world");
params.set("page", "2");
params.append("tag", "js");
params.append("tag", "beginner");

console.log(params.toString());
// "q=hello+world&page=2&tag=js&tag=beginner"

Atau buat dari sebuah object: iterable apa pun berisi pasangan [key, value] bisa dipakai, begitu juga object biasa:

const params = new URLSearchParams({
    q: "café",
    page: "1",
    sort: "new",
});

console.log(params.toString());
// "q=caf%C3%A9&page=1&sort=new"

set vs append: set mengganti nilai yang sudah ada untuk key itu. append menambahkan satu lagi. Pakai append saat sebuah key memang boleh berulang (tag, filter); pakai set untuk parameter bernilai tunggal.

Mengubah URL

Karena URL adalah object yang hidup, mengubah searchParams otomatis memperbarui .search dan .href:

const u = new URL("https://example.com/search?q=js");

u.searchParams.set("page", "2");
u.searchParams.set("q", "typescript");     // overwrites
u.searchParams.delete("utm_source");       // no-op if absent

console.log(u.href);
// "https://example.com/search?q=typescript&page=2"

Inilah cara idiomatis menambahkan parameter query ke URL yang sudah ada. Tanpa pengecekan "apakah URL-nya sudah punya ?", tanpa pusing apakah harus mengawali dengan & atau ?.

Kamu bisa mengubah bagian lain dari URL dengan cara yang sama:

const u = new URL("https://example.com/old");

u.pathname = "/new";
u.hash = "top";

console.log(u.href);
// "https://example.com/new#top"

Menelusuri parameter

URLSearchParams bersifat iterable. for...of memberimu pasangan [key, value], dan ada juga helper yang biasa: keys(), values(), dan entries():

const u = new URL("https://example.com/?q=js&page=2&tag=web&tag=beginner");

for (const [key, value] of u.searchParams) {
    console.log(key, "=", value);
}

Perhatikan bahwa key yang berulang muncul beberapa kali: kamu akan melihat tag = web lalu tag = beginner sebagai entri terpisah. Itu sesuai dengan query string yang sebenarnya.

Kalau kamu ingin object biasa untuk print debug cepat, Object.fromEntries bisa dipakai, tapi ia meringkas key yang berulang dan hanya menyimpan nilai terakhir:

const u = new URL("https://example.com/?q=js&tag=web&tag=beginner");

const obj = Object.fromEntries(u.searchParams);
console.log(obj);   // { q: "js", tag: "beginner" }

Tidak masalah untuk debugging. Salah kalau ada key yang bisa berulang.

URL relatif butuh base

new URL("/search?q=js") saja akan melempar error: path relatif bukan URL yang valid kalau berdiri sendiri. Kirim base sebagai argumen kedua:

const base = "https://example.com/app/";

const u1 = new URL("/search?q=js", base);
const u2 = new URL("profile", base);
const u3 = new URL("../about", base);

console.log(u1.href);   // "https://example.com/search?q=js"
console.log(u2.href);   // "https://example.com/app/profile"
console.log(u3.href);   // "https://example.com/about"

Aturan resolusinya sama dengan yang dipakai browser untuk <a href>: / di awal berarti absolut dari host, tanpa garis miring berarti relatif terhadap path saat ini, .. naik satu tingkat. Sangat praktis saat kamu menyusun URL API dari base yang sudah dikonfigurasi.

Di browser, window.location.href adalah base siap pakai untuk mem-parse URL halaman saat ini:

const u = new URL(window.location.href);
const page = u.searchParams.get("page") ?? "1";

Menangani URL yang tidak valid

Constructor URL melempar error pada input yang rusak. Itu berguna, tapi artinya kamu butuh try/catch saat mem-parse apa pun yang diketik pengguna atau dikirim sistem luar:

function safeParse(input) {
    try {
        return new URL(input);
    } catch {
        return null;
    }
}

console.log(safeParse("https://example.com/ok"));   // URL object
console.log(safeParse("not a url"));                // null
console.log(safeParse(""));                         // null

Lingkungan modern juga menyediakan URL.canParse(input), pengecekan boolean yang tidak perlu repot dengan try/catch saat kamu hanya ingin memvalidasi:

console.log(URL.canParse("https://example.com"));   // true
console.log(URL.canParse("nope"));                  // false

Contoh kecil yang berfungsi

Menyatukan semuanya: baca filter saat ini dari sebuah URL, ubah, lalu hasilkan URL baru untuk dituju:

function updateFilters(href, changes) {
    const u = new URL(href);

    for (const [key, value] of Object.entries(changes)) {
        if (value === null) {
            u.searchParams.delete(key);
        } else {
            u.searchParams.set(key, value);
        }
    }
    return u.href;
}

const current = "https://shop.example.com/products?category=shoes&page=3&sort=price";

console.log(updateFilters(current, { page: "1", sort: null, color: "red" }));
// "https://shop.example.com/products?category=shoes&page=1&color=red"

Mengirim null menghapus parameternya. Nilai lain mengisi atau menimpanya. Pola ini akan kamu tulis dalam satu bentuk atau lainnya setiap kali kamu membuat UI filter, pagination, atau deep link.

Yang perlu kamu ingat

• new URL(string) mem-parse URL menjadi bagian-bagian berlabel. Ia melempar error pada input sampah.
• url.searchParams adalah URLSearchParams: pakai get, getAll, set, append, delete, has.
• Encoding dilakukan untukmu. Jangan pakai encodeURIComponent kecuali kamu menyusun string secara manual.
• Kirim URL base sebagai argumen kedua untuk me-resolve path relatif.
• URL.canParse (atau try/catch) adalah alat validasimu untuk input yang tidak bisa dipercaya.

Setiap kali kamu tergoda memotong URL dengan .split('?') atau mengambil parameter query dengan regex, pakai API ini saja. Lebih pendek, benar, dan sudah tersedia di runtime.