url-literal

A utility for building safe, readable URLs with template literals and query parameters.

installation

yarn add @jswork/url-literal

usage

import urlLiteral from '@jswork/url-literal';

// Basic path building
const url1 = urlLiteral`/api/users`;
url1.toString(); // '/api/users'

// Path with variables
const userId = 123;
const url2 = urlLiteral`/api/users/${userId}`;
url2.toString(); // '/api/users/123'

// Add query parameters
const url3 = urlLiteral`/api/users`.withQuery({ page: 1, limit: 10 });
url3.toString(); // '/api/users?page=1&limit=10'

// Combine variables and query parameters
const url4 = urlLiteral`/api/users/${userId}/posts`.withQuery({ page: 1 });
url4.toString(); // '/api/users/123/posts?page=1'

// Replace path parameters
const path = urlLiteral`/api/users/:id`.withParam({ id: 123 });
path.toString(); // '/api/users/123'

// Replace multiple path parameters
const path2 = urlLiteral`/api/users/:userId/posts/:postId`.withParam({ userId: 123, postId: 456 });
path2.toString(); // '/api/users/123/posts/456'

// Chain params and query (params first, then query)
const url5 = urlLiteral`/api/users/:id`.withParam({ id: 123 }).withQuery({ page: 1, limit: 10 });
url5.toString(); // '/api/users/123?page=1&limit=10'

// Chain query and params (query first, then params)
const url6 = urlLiteral`/api/users/:id`.withQuery({ page: 1 }).withParam({ id: 123 });
url6.toString(); // '/api/users/123?page=1'

// Ignore null/undefined values
const url7 = urlLiteral`/api/users`.withQuery({ page: 1, search: null });
url7.toString(); // '/api/users?page=1'

// Automatic string conversion (no need to call toString())
const url8 = urlLiteral`/api/users/:id`.withParam({ id: 123 }).withQuery({ page: 1 });
const message = `Fetching ${url8}`; // 'Fetching /api/users/123?page=1'
const fullUrl = 'GET ' + url8; // 'GET /api/users/123?page=1'
fetch(url8); // Automatically converts to string

// Works in template literals
const url9 = urlLiteral`/api/users/:id`.withParam({ id: 123 });
console.log(`${url9}`); // '/api/users/123'

// String() also works
const url10 = urlLiteral`/api/users`.withQuery({ page: 1 });
String(url10); // '/api/users?page=1'

// toString() explicitly returns the URL string
const url11 = urlLiteral`/api/users/:id`.withParam({ id: 123 }).withQuery({ page: 1 });
url11.toString(); // '/api/users/123?page=1'

// Replace path parameters and get string directly with param() (legacy)
const url12 = urlLiteral`/api/users/:id`.param({ id: 123 });
url12; // '/api/users/123' (returns plain string)

// Add query parameters and get string directly with query() (legacy)
const url13 = urlLiteral`/api/users`.query({ page: 1, limit: 10 });
url13; // '/api/users?page=1&limit=10' (returns plain string)

// Combine param() and query() for direct string output (legacy)
const url14 = urlLiteral`/api/users/:id`.param({ id: 123 }).query({ page: 1 });
url14; // '/api/users/123?page=1'

license

Code released under the MIT license.