0
# Query Parameter Management
1

2
Advanced query string manipulation with support for arrays, objects, and flexible parameter handling.
3

4
## Capabilities
5

6
### Query Parameter Manipulation
7

8
Methods for adding, setting, removing, and checking query parameters with support for complex data structures.
9

10
```javascript { .api }
11
/**
12
 * Set query parameters (replaces existing)
13
 * @param name - Parameter name or object of name-value pairs
14
 * @param value - Parameter value (ignored if name is object)
15
 * @param build - Whether to rebuild URI immediately
16
 * @returns URI instance for chaining
17
 */
18
setQuery(name: string | object, value?: string, build?: boolean): URI;
19
setSearch(name: string | object, value?: string, build?: boolean): URI; // Alias
20

21
/**
22
 * Add query parameters (preserves existing)
23
 * @param name - Parameter name or object of name-value pairs
24
 * @param value - Parameter value (ignored if name is object)
25
 * @param build - Whether to rebuild URI immediately
26
 * @returns URI instance for chaining
27
 */
28
addQuery(name: string | object, value?: string, build?: boolean): URI;
29
addSearch(name: string | object, value?: string, build?: boolean): URI; // Alias
30

31
/**
32
 * Remove query parameters
33
 * @param name - Parameter name or array of names to remove
34
 * @param value - Specific value to remove (removes all if not specified)
35
 * @param build - Whether to rebuild URI immediately
36
 * @returns URI instance for chaining
37
 */
38
removeQuery(name: string | string[], value?: string, build?: boolean): URI;
39
removeSearch(name: string | string[], value?: string, build?: boolean): URI; // Alias
40

41
/**
42
 * Check if query parameters exist
43
 * @param name - Parameter name to check
44
 * @param value - Specific value to check for
45
 * @param withinArray - Whether to check within array values
46
 * @returns Boolean indicating parameter existence
47
 */
48
hasQuery(name: string, value?: string, withinArray?: boolean): boolean;
49
hasSearch(name: string, value?: string, withinArray?: boolean): boolean; // Alias
50
```
51

52
**Usage Examples:**
53

54
```javascript
55
const uri = new URI('http://example.com/api');
56

57
// Set single parameter
58
uri.setQuery('page', '1');
59
console.log(uri.query()); // 'page=1'
60

61
// Set multiple parameters with object
62
uri.setQuery({
63
  page: 2,
64
  limit: 10,
65
  sort: 'name'
66
});
67
console.log(uri.query()); // 'page=2&limit=10&sort=name'
68

69
// Add parameters (preserves existing)
70
uri.addQuery('filter', 'active')
71
   .addQuery('tag', 'javascript')
72
   .addQuery('tag', 'web'); // Multiple values for same key
73

74
console.log(uri.query()); // 'page=2&limit=10&sort=name&filter=active&tag=javascript&tag=web'
75

76
// Check parameter existence  
77
console.log(uri.hasQuery('page')); // true
78
console.log(uri.hasQuery('tag', 'javascript')); // true
79
console.log(uri.hasQuery('missing')); // false
80

81
// Remove specific parameter value
82
uri.removeQuery('tag', 'web');
83
console.log(uri.hasQuery('tag', 'web')); // false
84
console.log(uri.hasQuery('tag', 'javascript')); // true
85

86
// Remove all values for parameter
87
uri.removeQuery('tag');
88
console.log(uri.hasQuery('tag')); // false
89
```
90

91
### Advanced Query Operations
92

93
Enhanced query manipulation supporting complex data structures and parsing options.
94

95
```javascript { .api }
96
/**
97
 * Enhanced query getter/setter with object support
98
 * @param value - Query string, object, or function to transform query
99
 * @param build - Whether to rebuild URI immediately
100
 * @returns Current query string/object or URI instance for chaining
101
 */
102
query(value?: string | object | function, build?: boolean): string | object | URI;
103
```
104

105
**Usage Examples:**
106

107
```javascript
108
const uri = new URI('http://example.com/api?page=1&tags=js&tags=web');
109

110
// Get query as object
111
const queryObj = uri.query(true); // true means return as object
112
console.log(queryObj);
113
// { page: '1', tags: ['js', 'web'] }
114

115
// Set query from object
116
uri.query({
117
  search: 'javascript',
118
  category: 'programming',
119
  active: true
120
});
121
console.log(uri.query()); // 'search=javascript&category=programming&active=true'
122

123
// Transform query with function
124
uri.query(function(data) {
125
  data.timestamp = Date.now();
126
  delete data.active;
127
  return data;
128
});
129

130
// Complex nested structures
131
uri.setQuery({
132
  filters: {
133
    status: 'active',
134
    type: ['article', 'tutorial']
135
  },
136
  meta: {
137
    version: '1.0',
138
    format: 'json'
139
  }
140
});
141
```
142

143
### Static Query Utilities
144

145
Static methods for working with query data objects directly.
146

