Url

The Url module is one of the core building blocks of fx-fetch. The module contains functions and types to create and manipulate URLs.

The Url Type

A Url represents immutable and clonable HTTP URL data. It is a base element of the Url module.

import { Url } from 'fx-fetch';

type Type = Url.Url;

The Input Type

A Url.Input represents all the possible inputs that can be used to create a Url.

Concrete types that make up the Input union:

import { Url } from 'fx-fetch';

type Type = Url.Url.Input;

• string — a simple string URL
• globalThis.URL — the built-in JavaScript URL class
• Url.Url.Parts — an object containing individual parts of a URL
• Url.Url.Options — an object containing a URL string and optional search parameters
• Url.Url — existing Url can be used too

Constructors

unsafeMake

Creates a Url from any of Url.Input. Throws an IllegalArgumentException if the provided input is invalid.

import { Url } from 'fx-fetch';

//     ┌─── Url.Url
//     ▼
const url = Url.unsafeMake('https://example.com/');

make

Similar to unsafeMake, but returns an Option instead of throwing an error if the input is invalid. If the input is invalid, it returns None. If valid, it returns Some containing the Url.

import { Option } from 'effect';
import { Url } from 'fx-fetch';

//     ┌─── Option.Option<Url.Url>
//     ▼
const url = Url.make('https://example.com/');

from Url.Parts

For creating a Url from an object Url.Parts use same functions make or unsafeMake.

The Parts type is super primitive. It’s basically an object with properties similar to the built-in JavaScript URL object, but with better DX. Everything except the hostname is optional.

import { Url } from 'fx-fetch';

const parts: Url.Url.Parts = {
  protocol: 'https:',
  username: 'admin',
  password: '123456',
  hostname: 'example.com', // ◀︎── required property
  pathname: '/api/v1/resource',
  port: 8080,
  searchParams: {
    key: 'value',
    filter: ['a', 'b'],
    id: 123,
  },
  hash: '#section',
};

const url = Url.unsafeMake(parts);

All properties are designed for better DX. Here is a brief description of each:

• protocol — The protocol scheme of the URL (e.g., "http:", "https://", "ftp")
• username — The username of credentials, automatically percent-encoded
• password — The password of credentials, automatically percent-encoded
• hostname — The domain name or IP address of the URL (e.g., "example.com", "example.net/")
• pathname — The path component of the URL (e.g., "/path/to/", "foo/bar")
• port — The port number of the URL (e.g., 80, "443")
• hash — The fragment identifier of the URL (e.g., "#section1", "top")
• searchParams — Query parameters with various supported types:
  • instance of globalThis.URLSearchParams
  • object with string, number, undefined or array of string | number | undefined values
  • instance of Map
  • array of tuples

---

from Url.Options

For creating a Url from an object Url.Options use same functions make or unsafeMake.

Reason for having this variant is your comfort.

import { Url } from 'fx-fetch';

const options: Url.Url.Options = {
  url: 'https://example.com', // ◀︎── required property
  searchParams: {
    q: 'lorem ipsum',
    page: 1,
    filter: ['active', 'new'],
  },
};

const url = Url.unsafeMake(options);

---

Conversions

format

Formats the Url into a string representation.

import { Url } from 'fx-fetch';

const url = Url.unsafeMake({
  url: 'https://example.com',
  searchParams: {
    q: 'lorem ipsum',
    page: 1,
    filter: ['active', 'new'],
    category: undefined,
  },
});

Url.format(url); // 'https://example.com?q=lorem+ipsum&page=1&filter=active&filter=new'

---

Combinators

appendSearchParam

The appendSearchParam function appends a new search parameter to the existing URL’s query string.

import { Url } from 'fx-fetch';

const url = Url.unsafeMake({
  url: 'https://example.com',
  searchParams: {
    tag: "new"
  },
}); // 'https://example.com?tag=new'

const updatedUrl = Url.appendSearchParam(url, 'tag', 'active'); // 'https://example.com?tag=new&tag=active'

setSearchParam

The setSearchParam function sets or updates a search parameter in the existing URL’s query string.

If the value is undefined, the parameter is removed.

import { Url } from 'fx-fetch';

const url = Url.unsafeMake({
  url: 'https://example.com',
  searchParams: {
    tag: "new"
  },
}); // 'https://example.com?tag=new'

const updatedUrl = Url.setSearchParam(url, 'tag', 'active'); // 'https://example.com?tag=active'

setSearchParams

The setSearchParams function sets or updates multiple search parameters in the existing URL’s query string.

import { Url } from 'fx-fetch';

const url = Url.unsafeMake({
  url: 'https://example.com',
  searchParams: {
    tag: ['new', 'sale'],
  },
});

Url.format(url); // 'https://example.com?tag=new&tag=sale'

// Set 'tag' parameter to 'active', replacing existing values
url.pipe(
  Url.setSearchParams({
    "tag": "active"
  }),
  Url.format // 'https://example.com?tag=active'
);

// Add new 'q' parameter without removing existing ones
url.pipe(
  Url.setSearchParams({
    "q": "Lorem ipsum",
  }),
  Url.format // 'https://example.com?tag=new&tag=sale&q=Lorem+ipsum'
);

deleteSearchParam

The deleteSearchParam function removes a search parameter from the existing URL’s query string.

Can be used to remove a specific value for a parameter or all values associated with that parameter.

import { Url } from 'fx-fetch';

const url = Url.unsafeMake({
  url: 'https://example.com',
  searchParams: {
    tag: ['new', 'sale'],
  },
});

Url.format(url); // 'https://example.com?tag=new&tag=sale'

// Remove specific 'tag' parameter
url.pipe(
  Url.deleteSearchParam('tag', 'sale'),
  Url.format // 'https://example.com?tag=new'
);

// Remove all 'tag' parameters
url.pipe(
  Url.deleteSearchParam('tag', undefined),
  Url.format // 'https://example.com'
);