https://github.com/zakkudo/query-string
Make working with url query-strings enjoyable.
https://github.com/zakkudo/query-string
Last synced: 2 months ago
JSON representation
Make working with url query-strings enjoyable.
- Host: GitHub
- URL: https://github.com/zakkudo/query-string
- Owner: zakkudo
- License: bsd-3-clause
- Created: 2018-08-04T22:29:49.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2025-03-18T21:58:01.000Z (3 months ago)
- Last Synced: 2025-03-18T22:32:28.454Z (3 months ago)
- Language: JavaScript
- Homepage:
- Size: 105 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# @zakkudo/query-string
Make working with url query-strings enjoyable.
[](https://travis-ci.org/zakkudo/query-string)
[](https://coveralls.io/github/zakkudo/query-string?branch=master)
[](https://snyk.io/test/github/zakkudo/query-string)
[](https://nodejs.org/)
[](https://opensource.org/licenses/BSD-3-Clause)
## Why use this?
- Consistancy with simplicity
- The instance acts like a plain-old-object
- `JSON.stringify()` will serialize it to json like it was a normal object
- Casting to a string will format it to be directly usable in a query
Update the properties after initialization and the serialization will reflect the updates
- Complex params are automatically serialized and deserialized from json
## Install
```console
# Install using npm
npm install @zakkudo/query-string
```
``` console
# Install using yarn
yarn add @zakkudo/query-string
```
## Examples
### Initializing with an object
```javascript
import QueryString from '@zakkudo/query-string';
const query = new QueryString({
page: 3,
title: 'awesomeness',
complex: {'test': 'value'}
});
String(query) // '?page=3&title=awesomeness&complex=%7B%22test%22%3A%22value%22%7D&'
query.toString() // '?page=3&title=awesomeness&complex=%7B%22test%22%3A%22value%22%7D&'
const url = `http://example${query}` //Automatically serializes correctly
const url = `http://example${query}` //Automatically serializes correctly with changes
```
### Initializing with a URL and making changes dynamically
```javascript
import QueryString from '@zakkudo/query-string';
const query = new QueryString('http://example?page=3&title=awesomeness');
delete query.page;
String(query) // '?title=awesomeness'
query.toString() // '?title=awesomeness'
```
### Error handling
```javascript
import QueryString from '@zakkudo/query-string';
import QueryStringError from '@zakkudo/query-string/QueryStringError';
try {
const query = new QueryString('http://invalid.com/?first=1?second=2')
} catch(e) {
if (e instanceof QueryStringError) {
console.error(e.message); // Trying to add duplicate query param when already exists
} else {
throw e;
}
}
```
## API
### @zakkudo/query-string~QueryString ⏏
**Kind**: Exported class
#### new QueryString([data], [options])
**Throws**:
- [QueryStringError](#module_@zakkudo/query-string/QueryStringError..QueryStringError) On
issues parsing or serializing the configuration
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [data] | String \| Object \| QueryString | | Initial data. A url `String` will be parsed, and `Object`/`QueryString` instances will be copied. |
| [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/query-string/QueryStringError~QueryStringError ⇐ Error ⏏
Error class used by QueryString for raising errors
generated during parsing or serialization.
**Kind**: Exported class
**Extends**: Error
* [~QueryStringError](#module_@zakkudo/query-string/QueryStringError..QueryStringError) ⇐ Error
* [new QueryStringError(message, url)](#new_module_@zakkudo/query-string/QueryStringError..QueryStringError_new)
* [.url](#module_@zakkudo/query-string/QueryStringError..QueryStringError+url)
#### new QueryStringError(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 |
#### queryStringError.url
The related url fragment when the error was generated
**Kind**: instance property of [QueryStringError](#module_@zakkudo/query-string/QueryStringError..QueryStringError)