https://github.com/ootidea/type-safe-url
A lightweight TypeScript library for writing URLs in a type-safe manner.
https://github.com/ootidea/type-safe-url
library npm-package typescript
Last synced: 7 months ago
JSON representation
A lightweight TypeScript library for writing URLs in a type-safe manner.
- Host: GitHub
- URL: https://github.com/ootidea/type-safe-url
- Owner: ootidea
- License: cc0-1.0
- Created: 2023-09-23T10:45:31.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2023-10-05T05:12:30.000Z (over 2 years ago)
- Last Synced: 2024-06-06T14:34:17.151Z (about 2 years ago)
- Topics: library, npm-package, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/type-safe-url
- Size: 125 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
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.
```ts
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:
```ts
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:
```ts
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.
```ts
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.
```ts
const root = createRootPathObject<{
articles: {
'?': { tags: string[] } // 👈️ Multi-value as an array
}
}>()
console.log(
urlOf(root.articles, { tags: ['css', 'html'] }), // '/articles?tags=css&tags=html'
)
```