API Reference - Khanh Docs

Type Definitions#

`ParamMap`#

The base type for parameter objects used throughout the API.

type ParamMap = Record<string, unknown>;

All parameter values are converted to strings during URL encoding. The following types are supported:

string - Used as-is (after URL encoding)
number - Converted to string
boolean - Converted to 'true' or 'false'
Array - Each element becomes a separate parameter with the same key
null / undefined - Filtered out and not included in the URL

Main Functions#

`createUrl()`#

The primary function for building URLs with multiple overloads for different use cases.

Signature 1: Base Template with Parameters#

Build a URL using only a template string with path parameters. Unused parameters become query parameters.

function createUrl(baseTemplate: string, params: ParamMap): string;

Parameters:

baseTemplate - A URL template containing zero or more :param placeholders
params - Object with properties that correspond to the :params in the template

Returns: A complete URL with path parameters substituted and unused parameters as query string

Example:

import { createUrl } from 'fast-url';const url = createUrl('http://api.example.com/users/:id', {  id: 42,  search: 'foo',  active: true,});console.log(url);// → 'http://api.example.com/users/42?search=foo&active=true'

Signature 2: Base URL with Path#

Concatenate a base URL and path using / as separator. Handles duplicate slashes automatically.

function createUrl(baseUrl: string, path: string): string;

Parameters:

baseUrl - The first part of the URL
path - The second part of the URL to append

Returns: Concatenated URL with exactly one / separator

Example:

import { createUrl } from 'fast-url';// Handles trailing/leading slashesconst url1 = createUrl('http://api.example.com/', '/users');console.log(url1);// → 'http://api.example.com/users'// Works without slashes tooconst url2 = createUrl('http://api.example.com', 'users');console.log(url2);// → 'http://api.example.com/users'

Signature 3: Complete URL Building#

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

function createUrl(  baseUrl: string,  pathTemplate: string,  params: ParamMap): string;

Parameters:

baseUrl - The base URL (protocol + domain)
pathTemplate - Path template with optional :param placeholders
params - Object with path and query parameters

Returns: Complete URL with substituted path parameters and query string

Example:

import { createUrl } from 'fast-url';const url = createUrl('http://api.example.com/', '/users/:id', {  id: 42,  search: 'foo',  limit: 10,  offset: 20,});console.log(url);// → 'http://api.example.com/users/42?search=foo&limit=10&offset=20'

Note

Path vs Query Parameters

Parameters that match :param placeholders in the path template are used for path substitution. All other parameters become query string parameters.

Utility Functions#

`query()`#

Build a query string from a parameter object.

function query(params: ParamMap): string;

Parameters:

params - Object to convert into a query string

Returns: URL-encoded query string (without leading ?)

Examples:

import { query } from 'fast-url';// Basic usageconst q1 = query({ name: 'John', age: 30 });console.log(q1);// → 'name=John&age=30'// Special characters are encodedconst q2 = query({  search: 'hello world',  filter: 'price>100',});console.log(q2);// → 'search=hello%20world&filter=price%3E100'// Arrays create repeated parametersconst q3 = query({  tags: ['javascript', 'typescript'],  limit: 10,});console.log(q3);// → 'tags=javascript&tags=typescript&limit=10'// Null and undefined are filtered outconst q4 = query({  name: 'John',  age: null,  city: undefined,  country: 'USA',});console.log(q4);// → 'name=John&country=USA'// Empty object returns empty stringconst q5 = query({});console.log(q5);// → ''

Use Cases:

Building query strings independently
Updating existing URLs with new parameters
Creating search or filter parameters

`subst()`#

Substitute path parameters in a template string without building a full URL.

function subst(template: string, params: ParamMap): string;

Parameters:

template - String containing :param placeholders
params - Object with keys matching the placeholders

Returns: Template with all :param placeholders replaced with URL-encoded values

Examples:

import { subst } from 'fast-url';// Basic substitutionconst path1 = subst('/users/:id/posts/:postId', {  id: 42,  postId: 123,});console.log(path1);// → '/users/42/posts/123'// Extra parameters are ignoredconst path2 = subst('/users/:id', {  id: 42,  limit: 10, // Ignored  sort: 'name', // Ignored});console.log(path2);// → '/users/42'// Special characters in values are encodedconst path3 = subst('/search/:query', {  query: 'hello world & goodbye',});console.log(path3);// → '/search/hello%20world%20%26%20goodbye'// Unicode is properly handledconst path4 = subst('/users/:name', {  name: '田中',});console.log(path4);// → '/users/%E7%94%B0%E4%B8%AD'

Errors:

import { subst } from 'fast-url';// Missing parameter throws errortry {  subst('/users/:id', {});} catch (error) {  console.error(error.message);  // → "Missing value for path parameter id."}// Invalid type throws errortry {  subst('/users/:id', { id: {} });} catch (error) {  console.error(error.message);  // → "Path parameter id cannot be of type object. Allowed types are: boolean, string, number."}// Empty string throws errortry {  subst('/users/:id', { id: '' });} catch (error) {  console.error(error.message);  // → "Path parameter id cannot be an empty string."}

Use Cases:

Building URL paths without query strings
Template rendering
Path parameter validation

