README.md

type-safe-url

A lightweight TypeScript library for writing URLs in a type-safe manner.

Features

• Supports path parameters and query parameters
• Automatic URL encoding
• Works on both browsers and Node.js
• Tiny bundle size and 0 dependencies

With an IDE, you can list URL references and rename URL components 👍.

Basic example

Here is an example of how to define a URL structure and write corresponding URLs.

import { createRootPathObject, urlOf } from 'type-safe-url'

// Define your URL structure
const root = createRootPathObject<{
  company: {    // '/company'
    access: {}  // '/company/access'
    history: {} // '/company/history'
  }
}>()

// Create URL strings
console.log(
  urlOf(root),                // '/'
  urlOf(root.company.access), // '/company/access'
)

Path parameters

Path parameters are represented using function types as follows:

const root = createRootPathObject<{
  user: (name: string) => {   // 👈️ Path parameter
    profile: {}
    posts: (id: number) => {} // 👈️ Nested path parameter
  }
}>()

console.log(
  urlOf(root.user),                  // '/user'
  urlOf(root.user('alice')),         // '/user/alice'
  urlOf(root.user('alice').posts),   // '/user/alice/posts'
  urlOf(root.user('alice').posts(1)) // '/user/alice/posts/1'
)

Query parameters

Query parameters are represented as follows:

const root = createRootPathObject<{
  items: {
    '?': { page: number; limit: number }
  }
}>()

console.log(
  urlOf(root.items),                         // '/items'
  urlOf(root.items, { page: 2 }),            // '/items?page=2'
  urlOf(root.items, { page: 2, limit: 30 }), // '/items?page=2&limit=30'
)

Options for creating URL strings

You can configure the base URL and slashes at both ends.

const root = createRootPathObject<{
  about: {}
}>({
  baseUrl: 'https://example.com/',
  autoAddLeadingSlash: false,
  autoAddTrailingSlash: true,
})

console.log(urlOf(root.about)) // 'https://example.com/about/'

Multi-Value Query Parameters

You can define query parameters that accept multiple values.
Simply use array types as below.

const root = createRootPathObject<{
  articles: {
    '?': { tags: string[] } // 👈️ Multi-value as an array
  }
}>()

console.log(
  urlOf(root.articles, { tags: ['css', 'html'] }), // '/articles?tags=css&tags=html'
)