A TypeScript library to parse and stringify URL query strings.
npm install qs-tsA TypeScript library for parsing and stringifying URL query strings, inspired by the popular 'query-string' library. It provides robust handling of arrays, type inference, and encoding options.
- Type Inference: Flexible options to parse numbers (parseNumber) and booleans (parseBoolean)
- Array Formats: Support for repeat (key=a&key=b) and comma (key=a,b), plus configurable comma parsing
- Flexible Options: Configurable encoding/decoding, null handling, array formatting
- TypeScript Support: Full type definitions included
- Safe Parsing: Handles malformed encodings gracefully
- Dual Package: ESM and CommonJS support
``bash`
npm install qs-tsor
bun add qs-ts
>
> 💡 Consider using the native browser API URLSearchParams for simple use cases.
`typescript
import { parse } from 'qs-ts';
const result = parse('a=1&b=hello&c=true');
console.log(result);
// { a: '1', b: 'hello', c: 'true' } -> by default everything is a string
`
`typescript
import { stringify } from 'qs-ts';
const query = stringify({ a: 1, b: 'hello', c: true });
console.log(query);
// 'a=1&b=hello&c=true'
`
`javascript`
const { parse, stringify } = require('qs-ts');
Parses a query string into an object.
#### Options
- decode?: boolean (default: true) - Whether to decode percent-encoded charactersparseNumber?: boolean
- (default: false) - Attempt to parse numbers ("1", "12.5", "1e3" -> number).Number(val)
- Uses .parseBoolean?: boolean
- Does NOT parse "Infinity", "NaN", or empty strings.
- (default: false) - Attempt to parse booleans.array?: ParseArrayFormat
- Only "true" and "false" (lowercase) are converted.
- (default: { format: 'repeat' }) - How arrays are representedtypes?: Record
- - Explicit type casting (takes priority over global flags)ValueType
- supports "string" | "number" | "boolean" | "string[]" | "number[]"
ParseArrayFormat Definition:
`typescript`
type ParseArrayFormat =
| { format: "repeat" }
| { format: "comma"; encoded: "preserve" | "split" };
>
> ⚠️ Comma separated arrays depend on delimiter consistency. If values may be URL encoded or come from external sources, repeat is safer and more predictable.
- encoded: "preserve" splits on literal , only; %2C is treated as data.encoded: "split"
- splits on literal , and on %2C/%2c so results don’t depend on upstream encoding.
#### Examples
##### Parsing Numbers and Booleans
`typescript
parse('a=1&b=true&c=null', { parseNumber: true, parseBoolean: true });
// { a: 1, b: true, c: 'null' } (null literal not parsed unless typed)
parse('d=hello&e=001&f=12.5', { parseNumber: true });
// { d: 'hello', e: 1, f: 12.5 }
`
##### Array Formats
`typescript
// Repeat (default)
parse('tags=a&tags=b');
// { tags: ['a', 'b'] }
// Comma (Preserve encoded commas)
parse('tags=a,b%2Cc', { array: { format: 'comma', encoded: 'preserve' } });
// { tags: ['a', 'b,c'] }
// Comma (Split encoded commas)
parse('tags=a,b%2Cc', { array: { format: 'comma', encoded: 'split' } });
// { tags: ['a', 'b', 'c'] }
`
##### Explicit Types
Explicit types take priority over global parseNumber/parseBoolean flags.
`typescript`
parse('count=5&flags=on&items=a&items=b', {
parseNumber: true,
parseBoolean: true,
types: { count: 'string', flags: 'boolean', items: 'string[]' }
});
// { count: '5', flags: true, items: ['a', 'b'] }
// count stays string because of explicit type, despite parseNumber: true
##### Decoding Control
`typescript
parse('q=hello%20world', { decode: true });
// { q: 'hello world' }
parse('q=hello%20world', { decode: false });
// { q: 'hello%20world' }
`
Serializes an object into a query string.
#### Options
- encode?: boolean (default: true) - Whether to encode special charactersarray?: StringifyArrayFormat
- (default: { format: 'repeat' }) - How arrays are serializedskipNull?: boolean
- (default: false) - Whether to skip null valuesskipEmptyString?: boolean
- (default: false) - Whether to skip empty strings
StringifyArrayFormat Definition:
`typescript`
type StringifyArrayFormat =
| { format: "repeat" }
| { format: "comma" };
#### Examples
##### Basic Usage
`typescript`
stringify({ a: 1, b: 'hello', c: true });
// 'a=1&b=hello&c=true'
##### Array Formats
`typescript
// Repeat (default)
stringify({ tags: ['a', 'b', 'c'] });
// 'tags=a&tags=b&tags=c'
// Comma
stringify({ tags: ['a', 'b', 'c'] }, { array: { format: 'comma' } });
// 'tags=a,b,c'
`
##### Skipping Values
`typescript
stringify({ a: 1, b: null, c: '', d: undefined }, { skipNull: true, skipEmptyString: true });
// 'a=1'
stringify({ a: 1, b: null }, { skipNull: false });
// 'a=1&b'
`
##### Encoding Control
`typescript
stringify({ q: 'hello world' }, { encode: true });
// 'q=hello%20world'
stringify({ q: 'hello world' }, { encode: false });
// 'q=hello world'
`
Note: Nested objects are not supported. They are converted to their string representation.
`typescript
const obj = {
user: 'john',
age: 30,
active: true,
tags: ['developer', 'typescript'],
metadata: {
created: '2025-01-01' // This nested object will become '[object Object]'
}
};
const query = stringify(obj, { array: { format: 'repeat' } });
console.log(query);
// 'user=john&age=30&active=true&tags=developer&tags=typescript&metadata=%5Bobject%20Object%5D'
// When parsing back, you might want numeric/boolean values restored:
const parsed = parse(query, {
parseNumber: true,
parseBoolean: true,
array: { format: 'repeat' }
});
console.log(parsed);
// { user: 'john', age: 30, active: true, tags: ['developer', 'typescript'], metadata: '[object Object]' }
`
`typescript
// Parse from URL with repeat format (default)
const url2 = new URL('https://example.com/search?q=typescript&tags=web&tags=api&limit=10');
// inferTypes is gone, use specific flags if needed
const params2 = parse(url2.search.slice(1), { parseNumber: true, array: { format: 'repeat' } });
console.log(params2);
// { q: 'typescript', tags: ['web', 'api'], limit: 10 }
// Parse from URL with comma format
const url3 = new URL('https://example.com/search?q=typescript&tags=web,api&limit=10');
const params3 = parse(url3.search.slice(1), { parseNumber: true, array: { format: 'comma', encoded: 'preserve' } });
console.log(params3);
// { q: 'typescript', tags: ['web', 'api'], limit: 10 }
// Build URL
const baseUrl = 'https://example.com/search';
const queryString = stringify({ q: 'javascript', sort: 'recent' });
const fullUrl = ${baseUrl}?${queryString};`
console.log(fullUrl);
// 'https://example.com/search?q=javascript&sort=recent'
`bash`
bun run build
`bash`
bun test
`bash``
node verify.mjsor
bun verify.mjs
MIT - see LICENSE