readonly-url

An immutable TypeScript wrapper around the platform URL class.

import { rurl } from "@lebedevna/readonly-url";

const url = rurl("/articles?tag=web", "https://example.com");

url.pathname; // "/articles"
url.searchParams.get("tag"); // "web"

const nextUrl = url
  .withPathname("/guides")
  .withSearchParam("page", "2")
  .withHash("getting-started");

ReadonlyURL delegates parsing and serialization to the built-in URL class, while keeping its internal instance private. searchParams and toURL() each return copies, so callers cannot mutate the original value.

Use with() to update several properties at once, or the chainable withProtocol, withUsername, withPassword, withHost, withHostname, withPort, withPathname, withSearch, and withHash methods. Query helpers include withSearchParams, withSearchParam, and withoutSearchParam; query values may be strings, numbers, or booleans.

Agent skill

The package ships a TanStack Intent-compatible skill for coding agents. In a project that depends on this package, discover or load it with:

pnpm dlx @tanstack/intent@latest list
pnpm dlx @tanstack/intent@latest load @lebedevna/readonly-url#readonly-url

Development

npm test