Skip to main content Link Search Menu Expand Document (external link)
effect

Url overview

Added in v1.0.0

Table of contents

Constructors

fromString

Parses a URL string into a URL object, returning an Either type for safe 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 IllegalArgumentException and returns it as the Left value of an Either. The Right 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

export declare const fromString: (
  url: string,
  base?: string | URL | undefined
) => Either.Either<URL, Cause.IllegalArgumentException>

Example

import { Url } from "@effect/platform"
import { Either } from "effect"

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

if (Either.isRight(parsed)) {
  console.log("Parsed URL:", parsed.right.toString())
} else {
  console.log("Error:", parsed.left.message)
}
// Output: Parsed URL: https://example.com/path

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

if (Either.isRight(relativeParsed)) {
  console.log("Parsed relative URL:", relativeParsed.right.toString())
} else {
  console.log("Error:", relativeParsed.left.message)
}
// Output: Parsed relative URL: https://example.com/relative-path

Added in v1.0.0

Getters

urlParams

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

export declare const urlParams: (url: URL) => UrlParams.UrlParams

Example

import { Url } from "@effect/platform"

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

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

console.log(params)
// Output: [ [ 'foo', 'bar' ] ]

Added in v1.0.0

Modifiers

modifyUrlParams

Reads, modifies, and updates the query parameters of a 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

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

Example

import { Url, UrlParams } from "@effect/platform"

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

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

console.log(changedUrl.toString())
// Output: https://example.com/?foo=bar&key=value

Added in v1.0.0

mutate

This function clones the original URL object and applies a callback to the clone, allowing multiple updates at once.

Signature

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

Example

import { Url } from "@effect/platform"

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

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

console.log("Mutated:", mutatedUrl.toString())
// Output: Mutated: https://user:pass@example.com/

Added in v1.0.0

Setters

setHash

Updates the hash fragment of the URL.

Signature

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

Added in v1.0.0

setHost

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

Signature

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

Added in v1.0.0

setHostname

Updates the domain of the URL without modifying the port.

Signature

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

Added in v1.0.0

setHref

Replaces the entire URL string.

Signature

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

Added in v1.0.0

setPassword

Updates the password used for authentication.

Signature

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

Added in v1.0.0

setPathname

Updates the path of the URL.

Signature

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

Added in v1.0.0

setPort

Updates the port of the URL.

Signature

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

Added in v1.0.0

setProtocol

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

Signature

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

Added in v1.0.0

setSearch

Updates the query string of the URL.

Signature

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

Added in v1.0.0

setUrlParams

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

export declare const setUrlParams: {
  (urlParams: UrlParams.UrlParams): (url: URL) => URL
  (url: URL, urlParams: UrlParams.UrlParams): URL
}

Example

import { Url, UrlParams } from "@effect/platform"

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

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

console.log(updatedUrl.toString())
// Output: https://example.com/?key=value

Added in v1.0.0

setUsername

Updates the username used for authentication.

Signature

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

Added in v1.0.0