0
# querystringify
1

2
querystringify is a lightweight JavaScript library that provides a simple, JSON-compatible interface for parsing query strings into objects and converting objects back into query strings. It features built-in security protection against prototype pollution and graceful error handling for malformed input.
3

4
## Package Information
5

6
- **Package Name**: querystringify
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install querystringify`
10

11
## Core Imports
12

13
```javascript
14
var qs = require('querystringify');
15
```
16

17
For ES modules (if available):
18

19
```javascript
20
import { parse, stringify } from 'querystringify';
21
```
22

23
## Basic Usage
24

25
```javascript
26
var qs = require('querystringify');
27

28
// Parse query strings into objects
29
var result = qs.parse('?foo=bar&baz=qux');
30
// Result: { foo: 'bar', baz: 'qux' }
31

32
// Convert objects into query strings
33
var queryString = qs.stringify({ foo: 'bar', baz: 'qux' });
34
// Result: 'foo=bar&baz=qux'
35

36
// Add prefix to query string
37
var withPrefix = qs.stringify({ foo: 'bar' }, true);
38
// Result: '?foo=bar'
39
```
40

41
## Capabilities
42

43
### Query String Parsing
44

45
Parses query strings into JavaScript objects with automatic URL decoding and security protections.
46

47
```javascript { .api }
48
/**
49
 * Parse a query string into an object
50
 * @param {string} query - The query string to parse (can include ?, #, or no prefix)
51
 * @returns {object} Object with key-value pairs from the query string
52
 */
53
function parse(query);
54
```
55

56
**Features:**
57
- Handles query strings with or without `?` or `#` prefixes
58
- Parameters without values are set to empty strings
59
- Automatic URL decoding (including plus signs as spaces)
60
- Prevents prototype pollution by checking existing properties
61
- Graceful error handling - invalid encoded values are omitted
62
- First occurrence wins for duplicate keys
63

64
**Usage Examples:**
65

66
```javascript
67
var qs = require('querystringify');
68

69
// Basic parsing
70
qs.parse('foo=bar&baz=qux');
71
// { foo: 'bar', baz: 'qux' }
72

73
// Works with prefixes
74
qs.parse('?foo=bar&baz=qux');
75
// { foo: 'bar', baz: 'qux' }
76

77
qs.parse('#foo=bar&baz=qux');
78
// { foo: 'bar', baz: 'qux' }
79

80
// Parameters without values
81
qs.parse('foo&bar=baz');
82
// { foo: '', bar: 'baz' }
83

84
// URL decoding including plus signs
85
qs.parse('name=John+Doe&city=New%20York');
86
// { name: 'John Doe', city: 'New York' }
87

88
// Duplicate keys - first wins
89
qs.parse('foo=first&foo=second');
90
// { foo: 'first' }
91

92
// Malformed input is handled gracefully
93
qs.parse('?%&validkey=validvalue');
94
// { validkey: 'validvalue' }
95
```
96

97
### Query String Generation
98

99
Converts JavaScript objects into properly encoded query strings with optional prefix support.
100

101
```javascript { .api }
102
/**
103
 * Convert an object into a query string
104
 * @param {object} obj - Object to convert to query string
105
 * @param {string|boolean} [prefix] - Optional prefix. If true, uses '?'. If string, uses that string. Default: no prefix
106
 * @returns {string} Query string representation, or empty string if no valid pairs
107
 */
108
function stringify(obj, prefix);
109
```
110

111
**Features:**
112
- Automatic URL encoding of keys and values
113
- Handles null, undefined, and NaN values by converting to empty strings
114
- Optional prefix support (no prefix, `?`, or custom string)
115
- Empty objects return empty string regardless of prefix
116
- Graceful error handling - invalid encoding attempts are omitted
117
- Works with objects created with `Object.create(null)`
118

119
**Usage Examples:**
120

121
```javascript
122
var qs = require('querystringify');
123

124
// Basic stringification
125
qs.stringify({ foo: 'bar', baz: 'qux' });
126
// 'foo=bar&baz=qux'
127

128
// With question mark prefix
129
qs.stringify({ foo: 'bar', baz: 'qux' }, true);
130
// '?foo=bar&baz=qux'
131

132
// With custom prefix
133
qs.stringify({ foo: 'bar', baz: 'qux' }, '#');
134
// '#foo=bar&baz=qux'
135

136
// Empty values
137
qs.stringify({ foo: '' });
138
// 'foo='
139

140
// Null, undefined, NaN become empty strings
141
qs.stringify({ foo: null, bar: undefined, baz: NaN });
142
// 'foo=&bar=&baz='
143

144
// URL encoding
145
qs.stringify({ name: 'John Doe', city: 'New York' });
146
// 'name=John%20Doe&city=New%20York'
147

148
// Empty objects
149
qs.stringify({});
150
// ''
151
qs.stringify({}, true);
152
// ''
153

154
// Works with nulled objects
155
var obj = Object.create(null);
156
obj.foo = 'bar';
157
qs.stringify(obj);
158
// 'foo=bar'
159
```
160

161
## Error Handling
162

163
querystringify is designed to handle malformed input gracefully:
164

165
- **Invalid URL encoding**: Characters that cannot be decoded are omitted from results
166
- **Prototype pollution protection**: Built-in properties like `toString` and `__proto__` cannot be overridden
167
- **Encoding failures**: Keys or values that cannot be encoded are omitted from output
168
- **Edge cases**: Empty strings, null values, and undefined values are handled consistently
169

170
## Browser and Node.js Compatibility
171

172
querystringify works in both browser and Node.js environments without external dependencies. It uses standard JavaScript APIs (`encodeURIComponent`, `decodeURIComponent`) available in all modern environments.