use-qs

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.


🚀 Features

- ✅ 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

📦 Installation

``bash
yarn add use-qs
`

🛠️ Usage

$3

`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'
`

$3

`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'
`

$3

#### 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'
`

$3

`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"])'
`

$3

#### 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'
`

$3

`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
};
`

🧪 Testing

`bash


Run tests


yarn test
``

📝 Notes

- 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

📝 License

MIT © Felipe Rohde

⭐ Show your support

Give a ⭐️ if this project helped you!

👨‍💻 Author

Felipe Rohde

- Twitter: @felipe_rohde
- Github: @feliperohdee
- Email: feliperohdee@gmail.com