Request URI

A lightweight URI builder that works everywhere - Node.js, browsers, Fastify, Express, Fetch. Build URLs.

npm install ts-request-uri

The Problem

You're building a URL across environments. You're tired of:

• Manual string concatenation
• Detecting whether you're in Node or a browser
• Re-parsing the same request context over and over
• Brittle URL logic scattered throughout your code

This fixes it.

Quick Start

Browser

const uri = Uri.from("/api/users");
console.log(uri.href); // https://example.com/api/users

Node.js + Fastify

fastify.addHook("onRequest", (req, res, done) => {
  Uri.setRequest(req);
  done();
});

fastify.get("/welcome", (req, res) => {
  const url = Uri.from("/api/data");
  res.send(url.href); // Auto-detects base from request
});

Node.js + Express

app.use((req, res, next) => {
  Uri.setRequest(req);
  next();
});

app.get("/welcome", (req, res) => {
  const url = Uri.from("/api/data");
  res.send(url.href);
});

How It Works

Uri automatically detects your base URL from:

• Browser: window.location.origin
• Fastify/Express requests: Extracts protocol, host, port
• Fetch Request objects
• Plain objects: { protocol, host, port }
• Fallback: A URL you define

Set once, use anywhere:

// Global fallback (for when base can't be detected)
Uri.fallback = "https://api.example.com";

// Per-request override
const uri = Uri.from("/users", customRequest);

Building URLs

// Set path
Uri.from("/old").setPath("/new");

// Add query params
Uri.from("/search")
  .setQuery({ q: "term", limit: 10 });

// Modify parts
Uri.from("/api")
  .setHost("api.example.com")
  .setPort(8080)
  .setProtocol("https");

// Access the final URL
uri.href; // "https://api.example.com:8080/api?q=term&limit=10"

API Reference

| Method | Input | Purpose | |--------|-------|---------| | Uri.from(path, request?) | string, Request? | Create a new Uri | | Uri.setRequest(req) | Request | Set global request context | | Uri.fallback | string | Fallback base URL | | .setPath(path) | string | string[] | Replace the pathname | | .setQuery(key, val) | string, any | Add one query param | | .setQuery(obj) | object | Add multiple query params | | .setHost(host) | string | Replace host | | .setPort(port) | string | number | Replace port | | .setProtocol(protocol) | string | Replace protocol | | .href | — | Get the complete URL string |

Real Examples

API Client Builder

const apiBase = Uri.from("/api/v1");

const getUser = (id: string) => 
  apiBase.setPath(`/users/${id}`).href;

const searchUsers = (query: string, page: number) =>
  apiBase
    .setPath("/users")
    .setQuery({ q: query, page })
    .href;

URL Redirects

fastify.get("/legacy", (req, res) => {
  const newUrl = Uri.from("/new-path", req)
    .setQuery({ migrated: "true" });
  
  res.redirect(newUrl.href);
});

Multi-Environment Config

// Same code, different results based on environment
const analyticsUrl = Uri.from("/track")
  .setQuery({ 
    sessionId: req.sessionId,
    timestamp: Date.now()
  });

// Browser: https://example.com/track?sessionId=...&timestamp=...
// Server: https://api.internal.com/track?sessionId=...&timestamp=...

Error Handling

Uri throws Invalid URL when it can't determine a base. Set a fallback:

Uri.fallback = "https://localhost:3000";

Or pass the request explicitly:

const uri = Uri.from("/path", myRequest);

Testing

npm test

Fully tested across:

• All environment types (browser, Node, Fetch)
• Method chaining
• Edge cases (missing host, malformed URLs)
• Fallback behavior

Why This?

You could write URL logic yourself, but why? This package:

• Works in every JavaScript environment
• Eliminates string concatenation bugs
• Handles request detection automatically
• Stays out of the way