@chaisser/query-string

Parse and stringify query strings with full type safety

Features

• Type-Safe - Full TypeScript support with exported types for all options and return values
• Zero Dependencies - No runtime dependencies, lightweight and fast
• ESM + CJS - Ships both ES Module and CommonJS formats
• Array Formats - Supports bracket (a[]=1), comma (a=1,2), repeat (a=1&a=2), and none
• Type Parsing - Automatic number and boolean parsing from query string values
• URL Encoding/Decoding - Handles URL-encoded values transparently
• URL Utilities - parseUrl, stringifyUrl, extract, pick, exclude, has, get
• Flexible Options - Sort keys, skip nulls, skip empty strings, custom encoders

Installation

# npm
npm install @chaisser/query-string

# yarn
yarn add @chaisser/query-string

# pnpm
pnpm add @chaisser/query-string

Quick Start

import { parse, stringify } from '@chaisser/query-string';

// Parse a query string
const params = parse('?name=John&age=30');
// { name: 'John', age: '30' }

// Stringify an object
const qs = stringify({ name: 'John', age: '30' });
// 'name=John&age=30'

What It Does

@chaisser/query-string provides a complete toolkit for working with URL query strings. It handles parsing query strings into typed objects, stringifying objects back into query strings, and includes utilities for working with full URLs.

Usage Examples

Parse

import { parse } from '@chaisser/query-string';

// Basic parsing
parse('foo=bar&baz=qux');
// { foo: 'bar', baz: 'qux' }

// With numbers and booleans
parse('count=5&active=true', { parseNumbers: true, parseBooleans: true });
// { count: 5, active: true }

// Array formats
parse('tags[]=js&tags[]=ts', { arrayFormat: 'bracket' });
// { tags: ['js', 'ts'] }

parse('tags=js,ts', { arrayFormat: 'comma' });
// { tags: ['js', 'ts'] }

parse('tags=js&tags=ts', { arrayFormat: 'repeat' });
// { tags: ['js', 'ts'] }

Stringify

import { stringify } from '@chaisser/query-string';

// Basic
stringify({ foo: 'bar' });
// 'foo=bar'

// Arrays
stringify({ tags: ['js', 'ts'] }, { arrayFormat: 'bracket' });
// 'tags[]=js&tags[]=ts'

stringify({ tags: ['js', 'ts'] }, { arrayFormat: 'comma' });
// 'tags=js,ts'

// Skip null values
stringify({ a: '1', b: null }, { skipNull: true });
// 'a=1'

// Sort keys
stringify({ c: '3', a: '1', b: '2' }, { sort: true });
// 'a=1&b=2&c=3'

parseUrl

import { parseUrl } from '@chaisser/query-string';

parseUrl('https://example.com/path?foo=bar&baz=qux');
// { url: 'https://example.com/path', query: { foo: 'bar', baz: 'qux' } }

stringifyUrl

import { stringifyUrl } from '@chaisser/query-string';

stringifyUrl({ url: 'https://example.com', query: { foo: 'bar' } });
// 'https://example.com?foo=bar'

stringifyUrl({ url: 'https://example.com?existing=yes', query: { new: 'param' } });
// 'https://example.com?existing=yes&new=param'

pick / exclude

import { pick, exclude } from '@chaisser/query-string';

pick('a=1&b=2&c=3', ['a', 'c']);
// 'a=1&c=3'

exclude('a=1&b=2&c=3', ['b']);
// 'a=1&c=3'

has / get

import { has, get } from '@chaisser/query-string';

has('?foo=bar&baz=qux', 'foo');
// true

get('?foo=bar', 'foo');
// 'bar'

get('?foo=bar', 'missing');
// null

API Reference

Function	Description
parse(queryString, options?)	Parse a query string into a QueryParams object
stringify(params, options?)	Stringify an object into a query string (no leading ?)
parseUrl(url, options?)	Parse a URL into { url, query }
stringifyUrl({ url, query }, options?)	Merge query params into a URL
extract(url)	Extract the query string portion from a URL
pick(urlOrQuery, keys, options?)	Keep only specified keys
exclude(urlOrQuery, keys, options?)	Remove specified keys
has(urlOrQuery, key)	Check if a key exists
get(urlOrQuery, key)	Get the value of a key

ParseOptions

Option	Type	Default	Description
arrayFormat	'bracket' | 'comma' | 'repeat' | 'none'	'none'	How to parse array values
parseNumbers	boolean	false	Convert numeric strings to numbers
parseBooleans	boolean	false	Convert 'true'/'false' to booleans
decode	boolean	true	URL-decode values

StringifyOptions

Option	Type	Default	Description
arrayFormat	'bracket' | 'comma' | 'repeat' | 'none'	'none'	How to format array values
encode	boolean	true	URL-encode values
skipNull	boolean	false	Skip keys with null values
skipEmptyString	boolean	false	Skip keys with empty string values
sort	boolean | ((a, b) => number)	false	Sort keys

Related Packages

• @chaisser/chunk-array - Array chunking utility
• @chaisser/string-wizard - String manipulation toolkit
• @chaisser/type-guard - Runtime type guards
• @chaisser/uuid-v7 - UUID v7 generation
• @chaisser/wait-for - Async wait utilities
• @chaisser/regex-humanizer - Regex to human-readable
• @chaisser/password-strength - Password strength checker
• @chaisser/human-time - Human-readable time formatting
• @chaisser/obj-path - Deep object path access
• @chaisser/debounce-throttle - Debounce and throttle
• @chaisser/color-utils - Color manipulation utilities
• @chaisser/deep-clone - Deep clone objects
• @chaisser/array-group-by - Array grouping
• @chaisser/merge-objects - Deep merge objects
• @chaisser/event-emitter - Type-safe event emitter
• @chaisser/unique-by - Unique array elements by key
• @chaisser/memoize - Function memoization
• @chaisser/base64-url - Base64 URL encoding
• @chaisser/ip-regex - IP address regex patterns
• @chaisser/retry-async - Async retry with backoff
• @chaisser/rate-limiter - Rate limiting utility
• @chaisser/circuit-breaker - Circuit breaker pattern
• @chaisser/cookie-parser - Cookie parsing utility

License

MIT

---

Developed by Doruk Karaboncuk (doruk.karaboncuk@interaktifis.com)

Repository: github.com/Chaisser/query-string