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.

1
import { Url } from 'fx-fetch';

Constructors

You can make a Url from any of Url.Url.Input. This this is a just an union of all possible inputs that can be used.

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 — another Url instance (deep cloned)

1
const urlString: string = 'https://example.com/path?query=param#hash'; // Simple string URL. Don't worry, validation is done internally.
2

3
const jsUrl = new URL('https://example.com/path?query=param#hash'); // Vanilla JS URL object.
4

5
const urlOptions: Url.Url.Options = {
6
  url: 'https://example.com/path?query=param#hash',
7
  searchParams: {
8
    id: '123',
9
    page: 1,
10
    category: ['books', 'electronics'], // Arrays are supported too!
11
    'is-active': undefined, // Keys with `undefined` values are omitted from the final URL
12
  }, // `searchParams` is a `SearchParamsInput` type. Rich ways to specify search params! DX is important.
13
};
14

15
const urlParts: Url.Url.Parts = {
16
  protocol: 'https:', // Smartly handles trailing ':' character
17
  username: 'john',
18
  password: '123',
19
  hostname: 'example.com',
20
  pathname: '/path', // Smartly handles leading '/' character
21
  hash: '#hash', // Smartly handles leading '#' character
22
  searchParams: undefined, // `searchParams` is optional. Has the same type as `Url.Url.Options['searchParams']` ↑.
23
  port: 443, // Port can be a string or number
24
};
25

26
declare const url: Url.Url; // Of course, you can create Urls from other Urls too. Deep cloning is done internally.

make vs unsafeMake

Because a URL input can be anything, even something nonsensical, there are two ways to create a URL object: Safe and unsafe.

The safe way is recommended especially in non-manual use cases (like when a URL comes from user input, external API, etc.) But if you place the URL manually and are sure it’s valid, you can use the unsafe way.

make

1
// Safe way returns `Option.Option<Url.Url>`
2
//
3
//        ┌── Option.Option<Url.Url>
4
//        ▼
5
const maybeUrl = Url.make(urlString); // Validates the input URL. If invalid, returns `Option.none()`.
6

7
const nonsenseJsUrl = new globalThis.URL('Hello nonsense'); // Throws an error. Uncaught ReferenceError: Url is not defined
8
const maybeNonsenseUrl = Url.make('Hello nonsense'); // Returns `Option.none()` instead of throwing.

unsafeMake

1
// Unsafe way returns `Url.Url` or throws
2
//
3
//        ┌── Url.Url
4
//        ▼
5
const certainUrl = Url.unsafeMake(urlString); // If URL is invalid, `Effect.die` is called internally.