URL Building

Rezo provides a buildUri() method that constructs URLs from individual components and returns a RezoUri object. This is useful when you need to compose URLs programmatically from a base URL, path segments, query parameters, and authentication credentials.

import rezo from 'rezo';

const uri = rezo.buildUri({
  baseURL: 'https://api.example.com',
  pathname: '/v2/users',
  params: { role: 'admin', active: true },
});

console.log(uri.href);
// "https://api.example.com/v2/users?role=admin&active=true"

BuildUriOptions

The buildUri() method accepts a configuration object with the following properties:

Property	Type	Description
`url`	`string`	Full URL string. Used as the starting point if provided.
`baseURL`	`string`	Base URL. Combined with `pathname` when both are present.
`params`	`Record<string, any>`	Query parameters to append to the URL.
`paramsSerializer`	`(params: any) => string`	Custom function to serialize `params` into a query string.
`auth`	`{ username: string; password: string }`	Credentials encoded into the `userinfo` portion of the URL.
`href`	`string`	Full URL string (alias for `url`).
`protocol`	`string`	URL protocol (e.g., `'https:'`).
`hostname`	`string`	Host name without port.
`port`	`string \\| number`	Port number.
`pathname`	`string`	URL path (e.g., `'/api/users'`).
`search`	`string`	Raw query string (e.g., `'?key=value'`). Overridden by `params` if both are set.
`hash`	`string`	URL fragment (e.g., `'#section'`).

RezoUri

buildUri() returns a RezoUri object that provides a convenient API for reading and modifying the constructed URL.

Properties

Property	Type	Description
`href`	`string`	The full URL string.
`protocol`	`string`	The URL protocol (e.g., `'https:'`).
`hostname`	`string`	The host name.
`port`	`string`	The port number as a string.
`pathname`	`string`	The URL path.
`search`	`string`	The query string including the leading `?`.
`hash`	`string`	The fragment including the leading `#`.
`origin`	`string`	The URL origin (`protocol + '//' + host`).
`host`	`string`	The host including port if non-default.

params (getter / setter)

Read or replace the query parameters as a plain object:

const uri = rezo.buildUri({ url: 'https://api.example.com/search?q=rezo&page=1' });

// Read params
console.log(uri.params); // { q: 'rezo', page: '1' }

// Replace params
uri.params = { q: 'http-client', page: '2', sort: 'stars' };
console.log(uri.href);
// "https://api.example.com/search?q=http-client&page=2&sort=stars"

auth (getter / setter)

Read or set the userinfo credentials in the URL:

const uri = rezo.buildUri({
  url: 'https://api.example.com',
  auth: { username: 'admin', password: 's3cret' },
});

console.log(uri.href);
// "https://admin:s3cret@api.example.com"

// Read auth
console.log(uri.auth); // { username: 'admin', password: 's3cret' }

// Update auth
uri.auth = { username: 'root', password: 'newpass' };

clone()

Returns a new RezoUri with the same URL. Mutations on the clone do not affect the original:

const original = rezo.buildUri({ url: 'https://example.com/path?a=1' });
const copy = original.clone();

copy.params = { a: '2' };

console.log(original.href); // "https://example.com/path?a=1"
console.log(copy.href);     // "https://example.com/path?a=2"

toObject()

Returns a plain object with all URL components:

const uri = rezo.buildUri({ url: 'https://api.example.com:8080/v1/users?active=true#top' });

console.log(uri.toObject());
// {
//   href: 'https://api.example.com:8080/v1/users?active=true#top',
//   protocol: 'https:',
//   hostname: 'api.example.com',
//   port: '8080',
//   pathname: '/v1/users',
//   search: '?active=true',
//   hash: '#top',
//   origin: 'https://api.example.com:8080',
//   host: 'api.example.com:8080',
//   params: { active: 'true' }
// }

toJSON()

Same as toObject(). Allows RezoUri instances to be serialized with JSON.stringify().

Examples

Building a URL from parts

const uri = rezo.buildUri({
  protocol: 'https:',
  hostname: 'api.example.com',
  port: 8443,
  pathname: '/v2/resources',
  params: { limit: 50, offset: 100 },
});

console.log(uri.href);
// "https://api.example.com:8443/v2/resources?limit=50&offset=100"

Combining baseURL with pathname and params

const uri = rezo.buildUri({
  baseURL: 'https://api.example.com/v1',
  pathname: '/users',
  params: { role: 'admin', sort: '-created' },
});

console.log(uri.href);
// "https://api.example.com/v1/users?role=admin&sort=-created"

Auth encoding

Credentials in the auth option are percent-encoded into the URL’s userinfo section:

const uri = rezo.buildUri({
  url: 'https://registry.example.com/packages',
  auth: { username: 'deploy@ci', password: 'p@ss/word' },
});

console.log(uri.href);
// "https://deploy%40ci:p%40ss%2Fword@registry.example.com/packages"

Custom params serializer

const uri = rezo.buildUri({
  url: 'https://api.example.com/search',
  params: { tags: ['node', 'http', 'typescript'] },
  paramsSerializer: (params) =>
    Object.entries(params)
      .flatMap(([key, val]) =>
        Array.isArray(val) ? val.map(v => `${key}=${v}`) : [`${key}=${val}`]
      )
      .join('&'),
});

console.log(uri.href);
// "https://api.example.com/search?tags=node&tags=http&tags=typescript"