A powerful utility for parsing and stringifying URL query strings
npm install @nixat/query-stringA powerful utility for parsing and stringifying URL query strings with extensive options for customization.
``bashUsing npm
npm install @nixat/query-string
Features
- 🚀 Fast and lightweight - Zero dependencies, small bundle size
- 🔄 Flexible array formats - Multiple ways to handle arrays in query strings
- 🔧 Highly customizable - Extensive options for parsing and stringifying
- 🧠Smart parsing - Optionally parse numbers, booleans, and null values
- 🔒 Type-safe - Written in TypeScript with comprehensive type definitions
- 📚 Well documented - Clear examples and API documentation
- ✅ Well tested - Comprehensive test suite with high coverage
Usage
$3
`typescript
import { stringify, parse, parseUrl } from '@nixat/query-string';// Convert object to query string
stringify({ foo: 'bar', baz: ['qux', 'quux'] });
// => "foo=bar&baz=qux&baz[]=quux"
// Parse query string to object
parse('foo=bar&baz=qux&baz=quux');
// => { foo: 'bar', baz: ['qux', 'quux'] }
// Parse URL and extract query parameters
parseUrl('https://example.com/path?foo=bar&baz=qux');
// => { foo: 'bar', baz: 'qux' }
`$3
`typescript
// Default (repeat)
stringify({ foo: ['bar', 'baz'] });
// => "foo=bar&foo[]=baz"// Bracket format
stringify({ foo: ['bar', 'baz'] }, { arrayFormat: 'bracket' });
// => "foo[]=bar,baz"
// Index format
stringify({ foo: ['bar', 'baz'] }, { arrayFormat: 'index' });
// => "foo[0]=bar&foo[1]=baz"
// Comma format
stringify({ foo: ['bar', 'baz'] }, { arrayFormat: 'comma' });
// => "foo=bar,baz"
// Custom separator
stringify({ foo: ['bar', 'baz'] }, {
arrayFormat: 'separator',
arraySeparator: '|'
});
// => "foo=bar|baz"
`$3
`typescript
// Parse numbers
parse('foo=123&bar=45.67', { parseNumbers: true });
// => { foo: 123, bar: 45.67 }// Parse booleans
parse('foo=true&bar=false', { parseBooleans: true });
// => { foo: true, bar: false }
// Parse null values
parse('foo=&bar=value', { parseNull: true });
// => { foo: null, bar: 'value' }
`$3
`typescript
// Custom separators for stringify
stringify({ foo: 'bar', baz: 'qux' }, {
separator: ';',
keyValueSeparator: ':'
});
// => "foo:bar;baz:qux"// Custom separators for parse
parse('foo:bar;baz:qux', {
separator: ';',
keyValueSeparator: ':'
});
// => { foo: 'bar', baz: 'qux' }
`API
$3
Converts an object to a query string.
#### Options
-
separator - Character to use as a separator between key and value pairs (default: '&')
- keyValueSeparator - Character to use between key and value (default: '=')
- addQueryPrefix - Whether to include a question mark at the beginning of the query string (default: false)
- encode - Whether to encode keys and values (default: true)
- encoder - Custom encoding function to use instead of encodeURIComponent
- arrayFormat - How to handle arrays in the query string (default: 'repeat')
- 'bracket' - Uses bracket notation (e.g., foo[]=bar,baz)
- 'index' - Uses index notation (e.g., foo[0]=bar&foo[1]=baz)
- 'comma' - Uses comma as separator (e.g., foo=bar,baz)
- 'repeat' - Repeats the key (e.g., foo=bar&foo[]=baz)
- 'separator' - Uses a custom separator (e.g., foo=bar|baz)
- arraySeparator - Character to use as array value separator when arrayFormat is 'separator' (default: ',')
- skipNull - Whether to skip null and undefined values (default: true)
- skipEmptyString - Whether to skip empty strings (default: false)
- sort - Sort the keys of the query string (default: false)$3
Parses a query string into an object.
#### Options
-
separator - Character used as a separator between key and value pairs (default: '&')
- keyValueSeparator - Character used between key and value (default: '=')
- decode - Whether to decode keys and values (default: true)
- decoder - Custom decoding function to use instead of decodeURIComponent
- arrayFormat - How to parse arrays in the query string (default: 'repeat')
- arraySeparator - Character used as array value separator when arrayFormat is 'separator' (default: ',')
- parseNumbers - Whether to parse numbers (default: false)
- parseBooleans - Whether to parse booleans (default: false)
- parseNull - Whether to parse null values (default: false)
- ignoreQueryPrefix - Whether to ignore query prefix (default: true)$3
Extracts the query string from a URL.
$3
Parses a URL and returns the query parameters as an object. Takes the same options as
parse`.MIT