Parse Query String into Object

Parses a query string (optionally starting with ?) into a JavaScript object.
Supports arrays for duplicate keys, and can intelligently convert string values to primitives (numbers, booleans, null).

Import

import { parseQueryString } from 'nhb-toolbox';
import { getQueryStringAsObject } from 'nhb-toolbox';
import { queryStringToObject } from 'nhb-toolbox';

Function Signature

function parseQueryString(
  query: string,
  parsePrimitives?: boolean
): StrictObject

Usage Examples

Basic

parseQueryString('a=1&b=hello');
// Returns: { a: 1, b: 'hello' }

With '?' Prefix

parseQueryString('?token=abc&active=true');
// Returns: { token: 'abc', active: true }

Multiple Values

parseQueryString('tag=js&tag=ts');
// Returns: { tag: ['js', 'ts'] }

No Primitive Parsing

parseQueryString('n=10&x=true', false);
// Returns: { n: '10', x: 'true' }

Null and Booleans

parseQueryString('opt=null&isTrue=false');
// Returns: { opt: null, isTrue: false }

API Reference

Parameters

Name	Type	Description
query	string	The query string to parse (with or without starting ?).
parsePrimitives	boolean	(Optional) Whether to parse primitive-like strings ("false", "1", "null", etc). Defaults to true.

Returns

A JavaScript object (StrictObject) where each key is a string and each value may be:

• string
• number
• boolean
• null
• string[], number[], boolean[], or null[]

Types

export type StrictObject = Record<string, unknown>;

Key Features

1. Flexible Input: Accepts query strings with or without a leading ?.
2. Arrays from Multiple Keys: If a key appears more than once, you get an array.
3. Automatic Primitive Parsing: Converts "1" → 1", "true" → true", "null" → null" by default.
4. Safe: Does not touch or depend on the browser’s window.location.

Aliases

This function is also exported as:

• getQueryStringAsObject
• queryStringToObject

Limitations

1. No Deep Objects: Does not generate nested objects for dotted or bracketed keys (e.g., a.b=1 stays flat).
2. Empty Key Handling: Keys without a value (e.g., foo&b=2) will be parsed with foo as an empty string "".
3. No Key Decoding Customization: Uses standard URL decoding.

Notes

• Type Guessing: Primitive parsing is based on string matching; "012" becomes number 12, not "012" unless parsePrimitives = false.
• Setting parsePrimitives: false is useful when you want all values as strings, like in typical form posts.
• Arrays are always returned for duplicate keys, regardless of primitive type.
• All values are string unless parsing is enabled (default).

Recommended Use Cases

• Parsing URLs or query strings in client-side and server-side environments.
• Reading user input or redirects where the string isn’t available on window.location.search.
• Back-end parsing of GET query strings for API endpoints.

---

Conclusion:
parseQueryString turns any query string into a highly usable JavaScript object, supporting advanced parsing and multi-value keys. It works with any string input, making it ideal for shared or non-browser environments.