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

yarn add use-qs

🛠️ Usage

Basic Usage

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'

Nested Objects and Arrays

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

Case Transformation Options

CamelCase

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

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

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'

Map and Set Support

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

Advanced Options

Prefix Option

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

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'

Configuration Options

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

# 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: [email protected]