https://github.com/zakkudo/url
Make working with urls enjoyable.
https://github.com/zakkudo/url
Last synced: 2 months ago
JSON representation
Make working with urls enjoyable.
- Host: GitHub
- URL: https://github.com/zakkudo/url
- Owner: zakkudo
- License: bsd-3-clause
- Created: 2018-08-04T22:30:50.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2019-01-30T05:37:06.000Z (over 6 years ago)
- Last Synced: 2025-03-12T03:48:44.253Z (3 months ago)
- Language: JavaScript
- Homepage:
- Size: 109 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# @zakkudo/url
Make working with urls enjoyable.
[](https://travis-ci.org/zakkudo/url)
[](https://coveralls.io/github/zakkudo/url?branch=master)
[](https://snyk.io/test/github/zakkudo/url)
[](https://nodejs.org/)
[](https://opensource.org/licenses/BSD-3-Clause)
## Why use this?
- Params are accepted as a separate object
- You can update the params on the fly before the string is serialized
- Supports interpolation of fragments of the url with the params
- Supports dynamic json stringification of complex options like `@zakkudo/query-string`
## Install
```console
# Install using npm
npm install @zakkudo/url
```
``` console
# Install using yarn
yarn add @zakkudo/url
```
## Examples
### Generate URL with interpolation
``` javascript
import Url from '@zakkudo/url';
const url = new Url('http://backend/v1/users/:id/detail', {
page: 3,
id: '1234'
});
String(url); // 'http://backend/v1/users/1234/detail?page=3'
url.toString(); // 'http://backend/v1/users/1234/detail?page=3'
//Update the params after the fact
url.param.id = '5678';
String(url); // 'http://backend/v1/users/5678/detail?page=3'
//Update the url base after the fact
url.base = 'http://frontend/v1/users/:id/detail';
String(url); // 'http://frontend/v1/users/5678/detail?page=3'
```
### Generate object using raw url
``` javascript
import Url from '@zakkudo/url';
const url = new Url('http://backend/v1/users?limit=20');
JSON.stringify(url); // {"base": "http://backend/v1/users", "params": {"limit": 20}}
```
### Error handling
``` javascript
import Url from '@zakkudo/url';
import UrlError from @zakkudo/url/UrlError;
const url = new Url('http://backend/v1/users/:userId', {});
try {
String(url)
} catch (e) {
if (e instanceof UrlError) {
console.error(e.message); // `No replacement exists for userId in the params`
}
throw e;
}
```
## API
### @zakkudo/url~Url ⏏
**Kind**: Exported class
#### new Url(url, [params], [options])
**Throws**:
- [UrlError](#module_@zakkudo/url/UrlError..UrlError) On issues during serialization or construction of the url
- [QueryStringError](#module_@zakkudo/url/QueryStringError..QueryStringError) On issues
during serialization or construction of the query string
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| url | String | | The url pattern |
| [params] | Object | | Params to interpolate or append to the url as a query string when serialized. |
| [options] | Object | | Modifiers for how the query string object is contructed |
| [options.unsafe] | Boolean | false | Disable url escaping of key/value pairs. Useful for servers that use unsafe characters as delimiters |
### @zakkudo/url/UrlError~UrlError ⇐ Error ⏏
Error class used by Url for raising errors generated
for invalid errors.
**Kind**: Exported class
**Extends**: Error
* [~UrlError](#module_@zakkudo/url/UrlError..UrlError) ⇐ Error
* [new UrlError(message, url)](#new_module_@zakkudo/url/UrlError..UrlError_new)
* [.url](#module_@zakkudo/url/UrlError..UrlError+url)
#### new UrlError(message, url)
| Param | Type | Description |
| --- | --- | --- |
| message | String | A message describing the reason for the error. |
| url | String | The related url fragment when the error was generated |
#### urlError.url
The related url fragment when the error was generated
**Kind**: instance property of [UrlError](#module_@zakkudo/url/UrlError..UrlError)
### @zakkudo/url/QueryStringError~QueryStringError ⏏
Aliased error from package `@zakkudo/query-string/QueryStringError`
**Kind**: Exported class