147
```javascript { .api }
148
/**
149
 * Add query parameters to a data object
150
 * @param data - Existing query data object
151
 * @param name - Parameter name to add
152
 * @param value - Parameter value to add
153
 * @returns Modified data object
154
 */
155
URI.addQuery(data: object, name: string, value: string): object;
156

157
/**
158
 * Set query parameters in a data object
159
 * @param data - Existing query data object
160
 * @param name - Parameter name to set
161
 * @param value - Parameter value to set
162
 * @returns Modified data object
163
 */
164
URI.setQuery(data: object, name: string, value: string): object;
165

166
/**
167
 * Remove query parameters from a data object
168
 * @param data - Existing query data object
169
 * @param name - Parameter name to remove
170
 * @param value - Specific value to remove (optional)
171
 * @returns Modified data object
172
 */
173
URI.removeQuery(data: object, name: string, value?: string): object;
174

175
/**
176
 * Check if query parameters exist in a data object
177
 * @param data - Query data object to check
178
 * @param name - Parameter name to check
179
 * @param value - Specific value to check for (optional)
180
 * @param withinArray - Whether to check within array values
181
 * @returns Boolean indicating parameter existence
182
 */
183
URI.hasQuery(data: object, name: string, value?: string, withinArray?: boolean): boolean;
184
```
185

186
**Usage Examples:**
187

188
```javascript
189
// Work with query data objects directly
190
let queryData = { page: '1', sort: 'name' };
191

192
// Add parameters
193
URI.addQuery(queryData, 'filter', 'active');
194
URI.addQuery(queryData, 'tag', 'javascript');
195
URI.addQuery(queryData, 'tag', 'web');
196
console.log(queryData);
197
// { page: '1', sort: 'name', filter: 'active', tag: ['javascript', 'web'] }
198

199
// Check existence
200
console.log(URI.hasQuery(queryData, 'tag', 'javascript')); // true
201
console.log(URI.hasQuery(queryData, 'tag')); // true
202
console.log(URI.hasQuery(queryData, 'missing')); // false
203

204
// Remove specific value
205
URI.removeQuery(queryData, 'tag', 'web');
206
console.log(queryData.tag); // ['javascript']
207

208
// Remove entire parameter
209
URI.removeQuery(queryData, 'tag');
210
console.log(queryData.hasOwnProperty('tag')); // false
211
```
212

213
### Query String Encoding/Decoding
214

215
Methods for handling query string encoding with configurable space handling.
216

217
```javascript { .api }
218
/**
219
 * Encode query string with proper escaping
220
 * @param string - String to encode
221
 * @param escapeQuerySpace - Whether to encode spaces as + instead of %20
222
 * @returns Encoded string
223
 */
224
URI.encodeQuery(string: string, escapeQuerySpace?: boolean): string;
225

226
/**
227
 * Decode query string
228
 * @param string - String to decode
229
 * @param escapeQuerySpace - Whether to decode + as space
230
 * @returns Decoded string
231
 */
232
URI.decodeQuery(string: string, escapeQuerySpace?: boolean): string;
233
```
234

235
**Usage Examples:**
236

237
```javascript
238
// Encode query values
239
const encoded = URI.encodeQuery('hello world & more');
240
console.log(encoded); // 'hello+world+%26+more' (with escapeQuerySpace: true)
241

242
const encodedPct = URI.encodeQuery('hello world & more', false);
243
console.log(encodedPct); // 'hello%20world%20%26%20more'
244

245
// Decode query values
246
const decoded = URI.decodeQuery('hello+world+%26+more');
247
console.log(decoded); // 'hello world & more'
248

249
// Use in URI construction
250
const uri = new URI('http://example.com/search');
251
uri.setQuery('q', 'javascript & web development');
252
console.log(uri.toString()); // 'http://example.com/search?q=javascript+%26+web+development'
253
```
254

255
### Array Parameter Handling
256

257
Special handling for array-like query parameters and multiple values.
258

259
**Usage Examples:**
260

261
```javascript
262
const uri = new URI('http://example.com/api');
263

264
// Add multiple values for same parameter
265
uri.addQuery('category', 'web')
266
   .addQuery('category', 'mobile')
267
   .addQuery('category', 'desktop');
268

269
console.log(uri.query()); // 'category=web&category=mobile&category=desktop'
270

271
// Get as object shows arrays
272
const queryObj = uri.query(true);
273
console.log(queryObj.category); // ['web', 'mobile', 'desktop']
274

275
// Set array directly
276
uri.setQuery('tags', ['javascript', 'react', 'node']);
277
console.log(uri.query()); // 'tags=javascript&tags=react&tags=node'
278

279
// Check array values
280
console.log(uri.hasQuery('tags', 'react')); // true
281
console.log(uri.hasQuery('tags', 'vue')); // false
282

283
// Remove from array
284
uri.removeQuery('tags', 'node');
285
const remaining = uri.query(true);
286
console.log(remaining.tags); // ['javascript', 'react']
287

288
// Configure duplicate parameter behavior
289
uri.duplicateQueryParameters(false); // Disable duplicates
290
uri.setQuery('tags', ['a', 'b', 'c']);
291
// Will use a different serialization format depending on configuration
292
```