`join()`#

Join two strings using a separator, ensuring exactly one occurrence at the boundary.

function join(part1: string, separator: string, part2: string): string;

Parameters:

part1 - First string
separator - Separator character(s)
part2 - Second string

Returns: Joined string with exactly one separator

Examples:

import { join } from 'fast-url';// URL path joiningconst url1 = join('http://api.example.com/', '/', '/users');console.log(url1);// → 'http://api.example.com/users'// Works with different separatorsconst url2 = join('http://api.example.com', '/', 'users');console.log(url2);// → 'http://api.example.com/users'// Query string joiningconst query1 = join('name=John', '&', '&age=30');console.log(query1);// → 'name=John&age=30'// Handles empty stringsconst url3 = join('', '/', 'users');console.log(url3);// → 'users'const url4 = join('http://api.example.com', '/', '');console.log(url4);// → 'http://api.example.com'// Multiple character separatorsconst text = join('Hello', ', ', ', World');console.log(text);// → 'Hello, World'

Use Cases:

Safe URL concatenation
Building paths from segments
Joining strings with any separator

Advanced Examples#

Building Complex API Clients#

import { createUrl, query } from 'fast-url';class GitHubAPI {  private baseUrl = 'https://api.github.com';  // List user repositories with filters  getUserRepos(    username: string,    options: {      type?: 'all' | 'owner' | 'member';      sort?: 'created' | 'updated' | 'pushed' | 'full_name';      direction?: 'asc' | 'desc';      per_page?: number;      page?: number;    } = {}  ) {    return createUrl(this.baseUrl, '/users/:username/repos', {      username,      ...options,    });  }  // Get a specific commit  getCommit(owner: string, repo: string, sha: string) {    return createUrl(this.baseUrl, '/repos/:owner/:repo/commits/:sha', {      owner,      repo,      sha,    });  }  // Search repositories  searchRepos(    q: string,    options: {      sort?: 'stars' | 'forks' | 'updated';      order?: 'asc' | 'desc';      per_page?: number;    } = {}  ) {    return createUrl(this.baseUrl, '/search/repositories', {      q,      ...options,    });  }}const github = new GitHubAPI();console.log(  github.getUserRepos('octocat', {    type: 'owner',    sort: 'updated',    per_page: 50,  }));// → https://api.github.com/users/octocat/repos?type=owner&sort=updated&per_page=50console.log(github.getCommit('facebook', 'react', 'abc123'));// → https://api.github.com/repos/facebook/react/commits/abc123console.log(  github.searchRepos('fast-url language:typescript', {    sort: 'stars',    order: 'desc',  }));// → https://api.github.com/search/repositories?q=fast-url%20language%3Atypescript&sort=stars&order=desc

Dynamic Route Building#

import { createUrl } from 'fast-url';// Route configurationconst routes = {  home: '/',  userProfile: '/users/:userId',  userPosts: '/users/:userId/posts',  post: '/posts/:postId',  search: '/search',};// Helper to build routesfunction route(name: keyof typeof routes, params: Record<string, any> = {}) {  return createUrl('https://myblog.com', routes[name], params);}console.log(route('home'));// → https://myblog.com/console.log(route('userProfile', { userId: 123 }));// → https://myblog.com/users/123console.log(route('userPosts', { userId: 123, page: 2 }));// → https://myblog.com/users/123/posts?page=2console.log(route('search', { q: 'typescript', tag: 'tutorial' }));// → https://myblog.com/search?q=typescript&tag=tutorial

Pagination Helper#

import { createUrl } from 'fast-url';function buildPaginatedUrl(  baseUrl: string,  path: string,  page: number,  pageSize: number,  filters: Record<string, any> = {}) {  return createUrl(baseUrl, path, {    ...filters,    page,    per_page: pageSize,    offset: (page - 1) * pageSize,  });}console.log(  buildPaginatedUrl('https://api.example.com', '/products', 3, 20, {    category: 'electronics',    sort: 'price',  }));// → https://api.example.com/products?category=electronics&sort=price&page=3&per_page=20&offset=40

Performance Notes#

fast-url is optimized for performance:

Query string encoding: Matches Node.js performance with optimized implementations
Direct constant access: Better V8 JIT optimization
Minimal allocations: Efficient memory usage
Zero dependencies: Only relies on fast-querystring

Check

Benchmarks

In performance benchmarks, fast-url achieves 5-20% better performance than the original urlcat implementation in many scenarios while maintaining full compatibility.

Browser and Node.js Compatibility#

fast-url works in all modern JavaScript environments:

✅ Node.js 14+
✅ Bun
✅ Deno
✅ Modern browsers (Chrome, Firefox, Safari, Edge)
✅ React Native
✅ Electron

Type Definitions#

ParamMap#

Main Functions#

createUrl()#

Signature 1: Base Template with Parameters#

Signature 2: Base URL with Path#

Signature 3: Complete URL Building#

Utility Functions#

query()#

subst()#

join()#

Advanced Examples#

Building Complex API Clients#

Dynamic Route Building#

Pagination Helper#

Performance Notes#

Browser and Node.js Compatibility#

`ParamMap`#

`createUrl()`#

`query()`#

`subst()`#

`join()`#