@nixat/query-string

A powerful utility for parsing and stringifying URL query strings with extensive options for customization.

Installation

``bash


Using npm

npm install @nixat/query-string

Using yarn

yarn add @nixat/query-string

Using pnpm

pnpm add @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`.

License

MIT