Introduction

fast-url is a lightweight, high-performance JavaScript/TypeScript library for building URLs safely and conveniently. It's a modern fork of urlcat with a strong focus on performance optimization and code simplicity.

Why This Fork Was Created

The original urlcat library is a solid foundation for URL building, but over time it has faced several challenges:

Problems with the Original Project

• 🐌 Performance bottlenecks: The original implementation wasn't optimized for high-throughput scenarios
• 📦 Outdated dependencies: Not regularly updated with the latest Node.js optimizations
• 🔧 Maintenance gaps: Infrequent updates and slower adoption of modern JavaScript features
• ⚡ Query string encoding: Used older, less efficient encoding methods

How fast-url Addresses These Issues

fast-url was created to solve these problems while maintaining compatibility:

1. Performance-first approach:

   • Optimized query string encoding matching Node.js performance
   • Reduced function call overhead
   • Direct constant access for better V8 JIT optimization
   • 5-20% faster than previous implementations in many scenarios

2. Regular maintenance:

   • Active development and quick bug fixes
   • Regular dependency updates
   • Modern TypeScript implementation

3. Simplified codebase:

   • Minimal dependencies (only fast-querystring)
   • Clean, maintainable code
   • Focus on core functionality

4. Production-ready:

   • Comprehensive test coverage
   • Battle-tested in real-world applications
   • Performance benchmarks with CodSpeed integration

Key Features

The Problem

Building URLs manually is error-prone and difficult to maintain:

// ❌ Error-prone manual approach
const url = `${baseUrl}/users/${id}/posts?limit=${limit}&offset=${offset}`;

await fetch(url);

Issues with manual URL building:

• 🔴 Double slashes when joining paths
• 🔴 Unescaped parameters breaking URLs
• 🔴 Complex string concatenation logic
• 🔴 No validation of parameter types
• 🔴 Difficult to maintain and read

The Solution

fast-url provides a clean, safe API for URL construction:

// ✅ Clean and safe with fast-url
import { createUrl } from 'fast-url';

const url = createUrl(baseUrl, '/users/:id/posts', { id, limit, offset });

await fetch(url);

Benefits:

• ✅ Automatic parameter escaping
• ✅ Proper URL segment joining
• ✅ Clean separation of path and query parameters
• ✅ Type checking for path parameters
• ✅ Easy to read and maintain

Visual Example

Here's a visual representation of how fast-url simplifies URL building:

When to Use fast-url

fast-url is ideal for:

• 🌐 REST API clients: Building dynamic API endpoints
• 🔗 URL generators: Creating shareable links with query parameters
• 📱 Single-page applications: Managing client-side routing and navigation
• 🛠️ Backend services: Constructing URLs for external API calls
• 📊 Analytics tracking: Building tracking URLs with parameters

Quick Example

Here's a real-world example showing how fast-url simplifies URL building:

import { createUrl } from 'fast-url';

class UserAPI {
  private baseUrl = 'https://api.example.com';
  
  getUserPosts(userId: number, page = 1, limit = 10) {
    return fetch(
      createUrl(this.baseUrl, '/users/:userId/posts', {
        userId,
        page,
        limit,
        sort: 'created_at'
      })
    );
  }
}

// Generated URL: 
// https://api.example.com/users/42/posts?page=1&limit=10&sort=created_at

class UserAPI {
  private baseUrl = 'https://api.example.com';
  
  getUserPosts(userId: number, page = 1, limit = 10) {
    // Remove trailing slash from baseUrl if present
    const base = this.baseUrl.endsWith('/') 
      ? this.baseUrl.slice(0, -1) 
      : this.baseUrl;
    
    // Build path with encoded userId
    const path = `/users/${encodeURIComponent(userId)}/posts`;
    
    // Build query string
    const params = new URLSearchParams({
      page: String(page),
      limit: String(limit),
      sort: 'created_at'
    });
    
    return fetch(`${base}${path}?${params.toString()}`);
  }
}

Next Steps