fast-url

fast-url

A folk version of the urlcat focuses on performance and simplicity. Build correct URLs easily. A fast, minimal fork of urlcat focused on performance and simplicity.

fast-url is a tiny JavaScript/TypeScript library that makes building URLs convenient and prevents common mistakes.

Features

• Lightweight: Only one dependency (fast-querystring) and minimal bundle size
• Type safe: Written in TypeScript with full type definitions
• URL safe: Automatically escapes parameters and handles edge cases
• Unicode-aware: Uses codePointAt for proper Unicode handling, including graceful encoding of lone surrogates
• Flexible: Multiple ways to build URLs for different use cases

Installation

# Using JSR (recommended for Deno)
deno add jsr:@hckhanh/fast-url

# Using bun
bun add fast-url

# Using npm
npm install fast-url

Usage

Basic URL building

import { createUrl } from "fast-url";

// Path parameters
createUrl("https://api.example.com", "/users/:id", { id: 123 });
// → 'https://api.example.com/users/123'

// Query parameters
createUrl("https://api.example.com", "/users", { limit: 10, offset: 20 });
// → 'https://api.example.com/users?limit=10&offset=20'

// Combined path and query parameters
createUrl("https://api.example.com", "/users/:id/posts", { id: 123, limit: 10 });
// → 'https://api.example.com/users/123/posts?limit=10'

CommonJS

const { createUrl } = require("fast-url");

Utility functions

import { query, subst, join } from "fast-url";

// Build query strings
query({ name: "John", age: 30 });
// → 'name=John&age=30'

// Substitute path parameters
subst("/users/:id/posts/:postId", { id: 123, postId: 456 });
// → '/users/123/posts/456'

// Join URL parts
join("https://api.example.com/", "/", "/users");
// → 'https://api.example.com/users'

API

createUrl(baseUrl, pathTemplate, params?)

Build a complete URL by combining a base URL, path template, and parameters.

createUrl(baseTemplate, params)

Use a single template containing path parameters; unused params become query parameters.

query(params)

Build a query string from an object of key-value pairs.

subst(template, params)

Substitute path parameters in a template string.

join(part1, separator, part2)

Join two URL parts with exactly one separator.

Why fast-url?

Building URLs manually is error-prone:

// ❌ Error-prone manual approach
const url = `${baseUrl}/users/${id}/posts?limit=${limit}&offset=${offset}`;
// Issues: double slashes, unescaped parameters, complex concatenation

// ✅ Clean and safe with fast-url
const url = createUrl(baseUrl, "/users/:id/posts", { id, limit, offset });

fast-url handles:

• Automatic parameter escaping
• Proper URL segment joining
• Clean separation of path and query parameters

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT