npm package: @nixat/query-string
Description: A powerful utility for parsing and stringifying URL query strings
Latest version: 0.2.0

# @nixat/query-string

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

## Installation

```bash
# 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

```typescript
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

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

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

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