A TypeScript library that provides a powerful and flexible query string parsing and stringification solution, with support for nested objects, arrays, Maps, Sets, and custom transformations.
npm install use-qsA TypeScript library that provides a powerful and flexible query string parsing and stringification solution, with support for nested objects, arrays, Maps, Sets, and custom transformations.



- โ
Type-safe parsing and stringification of query strings
- ๐ Support for nested objects and arrays
- ๐ฆ Built-in Map and Set serialization
- ๐ฏ Custom value transformations
- ๐ Prefix filtering for namespaced parameters
- ๐จ Flexible case transformations (camelCase, snake_case, kebab-case)
- ๐งน Configurable value omission
- ๐ Handles special characters and edge cases
- ๐ญ Maintains data integrity in round trips
``bash`
yarn add use-qs
`typescript
import qs from 'use-qs';
// Parse query string
const parsed = qs.parse('?name=John&age=25');
// Result: { name: 'John', age: 25 }
// Stringify object
const stringified = qs.stringify({ name: 'John', age: 25 });
// Result: '?name=John&age=25'
`
`typescript
// Parsing nested structures
const parsed = qs.parse('?user.name=John&user.skills[0]=js&user.skills[1]=ts');
// Result: { user: { name: 'John', skills: ['js', 'ts'] } }
// Stringifying nested structures
const stringified = qs.stringify({
user: {
name: 'John',
skills: ['js', 'ts']
}
});
// Result: '?user.name=John&user.skills[0]=js&user.skills[1]=ts'
`
#### CamelCase
`typescript
const options = { case: 'camelCase' };
// Parsing to camelCase
const parsed = qs.parse('?first_name=John&last-name=Doe', options);
// Result: { firstName: 'John', lastName: 'Doe' }
// Stringifying from camelCase
const stringified = qs.stringify({ firstName: 'John', lastName: 'Doe' }, options);
// Result: '?firstName=John&lastName=Doe'
`
#### Snake Case
`typescript
const options = { case: 'snake_case' };
// Parsing snake_case
const parsed = qs.parse('?first-name=John&lastName=Doe', options);
// Result: { first_name: 'John', last_name: 'Doe' }
// Stringifying to snake_case
const stringified = qs.stringify({ firstName: 'John', lastName: 'Doe' }, options);
// Result: '?first_name=John&last_name=Doe'
`
#### Kebab Case
`typescript
const options = { case: 'kebab-case' };
// Parsing kebab-case
const parsed = qs.parse('?first_name=John&lastName=Doe', options);
// Result: { 'first-name': 'John', 'last-name': 'Doe' }
// Stringifying to kebab-case
const stringified = qs.stringify({ firstName: 'John', lastName: 'Doe' }, options);
// Result: '?first-name=John&last-name=Doe'
`
`typescript
// Parsing Map and Set
const parsed = qs.parse('?map=map([["key1","value1"]])&set=set(["value1","value2"])');
// Result: {
// map: new Map([['key1', 'value1']]),
// set: new Set(['value1', 'value2'])
// }
// Stringifying Map and Set
const stringified = qs.stringify({
map: new Map([['key1', 'value1']]),
set: new Set(['value1', 'value2'])
});
// Result: '?map=map([["key1","value1"]])&set=set(["value1","value2"])'
`
#### Prefix Option
`typescript
const options = { prefix: 'api-' };
// Parsing with prefix
const parsed = qs.parse('?api-name=John&api-age=25', options);
// Result: { name: 'John', age: 25 }
// Stringifying with prefix
const stringified = qs.stringify({ name: 'John', age: 25 }, options);
// Result: '?api-name=John&api-age=25'
`
#### Omit Values Option
`typescript
const options = {
omitValues: ['', null, undefined] // Array of values to omit
// OR
omitValues: (value, key) => value === '' // Function to determine omission
};
const stringified = qs.stringify({
name: 'John',
age: null,
email: ''
}, options);
// Result: '?name=John'
`
`typescript`
type QsOptions = {
addQueryPrefix?: boolean; // Add '?' prefix to stringified result
case?: 'camelCase' | 'snake_case' | 'kebab-case'; // Case transformation option
omitValues?: any[] | ((value: any, key: string) => boolean); // Values to omit
prefix?: string; // Prefix for keys
restoreCase?: 'camelCase' | 'snake_case' | 'kebab-case' | false; // Restore case when parsing
};
`bash``Run tests
yarn test
- The library automatically handles URL encoding/decoding
- Supports deep nesting of objects and arrays
- Maintains type safety with TypeScript
- Preserves data integrity in parse/stringify round trips
- Handles special characters and edge cases gracefully
- Supports flexible case transformations with restoration options
MIT ยฉ Felipe Rohde
Give a โญ๏ธ if this project helped you!
Felipe Rohde
- Twitter: @felipe_rohde
- Github: @feliperohdee
- Email: feliperohdee@gmail.com