https://github.com/gturi/url-builder
Utility to help building http urls for your API.
https://github.com/gturi/url-builder
rest-api typescript url
Last synced: 6 months ago
JSON representation
Utility to help building http urls for your API.
- Host: GitHub
- URL: https://github.com/gturi/url-builder
- Owner: gturi
- License: mit
- Created: 2020-11-14T09:45:51.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2023-03-06T23:59:32.000Z (over 3 years ago)
- Last Synced: 2025-09-05T08:54:28.260Z (10 months ago)
- Topics: rest-api, typescript, url
- Language: TypeScript
- Homepage: https://github.com/gturi/url-builder/blob/gh-pages/README.md
- Size: 900 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# UrlBuilder
| branch | build | coverage |
| --- | --- | --- |
| main | [](https://github.com/FlamingTuri/url-builder/actions/workflows/lint-and-test.yml) | [](https://coveralls.io/github/FlamingTuri/url-builder?branch=main) |
| develop | [](https://github.com/FlamingTuri/url-builder/actions/workflows/lint-and-test.yml) | [](https://coveralls.io/github/FlamingTuri/url-builder?branch=develop) |
Utility to help building http urls for your API.
## Installing
```bash
npm install http-url-builder
```
To install the latest version with security updates applied use `@dev` tag when installing:
```bash
npm install http-url-builder@dev
```
## Examples
Importing the library:
```js
// old CommonJS syntax
const UrlBuilder = require('http-url-builder').UrlBuilder;
// new ES6 syntax
import { UrlBuilder } from 'http-url-builder';
```
Basic setup:
```js
const url = UrlBuilder.create('localhost', 8080).build();
console.log(url);
// https://localhost:8080
```
Build an url:
```js
// 'false' uses 'http' instead of 'https'
const url = UrlBuilder.create('localhost', 8080/*, false*/)
.addPath('foo')
.addPathVariable('John Doe')
.addPath('bar')
.addQueryParam('baz', 'qux')
.addQueryParam('test', 123)
.build();
console.log(url);
// https://localhost:8080/foo/John Doe/bar?baz=qux&test=123
```
`addPath()` does not allow spaces in the url and automatically trims the path value to prevent errors.
`addPathVariable()` instead allows to insert spaces since query params do not need to follow the strict rules applied to paths. Moreover, `/` characters will be replaced with `%2F`.
```js
const url = UrlBuilder.create('localhost', 8080)
.addPath('example')
// 'true' will trim the path variable as it happens with .addPath()
.addPathVariable(' John/Doe '/*, true*/)
.addPath('operation')
.build();
console.log(url);
// https://localhost:8080/example/ John%2FDoe /operation
```
`addQueryParam()` accepts strings, numbers, booleans and objects. Objects will be converted to their JSON representation to create the url.
```js
const obj = {
foo: 'bar',
baz: 0,
qux: true,
};
const url = UrlBuilder.create('localhost', 8080)
.addPath('example')
.addQueryParam('myObj', obj)
.build();
console.log(url);
// https://localhost:8080/example?myObj={"foo":"bar","baz":0,"qux":true}
```
Each `addPath()`, `addPathVariable()` and `addQueryParam()` operation creates a new UrlBuilder instance.
Thanks to immutability, paths can not be accidentally modified:
```js
const base = UrlBuilder.create('localhost', 8080).addPath('base');
const fooUrl = base.addPath('foo');
const barUrl = base.addPath('bar');
console.log(base.build()); // https://localhost:8080/base
console.log(fooUrl.build()); // https://localhost:8080/base/foo
console.log(barUrl.build()); // https://localhost:8080/base/bar
```
If you already have an url, you can convert it to an UrlBuilder instance by using its constructor:
```js
const url = new UrlBuilder("https://localhost:8080/my/path");
```
## License
[MIT](LICENSE)