Effortlessly generate and manage type-safe URLs for your web applications.
merl is a lightweight utility that simplifies URL generation and ensures type safety in your JavaScript/TypeScript applications. Define your URL patterns once, and let merl handle dynamic segments and query parameters, reducing errors and improving code clarity.
- 🛠 Type-Safe URL Generation: Compile-time safety for dynamic and query parameters.
- 🚀 Simple API: Easy-to-use chaining for building nested routes.
- ⚡ Lightweight and Fast: Minimal overhead for modern web applications.
- 🔒 Error Prevention: Guards against invalid routes or missing parameters.
Install merl via npm or yarn:
npm install merlor
yarn add merlimport merl from 'merl';
// Declare all your routes
const urls = [
'products/:productId/reviews/:reviewId',
'categories/:categoryId/items',
'/about',
'/search',
] as const;
// Compile URL patterns
const pathBuilder = merl.compile(urls);// Example: Product Review URL
const productReviewUrl = pathBuilder.products
.using('42') // Replace :productId with '42'
.reviews.using('7') // Replace :reviewId with '7'
.url();
console.log(productReviewUrl); // Output: /products/42/reviews/7const categoryItemsUrl = pathBuilder.categories
.using('electronics') // Replace :categoryId with 'electronics'
.items.url({ sort: 'asc', page: 2 });
console.log(categoryItemsUrl); // Output: /categories/electronics/items?sort=asc&page=2const aboutUrl = pathBuilder.about.url();
console.log(aboutUrl); // Output: /about
const searchUrl = pathBuilder.search.url({ q: 'laptops' });
console.log(searchUrl); // Output: /search?q=laptopsChain .using() calls to handle deeply nested routes.
const nestedUrl = pathBuilder.products
.using('99')
.reviews.using('12')
.url({ highlight: true });
console.log(nestedUrl); // Output: /products/99/reviews/12?highlight=truemerl prevents incorrect usage at compile-time in TypeScript.
// TypeScript error: Missing :productId
// const invalidUrl = pathBuilder.products.url();
// Correct usage:
const validUrl = pathBuilder.products.using('10').reviews.using('5').url();
console.log(validUrl); // Output: /products/10/reviews/5Compiles a list of URL patterns into a type-safe pathBuilder object.
routes: An array of URL strings (e.g.,'path/:dynamicSegment').
Use .using(value) to replace dynamic segments (e.g., :productId).
Add query parameters with .url(query):
query: An object where keys are parameter names and values are strings or numbers.
- 🚦 Eliminates Runtime Errors: Type-checking ensures your URLs are always valid.
- 📚 Readable Code: Focus on route logic instead of manual string concatenation.
- 🧹 Maintainability: Centralize your route definitions in a single place.
This project is licensed under the MIT License. See the LICENSE file for details.