Url unstable

Parses and edits platform URL values.

The HTTP modules use the standard URL object as their URL representation. This module adds safe parsing and helpers that return updated copies when changing credentials, host, path, protocol, query, or hash parts. Query strings can also be read or updated through UrlParams.

17 exports Since v4.0.0 Source

Constructors

fromString

unstable

Since v4.0.0

Parses a URL string safely into a URL object, returning a Result type for error handling.

Details

This function converts a string into a URL object, enabling safe URL parsing with built-in error handling. If the string is invalid or fails to parse, this function does not throw an error; instead, it wraps the error in a IllegalArgumentError and returns it as the Failure value of an Result. The Success value contains the successfully parsed URL.

An optional base parameter can be provided to resolve relative URLs. If specified, the function interprets the input url as relative to this base. This is especially useful when dealing with URLs that might not be fully qualified.

Signature

declare const fromString: (url: string, base?: string | URL) => Result<URL, IllegalArgumentError>

Example Parsing absolute and relative URLs

import { Result } from "effect"
import { Url } from "effect/http"

// Parse an absolute URL
//
//      ┌─── Result<URL, IllegalArgumentError>
//      ▼
const parsed = Url.fromString("https://example.com/path")

Result.map(parsed, (url) => url.toString()) // => Result.succeed("https://example.com/path")

// Parse a relative URL with a base
const relativeParsed = Url.fromString("/relative-path", "https://example.com")

Result.map(relativeParsed, (url) => url.toString()) // => Result.succeed("https://example.com/relative-path")

make

unstable

Since v4.0.0

Creates a URL safely by appending UrlParams and an optional hash to a URL string.

Details

Returns a Result that fails with UrlError if the URL cannot be constructed.

Signature

declare function make(url: string, params: UrlParams, hash: string | undefined): Result<URL, UrlError>

Errors

UrlError

unstable

Since v4.0.0

Error returned when constructing a URL fails.

Signature

declare class UrlError extends YieldableError<this> & {
  readonly _tag: "UrlError";
} & Readonly<{
  readonly cause: unknown;
}> {
  constructor(args: {
    readonly cause: unknown;
  });
}

Getters

urlParams

unstable

Since v4.0.0

Retrieves the query parameters from a URL.

Details

This function extracts the query parameters from a URL object and returns them as UrlParams. The resulting structure can be easily manipulated or inspected.

Signature

declare function urlParams(url: URL): UrlParams

Example Reading query parameters

import { Url, UrlParams } from "effect/http"

const myUrl = new URL("https://example.com?foo=bar")

// Read parameters
const params = Url.urlParams(myUrl)

UrlParams.toString(params) // => "foo=bar"

Setters

setHash

unstable

Since v4.0.0

Updates the hash fragment of the URL.

Signature

declare const setHash: {
  (hash: string): (url: URL) => URL;
  (url: URL, hash: string): URL;
}

setHost

unstable

Since v4.0.0

Updates the host (domain and port) of the URL.

Signature

declare const setHost: {
  (host: string): (url: URL) => URL;
  (url: URL, host: string): URL;
}

setHostname

unstable

Since v4.0.0

Updates the domain of the URL without modifying the port.

Signature

declare const setHostname: {
  (hostname: string): (url: URL) => URL;
  (url: URL, hostname: string): URL;
}

setHref

unstable

Since v4.0.0

Replaces the entire URL string.

Signature

declare const setHref: {
  (href: string): (url: URL) => URL;
  (url: URL, href: string): URL;
}

setPassword

unstable

Since v4.0.0

Updates the password used for authentication.

Signature

declare const setPassword: {
  (password: string | Redacted<string>): (url: URL) => URL;
  (url: URL, password: string | Redacted<string>): URL;
}

setPathname

unstable

Since v4.0.0

Updates the path of the URL.

Signature

declare const setPathname: {
  (pathname: string): (url: URL) => URL;
  (url: URL, pathname: string): URL;
}

setPort

unstable

Since v4.0.0

Updates the port of the URL.

Signature

declare const setPort: {
  (port: string | number): (url: URL) => URL;
  (url: URL, port: string | number): URL;
}

setProtocol

unstable

Since v4.0.0

Updates the protocol (e.g., http, https).

Signature

declare const setProtocol: {
  (protocol: string): (url: URL) => URL;
  (url: URL, protocol: string): URL;
}

setSearch

unstable

Since v4.0.0

Updates the query string of the URL.

Signature

declare const setSearch: {
  (search: string): (url: URL) => URL;
  (url: URL, search: string): URL;
}

setUrlParams

unstable

Since v4.0.0

Updates the query parameters of a URL.

Details

This function allows you to set or replace the query parameters of a URL object using the provided UrlParams. It creates a new URL object with the updated parameters, leaving the original object unchanged.

Signature

declare const setUrlParams: {
  (urlParams: Input): (url: URL) => URL;
  (url: URL, urlParams: Input): URL;
}

Example Replacing query parameters

import { Url, UrlParams } from "effect/http"

const myUrl = new URL("https://example.com?foo=bar")

// Write parameters
const updatedUrl = Url.setUrlParams(
  myUrl,
  UrlParams.fromInput([["key", "value"]])
)

updatedUrl.toString() // => "https://example.com/?key=value"

setUsername

unstable

Since v4.0.0

Updates the username used for authentication.

Signature

declare const setUsername: {
  (username: string): (url: URL) => URL;
  (url: URL, username: string): URL;
}

Transforming

modifyUrlParams

unstable

Since v4.0.0

Reads the query parameters of a URL, modifies them, and updates the URL.

Details

This function provides a functional way to interact with query parameters by reading the current parameters, applying a transformation function, and then writing the updated parameters back to the URL. It returns a new URL object with the modified parameters, ensuring immutability.

Signature

declare const modifyUrlParams: {
  (f: (urlParams: UrlParams) => Input): (url: URL) => URL;
  (url: URL, f: (urlParams: UrlParams) => Input): URL;
}

Example Modifying query parameters

import { Url, UrlParams } from "effect/http"

const myUrl = new URL("https://example.com?foo=bar")

const changedUrl = Url.modifyUrlParams(myUrl, UrlParams.append("key", "value"))

changedUrl.toString() // => "https://example.com/?foo=bar&key=value"

mutate

unstable

Since v4.0.0

Updates a cloned URL with a callback, allowing multiple changes at once.

Signature

declare const mutate: {
  (f: (url: URL) => void): (self: URL) => URL;
  (self: URL, f: (url: URL) => void): URL;
}

Example Mutating URL credentials

import { Url } from "effect/http"

const myUrl = new URL("https://example.com")

const mutatedUrl = Url.mutate(myUrl, (url) => {
  url.username = "user"
  url.password = "pass"
})

mutatedUrl.toString() // => "https://user:pass@example.com/"