@nixat/query-string

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

Installation

# 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

Basic Usage

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

Array Formats

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

Smart Parsing

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

Custom Separators

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

stringify(obj, options?)

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)

parse(queryString, options?)

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)

extractQuery(url)

Extracts the query string from a URL.

parseUrl(url, options?)

Parses a URL and returns the query parameters as an object. Takes the same options as parse.

License

MIT