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:

RezoUri

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

Properties

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()

Returns the URL as a string (this.href). Allows RezoUri instances to be serialized with JSON.stringify() — the result is the href string, not the object form. Use toObject() if you need the full breakdown of components.

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"

RezoUri (standalone)

RezoUri is the class buildUri() returns. You can import it directly and use it anywhere a URL works — it’s a subclass of the native URL, so instanceof URL is true and it serializes via toString() / href like any other URL.

import { RezoUri } from 'rezo';

const uri = new RezoUri('https://api.example.com/v1/users?role=admin');

// Standard URL surface
uri.protocol; // 'https:'
uri.pathname; // '/v1/users'

// RezoUri additions
uri.params;            // { role: 'admin' } — query as a plain object
uri.params = { role: 'editor', active: 'true' };  // replaces all params
uri.toObject();        // every URL component as a plain object, including auth
const copy = uri.clone();  // detached copy you can mutate

// Pass it directly to any HTTP method
await rezo.get(uri);

Use it when you want to compose a URL once and pass it around as a value, or when you want the params getter / setter rather than driving searchParams by hand.

parseLinkHeader

parseLinkHeader(header) turns an HTTP Link header into a { rel: url } map. It’s what powers rezo.paginate() auto-detection internally, but it’s also exported directly:

import { parseLinkHeader } from 'rezo';

const response = await rezo.get('https://api.github.com/users/octocat/repos');
const links = parseLinkHeader(response.headers.get('link'));

// {
//   next:  'https://api.github.com/user/.../repos?page=2',
//   last:  'https://api.github.com/user/.../repos?page=4',
//   first: 'https://api.github.com/user/.../repos?page=1'
// }

if (links.next) {
  const more = await rezo.get(links.next);
}

Returns {} for missing or empty headers — safe to call unconditionally.