1 | # build-url-ts ( Typescript )
|
2 | [![Build Status](https://github.com/meabed/build-url-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/meabed/build-url-ts/actions/workflows/ci.yml)
|
3 | [![NPM version](https://img.shields.io/npm/v/build-url-ts.svg)](https://www.npmjs.com/package/build-url-ts)
|
4 | [![Downloads](https://img.shields.io/npm/dm/build-url-ts.svg)](https://www.npmjs.com/package/build-url-ts)
|
5 | [![UNPKG](https://img.shields.io/badge/UNPKG-OK-179BD7.svg)](https://unpkg.com/browse/build-url-ts@latest/)
|
6 |
|
7 | A library that builds a URL, including its path, query parameters and fragment identifier. Works in node and in the browser.
|
8 |
|
9 | > This is a fork from https://github.com/steverydz/build-url to add typescript support for the library
|
10 |
|
11 | [![Edit build-url-ts-demo](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/build-url-ts-demo-qer8y?fontsize=14&hidenavigation=1&theme=dark)
|
12 |
|
13 | ## Installation
|
14 |
|
15 | To install with npm:
|
16 |
|
17 | ```javascript
|
18 | npm install build-url-ts --save
|
19 | ```
|
20 |
|
21 | ## Usage
|
22 |
|
23 | ```javascript
|
24 | import { buildUrl } from 'build-url-ts';
|
25 |
|
26 | buildUrl('http://example.com', {
|
27 | path: 'about',
|
28 | hash: 'contact',
|
29 | queryParams: {
|
30 | foo: bar,
|
31 | bar: ['foo', 'bar']
|
32 | }
|
33 | });
|
34 | ```
|
35 |
|
36 | ## Options
|
37 |
|
38 | The `buildUrl` function accepts two arguments. The first is a URL e.g. `http://example.com`. The second is an object where you can specify the `path`, `hash`, `lowerCase`, and an object of `queryParams`:
|
39 |
|
40 | ```javascript
|
41 | index('http://example.com', {
|
42 | path: 'about',
|
43 | hash: 'contact',
|
44 | queryParams: {
|
45 | foo: 'bar',
|
46 | bar: 'baz'
|
47 | }
|
48 | });
|
49 |
|
50 | // returns http://example.com/about?foo=bar&bar=baz#contact
|
51 | ```
|
52 |
|
53 | If you pass an array to the `queryParams` object, it will be transformed to a comma separated list:
|
54 |
|
55 | ```javascript
|
56 | index('http://example.com', {
|
57 | queryParams: {
|
58 | foo: 'bar',
|
59 | bar: ['one', 'two', 'three']
|
60 | }
|
61 | });
|
62 |
|
63 | // returns http://example.com?foo=bar&bar=one,two,three
|
64 | ```
|
65 |
|
66 | If you want to change the `path`, `hash` and `queryParams` case to all lowercase then pass `lowerCase` as true in arguments, default value of this will be `false`:
|
67 |
|
68 | ```javascript
|
69 | index('http://example.com', {
|
70 | path: 'AbouT',
|
71 | hash: 'ConTacT',
|
72 | lowerCase: true,
|
73 | queryParams: {
|
74 | foo: 'bAr',
|
75 | bar: ['oNe', 'TWO', 'thrEE', 123]
|
76 | }
|
77 | });
|
78 |
|
79 | // returns http://example.com/about?foo=bar&bar=one,two,three,123#contact
|
80 | ```
|
81 |
|
82 | If you pass an array to the `queryParams` object, and want that they should not be comma separated use `disableCSV`:
|
83 |
|
84 | ```javascript
|
85 | index('http://example.com', {
|
86 | disableCSV: true,
|
87 | queryParams: {
|
88 | foo: 'bar',
|
89 | bar: ['one', 'two', 'three']
|
90 | }
|
91 | });
|
92 |
|
93 | // returns http://example.com?foo=bar&bar=one&bar=two&bar=three
|
94 | ```
|
95 |
|
96 | if you need the array as an array in the query string, you can pass `disableCSV` as one of this values `'array' | 'order_asc' | 'order_desc'`:
|
97 | ```javascript
|
98 | index('http://example.com', {
|
99 | disableCSV: 'array',
|
100 | queryParams: {
|
101 | foo: 'bar',
|
102 | bar: ['one', 'two', 'three']
|
103 | }
|
104 | });
|
105 |
|
106 | // returns http://example.com?foo=bar&bar[]=one&bar[]=two&bar[]=three
|
107 | ```
|
108 |
|
109 | If you only want the query string, path, hash, or any combination of the three you can skip the URL parameter or pass in an empty string or null:
|
110 |
|
111 | ```javascript
|
112 | index('', {
|
113 | queryParams: {
|
114 | foo: 'bar',
|
115 | bar: 'baz'
|
116 | }
|
117 | });
|
118 |
|
119 | // returns ?foo=bar&bar=baz
|
120 |
|
121 | index(null, {
|
122 | queryParams: {
|
123 | foo: 'bar',
|
124 | bar: 'baz'
|
125 | }
|
126 | });
|
127 |
|
128 | // returns ?foo=bar&bar=baz
|
129 |
|
130 | index({
|
131 | queryParams: {
|
132 | foo: 'bar',
|
133 | bar: 'baz'
|
134 | }
|
135 | });
|
136 | ```
|
137 |
|
138 | Any null values in the `queryParams` object will be treated as empty strings:
|
139 |
|
140 | ```javascript
|
141 | index('http://example.com', {
|
142 | queryParams: {
|
143 | foo: 'bar',
|
144 | bar: null
|
145 | }
|
146 | });
|
147 |
|
148 | // returns http://example.com?foo=bar&bar=
|
149 | ```
|
150 |
|
151 | ## License
|
152 |
|
153 | This is licensed under an MIT License. [See details](LICENSE)
|