@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 ([email protected])

Repository: github.com/Chaisser/query-string