JSURL2

https://github.com/wmertens/jsurl2
Admin
JSURL2 is a URL-friendly, compact, and fast JSON-like formatting and parsing library that serves as...
Tokens:21,002
Snippets:302
Trust Score:9.4
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install jsurl2 via NPM

Source: https://github.com/wmertens/jsurl2/blob/master/README.md

Command to install the library using the Node Package Manager.

```sh
npm install jsurl2
```

--------------------------------

### Configure ParseOptions

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/types.md

Examples demonstrating parsing with URI decoding enabled and using tryParse with a fallback.

```typescript
import { parse, tryParse, ParseOptions } from 'jsurl2'

// Basic parsing without URI decoding
const obj1 = parse('(name~John)~')

// URI-encoded input
const uriEncoded = '%28name~John%29~'
const opts: ParseOptions = { deURI: true }
const obj2 = parse(uriEncoded, opts)

// With tryParse
const fallback = { name: 'Unknown' }
const obj3 = tryParse(uriEncoded, fallback, opts)
```

--------------------------------

### Configure StringifyOptions

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/types.md

Examples showing how to apply short and rich modes when stringifying objects.

```typescript
import { stringify, StringifyOptions } from 'jsurl2'

// Minimal options
const opts1: StringifyOptions = { short: true }
const encoded1 = stringify(obj, opts1)

// Rich mode for preserving special values
const opts2: StringifyOptions = { rich: true }
const encoded2 = stringify(obj, opts2)

// Both options combined
const opts3: StringifyOptions = { short: true, rich: true }
const encoded3 = stringify(obj, opts3)
```

--------------------------------

### JSON Parsing Examples

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/ENCODING-FORMAT.md

Examples of input strings that the parser identifies and converts into native JavaScript values.

```javascript
'{"x":1}'
```

```javascript
'[1,2,3]'
```

```javascript
'true'
```

--------------------------------

### TryParse Usage Example

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/INDEX.md

Demonstrates using tryParse to return a default value when input is invalid.

```typescript
tryParse(userInput, { default: true })
// Returns fallback if userInput is invalid
```

--------------------------------

### Stringify Usage Example

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/INDEX.md

Basic usage of stringify to convert an object into JsUrl2 format.

```typescript
stringify({ name: 'Alice', age: 30 })
// Result: (name~Alice~age~30)~
```

--------------------------------

### Use JSURL2 in URL Query Strings

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/API-OVERVIEW.md

Example of encoding state for URL parameters and decoding them with deURI enabled.

```typescript
const state = { page: 1, filter: 'active' }
const encoded = stringify(state)
const url = `https://example.com?state=${encoded}`
// Browser will URI-encode automatically

// On next page:
const decoded = parse(newEncodedValue, { deURI: true })
```

--------------------------------

### Parse Usage Example

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/INDEX.md

Basic usage of parse to convert a JsUrl2 string back into a JavaScript object.

```typescript
parse<User>('(name~Alice~age~30)~')
// Result: { name: 'Alice', age: 30 } as User
```

--------------------------------

### Catch Cannot Decode Part Error

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/errors.md

Handles errors occurring when an unrecognized starting character is encountered during parsing.

```typescript
import { parse } from 'jsurl2'

try {
  const obj = parse('@invalid-format')
} catch (err) {
  if (err instanceof Error && err.message.includes('Cannot decode part')) {
    console.error('Input format is not valid JsUrl2 or JSON')
  }
}
```

--------------------------------

### Apply Generic Types to Decoded Data

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/types.md

Example of using a generic type parameter to enforce structure on parsed data.

```typescript
import { parse } from 'jsurl2'

interface User {
  name: string
  age: number
  email: string
}

const encoded = '(name~Alice~age~30~email~alice@example.com)~'
const user = parse<User>(encoded)
// TypeScript knows user is of type User
// user.name is string
// user.age is number

// Without type parameter
const unknown = parse(encoded)
// TypeScript infers any, no type checking
```

--------------------------------

### Gradual Adoption Strategies

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/USAGE-GUIDE.md

Shows how to support both JSON and jsurl2 formats during a transition period.

```typescript
// Support both formats
function parseAny(input: string) {
  const result = tryParse(input, null)
  return result !== null ? result : JSON.parse(input)
}

// Emit new format, accept both
function send(data: any) {
  return stringify(data)  // Smaller output
}
```

--------------------------------

### Run JSURL2 Benchmarks

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/USAGE-GUIDE.md

Execute the built-in performance test suite using npm.

```bash
npm run bench
```

--------------------------------

### Perform Basic Roundtrip

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/INDEX.md

Demonstrates basic object serialization and deserialization.

```typescript
import { stringify, parse } from 'jsurl2'

const obj = { x: 1, y: 'hello' }
const encoded = stringify(obj)
const decoded = parse(encoded)
// decoded equals obj by value
```

--------------------------------

### Unit Testing with Vitest

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/USAGE-GUIDE.md

Demonstrates basic roundtrip serialization and error handling using tryParse.

```typescript
import { stringify, parse, tryParse } from 'jsurl2'
import { expect, test } from 'vitest'

test('roundtrip', () => {
  const original = { a: 1, b: 'hello' }
  const encoded = stringify(original)
  const decoded = parse(encoded)
  expect(decoded).toEqual(original)
})

test('error handling', () => {
  const result = tryParse('invalid', { default: true })
  expect(result).toEqual({ default: true })
})
```

--------------------------------

### Project File Structure

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/README.md

Visual representation of the project's documentation directory layout.

```text
/workspace/home/output/
├── README.md                    (this file)
├── INDEX.md                     (navigation and quick reference)
├── API-OVERVIEW.md              (quick reference guide)
├── USAGE-GUIDE.md               (practical patterns)
├── IMPLEMENTATION.md            (internal architecture)
├── ENCODING-FORMAT.md           (format specification)
├── types.md                     (type definitions)
├── errors.md                    (error catalog)
└── api-reference/
    ├── stringify.md             (stringify() reference)
    ├── parse.md                 (parse() reference)
    └── tryParse.md              (tryParse() reference)
```

--------------------------------

### Implement Server-Side Rendering

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/INDEX.md

Passing initial state from server to client via serialized script tags.

```typescript
// Server
const initialState = { user: { id: 1 }, posts: [] }
const html = `<script>
  const INITIAL_STATE = ${stringify(initialState)}
</script>`

// Client
const state = parse(INITIAL_STATE)
```

--------------------------------

### Import jsurl2 with TypeScript

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/INDEX.md

Includes type definitions for stringify and parse options in TypeScript projects.

```typescript
import {
  stringify,
  parse,
  tryParse,
  StringifyOptions,
  ParseOptions
} from 'jsurl2'
```

--------------------------------

### Import jsurl2

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/USAGE-GUIDE.md

Import the library using CommonJS, ES Modules, or TypeScript syntax.

```javascript
const { stringify, parse, tryParse } = require('jsurl2')
```

```javascript
import { stringify, parse, tryParse } from 'jsurl2'
```

```typescript
import { stringify, parse, tryParse, StringifyOptions, ParseOptions } from 'jsurl2'
```

--------------------------------

### Safe Parsing Patterns with jsurl2

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/errors.md

Demonstrates using tryParse for default values, explicit try-catch blocks for error categorization, and logging for graceful degradation.

```typescript
import { parse, tryParse } from 'jsurl2'

// Pattern 1: Using tryParse (recommended for most cases)
const defaultObj = { status: 'unknown' }
const obj = tryParse(userInput, defaultObj)
// Returns defaultObj if parsing fails, no exception

// Pattern 2: Explicit try-catch with categorization
function parseUserInput(input: string) {
  try {
    return parse(input)
  } catch (err) {
    if (err instanceof Error) {
      if (err.message.includes('Illegal escape code')) {
        throw new Error('Invalid encoded string detected')
      } else if (err.message.includes('Unknown dict reference')) {
        throw new Error('Unsupported special value in input')
      } else if (err.message.includes('Not a number')) {
        throw new Error('Malformed number encountered')
      } else {
        throw new Error('Invalid input format')
      }
    }
    throw err
  }
}

// Pattern 3: Logging and graceful degradation
function parseWithLogging(input: string, fallback: any = {}) {
  try {
    return parse(input)
  } catch (err) {
    console.warn('Parse failed:', err instanceof Error ? err.message : err)
    return fallback
  }
}
```

--------------------------------

### URI-Ready Output

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/api-reference/stringify.md

Shows how the output can be directly embedded into a URL query string.

```typescript
const data = { query: 'search term', limit: 10 }
const encoded = stringify(data)
// Result: (query~search_term~limit~10)~

// Can be used in query string without further encoding
const url = `https://example.com/api?data=${encoded}`
// Browsers will URI-encode the output automatically if needed
```

--------------------------------

### Import jsurl2 via CommonJS

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/INDEX.md

Use this syntax for Node.js environments using CommonJS modules.

```javascript
const { stringify, parse, tryParse } = require('jsurl2')
```

--------------------------------

### Import jsurl2 via ES Modules

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/INDEX.md

Use this syntax for modern JavaScript environments supporting ES modules.

```javascript
import { stringify, parse, tryParse } from 'jsurl2'
```

--------------------------------

### tryParse(value, options?)

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/API-OVERVIEW.md

Attempts to parse a JSURL2 string, returning a default value if parsing fails.

```APIDOC
## tryParse(value, options?)

### Description
Safely parses a JSURL2 string. If the input is malformed, it returns the provided default value.

### Parameters
- **value** (string) - Required - The encoded string to parse.
- **options** (ParseOptions & { default: any }) - Optional - Configuration object including a default value to return on error.

### Example
```typescript
import { tryParse } from 'jsurl2';
const data = tryParse(userInput, { default: true });
```
```

--------------------------------

### SSR State Serialization and Parsing

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/USAGE-GUIDE.md

Demonstrates serializing state on the server for embedding in HTML and parsing it on the client.

```typescript
// Server-side (e.g., Node.js)
import { stringify } from 'jsurl2'

const initialState = {
  user: { id: 1, name: 'Alice' },
  posts: [{ id: 1, title: 'Hello' }],
  theme: 'dark'
}

const encoded = stringify(initialState, { rich: true })

// Emit HTML with state embedded
const html = `
  <html>
    <body>
      <div id="root"></div>
      <script>
        const INITIAL_STATE = ${encoded};
        // Application code uses INITIAL_STATE
      </script>
    </body>
  </html>
`
```

```typescript
// Client-side (e.g., React, Vue)
import { parse } from 'jsurl2'

// INITIAL_STATE is already parsed by browser
const initialState = INITIAL_STATE || {}
// Or if encoded as string:
const initialState = parse(INITIAL_STATE, { rich: true })
```

--------------------------------

### StringifyOptions

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/types.md

Configuration object for the stringify function to control encoding behavior.

```APIDOC
## StringifyOptions

### Description
Options object passed to the `stringify` function to control encoding behavior.

### Fields
- **short** (boolean) - Optional - When true, omits optional closing delimiters to reduce output size.
- **rich** (boolean) - Optional - When true, encodes JavaScript Date objects, undefined, NaN, and Infinity as decodable special values.
```

--------------------------------

### JsUrl2 Format Comparison

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/00-START-HERE.md

Comparison of JsUrl2 format against standard JSON for a simple object.

```text
JavaScript Object        JsUrl2 Format             Size
{ name: 'John', age: 42 } → (name~John~age~42)~    (18 bytes)
JSON: {"name":"John","age":42}                      (28 bytes)
```

--------------------------------

### Configure Conditional Encoding

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/USAGE-GUIDE.md

Wrap stringify to apply context-specific options like compact mode.

```typescript
import { stringify } from 'jsurl2'

function encodeData(data: any, options?: { compact?: boolean }) {
  const stringifyOptions: StringifyOptions = {
    short: options?.compact,
    rich: true
  }
  
  return stringify(data, stringifyOptions)
}

// Use based on context
const small = encodeData(data, { compact: true })  // For URLs
const normal = encodeData(data)                     // For storage
```

--------------------------------

### stringify(value: any, options?: StringifyOptions): string

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/API-OVERVIEW.md

Encodes a JavaScript value into compact JsUrl2 format or rich format.

```APIDOC
## stringify

### Description
Encodes a JavaScript value into compact JsUrl2 format or rich format (with Dates, undefined, etc.).

### Signature
`stringify(value: any, options?: StringifyOptions): string`

### Options
- **short** (boolean) - Optional
- **rich** (boolean) - Optional

### Returns
- **string** - Encoded string, never throws
```

--------------------------------

### Encode and decode objects with jsurl2

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/00-START-HERE.md

Demonstrates basic usage of stringify and parse functions, including safe parsing with a fallback value.

```typescript
import { stringify, parse } from 'jsurl2'

// Encode an object
const obj = { name: 'John', age: 42, active: true }
const encoded = stringify(obj)
// Result: (name~John~age~42~active~~)~

// Decode it back
const decoded = parse(encoded)
// Result: { name: 'John', age: 42, active: true }

// Safe decoding with fallback
const result = tryParse(userInput, { name: 'Unknown' })
// Returns fallback if userInput is invalid
```

--------------------------------

### JSURL.stringify(obj[, options])

Source: https://github.com/wmertens/jsurl2/blob/master/docs/index.html

Serializes a JavaScript object into a JSURL string.

```APIDOC
## JSURL.stringify(obj[, options])

### Description
Converts a JavaScript object into a JSURL string representation.

### Parameters
- **obj** (Object) - Required - The object to serialize.
- **options** (Object) - Optional - Configuration options: `rich` (encode Date, undefined, Infinity) or `short` (remove optional trailing delimiters).
```

--------------------------------

### Array Encoding

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/api-reference/stringify.md

Demonstrates how arrays are serialized into the jsurl2 format.

```typescript
const arr = [1, 'hello', true, false]
const encoded = stringify(arr)
// Result: !1~hello~~_F~~
```

--------------------------------

### Query String Usage

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/api-reference/parse.md

Extracting and parsing data directly from URL query parameters.

```typescript
// Extract and parse data from URL query string
const params = new URLSearchParams(location.search)
const data = parse(params.get('state'), { deURI: true })
```

--------------------------------

### Use in URL Query Parameters

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/INDEX.md

Encoding state for use in URL query strings.

```typescript
const state = { page: 2, filter: 'active' }
const encoded = stringify(state)
const url = `https://example.com?state=${encoded}`

// Later:
const decoded = parse(encoded, { deURI: true })
```

--------------------------------

### Perform Basic Encoding and Decoding

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/API-OVERVIEW.md

Standard usage of stringify and parse functions.

```typescript
import { stringify, parse } from 'jsurl2'

const data = { name: 'John', age: 30 }
const encoded = stringify(data)           // (name~John~age~30)~
const decoded = parse(encoded)            // { name: 'John', age: 30 }
```

--------------------------------

### parse(value, options?)

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/API-OVERVIEW.md

Parses a JSURL2 string back into a JavaScript object.

```APIDOC
## parse(value, options?)

### Description
Parses a JSURL2 encoded string back into its original JavaScript value.

### Parameters
- **value** (string) - Required - The encoded string to parse.
- **options** (ParseOptions) - Optional - Configuration object.
  - **deURI** (boolean) - Remove URI encoding and whitespace before parsing.

### Example
```typescript
import { parse } from 'jsurl2';
const decoded = parse('(name~John)', { deURI: true });
```
```

--------------------------------

### JSURL.tryParse(str[, default][, options])

Source: https://github.com/wmertens/jsurl2/blob/master/docs/index.html

Parses a JSURL string, returning a default value instead of throwing an error on failure.

```APIDOC
## JSURL.tryParse(str[, default][, options])

### Description
Attempts to parse a JSURL string. If parsing fails, it returns the provided default value instead of throwing an exception.

### Parameters
- **str** (String) - Required - The JSURL string to parse.
- **default** (Any) - Optional - The value to return if parsing fails.
- **options** (Object) - Optional - Options passed directly to the parse() method.
```

--------------------------------

### Drop-in Replacement for JSON

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/USAGE-GUIDE.md

Compares standard JSON methods with jsurl2 equivalents.

```typescript
// Before
const str = JSON.stringify(obj)
const parsed = JSON.parse(str)

// After
const str = stringify(obj)  // Usually smaller
const parsed = parse(str)   // Same API
```

--------------------------------

### Optimize JSURL2 for Small Data

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/USAGE-GUIDE.md

Use JSURL2 for small objects and booleans to achieve size advantages over JSON. Prefer standard JSON for large data payloads.

```typescript
// Good use case
stringify({ active: true, verified: true, pending: false })
// (active~~verified~~pending~_F~)  — 35 bytes
// vs JSON 50 bytes

// Use JSON for large data
stringify({ content: 'very long text...' })  // Still works, but no size advantage
```

--------------------------------

### tryParse

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/README.md

Safe parsing that returns a fallback value on error instead of throwing.

```APIDOC
## tryParse<T>(encoded: string, fallback?: T, options?: ParseOptions): T

### Description
Safe parsing that returns a fallback value on error instead of throwing.

### Parameters
- **encoded** (string) - Required - The encoded string to parse.
- **fallback** (T) - Optional - The value to return if parsing fails.
- **options** (ParseOptions) - Optional - Configuration options.
```

--------------------------------

### stringify(value, options?)

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/API-OVERVIEW.md

Serializes a JavaScript object or value into a JSURL2 string.

```APIDOC
## stringify(value, options?)

### Description
Converts a JavaScript value into a URL-friendly string representation.

### Parameters
- **value** (any) - Required - The value to serialize.
- **options** (StringifyOptions) - Optional - Configuration object.
  - **short** (boolean) - Omit trailing delimiters.
  - **rich** (boolean) - Encode special types like Dates, undefined, NaN, and Infinity.

### Example
```typescript
import { stringify } from 'jsurl2';
const encoded = stringify({ name: 'John' }, { short: true });
```
```

--------------------------------

### ParseOptions

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/types.md

Configuration object for the parse and tryParse functions to control decoding behavior.

```APIDOC
## ParseOptions

### Description
Options object passed to the `parse` or `tryParse` function to control decoding behavior.

### Fields
- **deURI** (boolean) - Optional - When true, pre-processes the input to remove URI percent encoding and whitespace before parsing.
```

--------------------------------

### Basic Object Encoding

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/api-reference/stringify.md

Standard usage for converting a plain JavaScript object into a stringified URL format.

```typescript
import { stringify } from 'jsurl2'

const obj = {
  name: 'John Doe',
  age: 42,
  children: ['Mary', 'Bill']
}

const encoded = stringify(obj)
// Result: (name~John_Doe~age~42~children~!Mary~Bill)~
```

--------------------------------

### Apply Short Mode for Space Savings

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/API-OVERVIEW.md

Use the short option to omit trailing delimiters in the encoded string.

```typescript
const encoded = stringify(data, { short: true })  // (name~John~age~30)
const decoded = parse(encoded)                    // Still works fine
```

--------------------------------

### JSURL.stringify(obj[, options])

Source: https://github.com/wmertens/jsurl2/blob/master/README.md

Serializes a JavaScript object into a JSURL2 string. Options include 'rich' for encoding Date, undefined, and Infinity, and 'short' to remove optional trailing delimiters.

```APIDOC
## JSURL.stringify(obj[, options])

### Description
Converts a JavaScript object into a JSURL2 string representation.

### Parameters
- **obj** (Object) - Required - The object to serialize.
- **options** (Object) - Optional - Configuration object. Supported keys: 'rich' (boolean), 'short' (boolean).
```

--------------------------------

### JSURL.parse(str[, options])

Source: https://github.com/wmertens/jsurl2/blob/master/docs/index.html

Parses a JSURL string back into a JavaScript object.

```APIDOC
## JSURL.parse(str[, options])

### Description
Parses a JSURL string and returns the corresponding JavaScript object.

### Parameters
- **str** (String) - Required - The JSURL string to parse.
- **options** (Object) - Optional - Configuration options: `deURI` (remove URI encoding and whitespace).
```

--------------------------------

### Implement JSON Fallback Parsing

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/USAGE-GUIDE.md

Use tryParse to attempt JSURL2 decoding before falling back to standard JSON.parse.

```typescript
import { parse, tryParse } from 'jsurl2'

function parseFlexible(input: string) {
  // Try JSURL2 first
  const result = tryParse(input, null)
  
  if (result !== null) {
    return result
  }
  
  // Fall back to JSON
  try {
    return JSON.parse(input)
  } catch (err) {
    console.error('Failed to parse:', err)
    return {}
  }
}
```

--------------------------------

### JSURL Performance Benchmark Script

Source: https://github.com/wmertens/jsurl2/blob/master/docs/performance.html

Executes a loop of 200,000 operations for both JSON and JSURL to measure serialization and parsing performance.

```javascript
const count = 200000 const v = { a: [[1, 2], [], false, {}, true], b: [], c: {d: 'hello', e: {}, f: [], g: true, n: null}, } const JSONParse = () => { const n = Date.now() const s = JSON.stringify(v) for (let i = 0; i < count; i++) { JSON.parse(s) } const ms = Date.now() - n console.log(`JSON: ${count} parsed in ${ms}ms, ${ms / count}ms/item`) } const JSONStringify = () => { const n = Date.now() for (let i = 0; i < count; i++) { JSON.stringify(v) } const ms = Date.now() - n console.log(`JSON: ${count} stringified in ${ms}ms, ${ms / count}ms/item`) } const v2Parse = () => { const n = Date.now() const s = JSURL.stringify(v) for (let i = 0; i < count; i++) { JSURL.parse(s) } const ms = Date.now() - n console.log(`v2: ${count} parsed in ${ms}ms, ${ms / count}ms/item`) } const v2Stringify = () => { const n = Date.now() for (let j = 0; j < count; j++) { JSURL.stringify(v) } const ms = Date.now() - n console.log(`v2: ${count} stringified in ${ms}ms, ${ms / count}ms/item`) } window.onload = () => { JSONParse() JSONStringify() v2Parse() v2Stringify() }
```

--------------------------------

### stringify(value, options)

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/INDEX.md

Serializes a JavaScript object or value into a URL-friendly string.

```APIDOC
## stringify(value, options)

### Description
Converts a JavaScript value into a URL-safe string representation.

### Parameters
- **value** (any) - The object or value to serialize.
- **options** (StringifyOptions) - Optional configuration object.
  - **short** (boolean) - Omit optional delimiters.
  - **rich** (boolean) - Preserve special values like Dates, undefined, and NaN.
```

--------------------------------

### Backwards Compatibility with Legacy Data

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/api-reference/tryParse.md

Uses tryParse to handle mixed format data, returning a fallback only if all parsing attempts fail.

```typescript
// Handle both new JsUrl2 format and old JSON format
const legacyOrNew = '(user~admin~timestamp~_D2024-01-15)~'
const data = tryParse(legacyOrNew, { user: 'guest', timestamp: null })
// Parser auto-detects format, returns fallback only if both formats fail
```

--------------------------------

### Encode State for URLs

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/USAGE-GUIDE.md

Prepare state objects for inclusion in URL query parameters.

```typescript
import { stringify } from 'jsurl2'

const state = {
  page: 2,
  sort: 'name',
  filters: ['active', 'verified']
}

const encoded = stringify(state)
// Result: (page~2~sort~name~filters~!active~verified~~)~

// Use in URL
const url = `https://api.example.com/users?state=${encoded}`
// Browser automatically URI-encodes special characters

// Or with explicit encoding:
const safeUrl = `https://api.example.com/users?state=${encodeURIComponent(encoded)}`
```

--------------------------------

### Real-World Form Processing

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/api-reference/tryParse.md

Handles multiple fields with varying fallback strategies based on expected data types.

```typescript
// Processing form data where some fields might be invalid
const formData = {
  user: '(name~John~email~john@example.com)~',
  metadata: 'invalid json {',
  settings: '(theme~dark~notifications~true)~'
}

const processed = {
  user: tryParse(formData.user, null),
  metadata: tryParse(formData.metadata, {}),
  settings: tryParse(formData.settings, {})
}

// processed.user is the decoded object or null
// processed.metadata is {} (fallback)
// processed.settings is the decoded object or {}
```

--------------------------------

### Object Key Encoding

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/IMPLEMENTATION.md

Demonstrates how object keys containing special characters are escaped during the encoding process.

```typescript
const obj = { 'hello world': 1, 'key~with~tildes': 2 }
// Encoded: (hello_world~1~key*-with*-tildes~2)~
```

--------------------------------

### String Encoding Format

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/ENCODING-FORMAT.md

The format for encoding strings, including rules for prefixes and reserved character escaping.

```text
[*]? ( [a-zA-Z_] | [^reserved]* )+ ~
```

--------------------------------

### Define StringifyOptions

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/types.md

Type definition for configuring the stringify function.

```typescript
type StringifyOptions = {
  short?: boolean
  rich?: boolean
}
```

--------------------------------

### Process Batches Safely

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/USAGE-GUIDE.md

Use tryParse to filter out corrupted inputs during batch processing.

```typescript
import { tryParse } from 'jsurl2'

interface Item {
  id: number
  name: string
}

function processBatch(inputs: string[]): Item[] {
  return inputs
    .map(input => tryParse<Item>(input, null))
    .filter((item): item is Item => item !== null)
}

const data = processBatch([
  '(id~1~name~Alice)~',
  'corrupted',
  '(id~2~name~Bob)~'
])
// Result: [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
```

--------------------------------

### Safe Parsing with tryParse

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/USAGE-GUIDE.md

Uses tryParse to provide default values for user input without throwing exceptions.

```typescript
import { tryParse } from 'jsurl2'

function loadUserSettings(input: string) {
  const defaults = {
    theme: 'light',
    notifications: true,
    language: 'en'
  }
  
  const settings = tryParse(input, defaults)
  return settings
}

// Safe — never throws
const settings = loadUserSettings(userProvidedString)
```

--------------------------------

### JSURL2 API Usage

Source: https://github.com/wmertens/jsurl2/blob/master/docs/index.html

Basic usage of the JSURL2 library for stringifying and parsing objects. Options like 'rich', 'short', and 'deURI' control encoding behavior and error handling.

```javascript
var JSURL = require("jsurl2");

// Options:
// * `rich`: encode Date, `undefined`, `Infinity`
// * `short`: remove optional trailing delimiters
str = JSURL.stringify(obj[, options]);

// Options:
// * `deURI`: remove URI encoding and whitespace
obj = JSURL.parse(str[, options]);

// return `default` instead of throwing on error; options are passed to `parse()`
obj = JSURL.tryParse(str[, default][, options]);
```

--------------------------------

### Optimize Output Size

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/USAGE-GUIDE.md

Use short mode to reduce string length compared to standard JSON serialization.

```typescript
import { stringify } from 'jsurl2'

const data = { a: 1, b: 2, c: true, d: false }

const normal = stringify(data)
// (a~1~b~2~c~~d~_F~)~  — 27 bytes

const short = stringify(data, { short: true })
// (a~1~b~2~c~d~_F)    — 21 bytes

// JSON for comparison
const json = JSON.stringify(data)
// {"a":1,"b":2,"c":true,"d":false}  — 32 bytes
```

```typescript
const encoded = stringify(data, { short: true, rich: true })
// Smallest output + preserves special types

// Size comparison for { date: new Date(), val: NaN }
// JSON: {"date":"2024-01-15T00:00:00.000Z","val":null}  — 50 bytes
// JSURL2: (date~_D2024-01-15~val~_n~)~  — 32 bytes
// JSURL2 short: (date~_D2024-01-15~val~_n)  — 30 bytes
```

--------------------------------

### Validate User Input with tryParse

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/USAGE-GUIDE.md

Use tryParse instead of parse to prevent application crashes when processing potentially invalid user-provided input strings.

```typescript
// Risky
function processUserInput(input: string) {
  const data = parse(input)  // Throws on invalid input
  return data
}

// Safe
function processUserInput(input: string) {
  const data = tryParse(input, {})  // Never throws
  return data
}
```

--------------------------------

### Handle parsing errors in TypeScript

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/api-reference/parse.md

Demonstrates catching errors thrown by the parse function when encountering invalid input formats.

```typescript
import { parse } from 'jsurl2'

try {
  const obj = parse('*invalid-escape')
} catch (err) {
  console.error(err.message)
  // Error: Illegal escape code "*i"
}
```

--------------------------------

### tryParse(encoded, defaultValue)

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/INDEX.md

Attempts to parse an encoded string, returning a default value if parsing fails.

```APIDOC
## tryParse(encoded, defaultValue)

### Description
An error-safe parsing method that returns the provided default value instead of throwing an error if the input is invalid.

### Parameters
- **encoded** (string) - The encoded string to parse.
- **defaultValue** (any) - The value to return if parsing fails.
```

--------------------------------

### With URI Decoding

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/api-reference/tryParse.md

Enables URI decoding during the parsing process using the deURI option.

```typescript
// URL query string with URI-encoded data
const params = new URLSearchParams(location.search)
const stateStr = params.get('state')

const defaultState = { view: 'list', page: 1 }
const state = tryParse(stateStr || '', defaultState, { deURI: true })
```

--------------------------------

### Safe Parsing with Default Value

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/api-reference/tryParse.md

Demonstrates using a fallback object when parsing valid and invalid input strings.

```typescript
import { tryParse } from 'jsurl2'

const encoded = '(name~John~age~42)~'
const obj = tryParse(encoded, {})
// Result: { name: 'John', age: 42 }

const badInput = 'not valid jsurl'
const fallback = { name: 'Unknown', age: 0 }
const obj2 = tryParse(badInput, fallback)
// Result: { name: 'Unknown', age: 0 }
```

--------------------------------

### Represent JSON data formats

Source: https://github.com/wmertens/jsurl2/blob/master/README.md

Comparison of standard JSON, URI-encoded JSON, JSURL2, and URI-encoded JSURL2 formats.

```json
{"name": "John Doé", "age": 42, "user": true, "children": ["Mary", "Bill"]}
```

```text
%7B%22name%22%3A%22John%20Do%C3%22%2C%22age%22%3A42%2C%22user%22%3Atrue%2C%22children%22%3A%5B%22Mary%22%2C%22Bill%22%5D%7D
```

```jsurl
(name~John_Doé~age~42~user~~children~!Mary~Bill)~
```

```text
(name~John_Do%C3%A9~age~42~user~~children~!Mary~Bill)~
```

--------------------------------

### Unicode Handling

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/IMPLEMENTATION.md

Shows that Unicode characters are preserved without explicit escaping during encoding.

```typescript
const obj = { name: 'José', emoji: '🎉' }
// Encoded: (name~José~emoji~🎉)~
// No Unicode escaping needed (URI encoding will handle if needed)
```

--------------------------------

### Perform Error-Safe Parsing

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/INDEX.md

Parsing input without throwing errors by providing default values.

```typescript
const defaults = { theme: 'light' }
const settings = tryParse(userInput, defaults)
// Never throws; returns defaults on error
```

--------------------------------

### parse(encoded, options)

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/INDEX.md

Decodes a JsUrl2 or JSON string back into a JavaScript value.

```APIDOC
## parse(encoded, options)

### Description
Decode JsUrl2 or JSON string to JavaScript value.

### Signature
`function parse<T>(encoded: string, options?: ParseOptions): T`

### Parameters
- **encoded** (string) - Required - The JsUrl2 encoded string.
- **options** (ParseOptions) - Optional - Configuration options:
  - **deURI** (boolean) - Remove URI encoding before parsing.

### Example
```typescript
parse<User>('(name~Alice~age~30)~')
// Result: { name: 'Alice', age: 30 } as User
```
```

--------------------------------

### parse(encoded, options)

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/INDEX.md

Parses a jsurl2-encoded string back into a JavaScript object.

```APIDOC
## parse(encoded, options)

### Description
Decodes a string generated by stringify back into its original JavaScript value.

### Parameters
- **encoded** (string) - The encoded string to parse.
- **options** (ParseOptions) - Optional configuration object.
  - **deURI** (boolean) - Decode URI escapes.
```

--------------------------------

### Regular Expressions

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/IMPLEMENTATION.md

Regex patterns used for string detection, character escaping, and JSON format identification.

```typescript
const stringRE = /^[a-zA-Z]/
// Detects if string can omit * prefix

const numRE = /^[\d-]/
// Detects if value starts as number

const replaceRE = /([*_~$+'() <>%?#&=\\\n\r\0  ])/g
// Identifies characters needing escape in strings

const escapeRE = /(_|\*.)/g
// Identifies escape sequences in input

const JSONRE = /^({|\[|"|true$|false$|null$)/
// Auto-detects JSON format
```

--------------------------------

### JSURL.parse(str[, options])

Source: https://github.com/wmertens/jsurl2/blob/master/README.md

Parses a JSURL2 string back into a JavaScript object. The 'deURI' option can be used to remove URI encoding and whitespace before parsing.

```APIDOC
## JSURL.parse(str[, options])

### Description
Parses a JSURL2 string and returns the corresponding JavaScript object.

### Parameters
- **str** (String) - Required - The JSURL2 string to parse.
- **options** (Object) - Optional - Configuration object. Supported keys: 'deURI' (boolean).
```

--------------------------------

### Encode Objects

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/USAGE-GUIDE.md

Convert JavaScript objects into URL-friendly strings.

```typescript
import { stringify } from 'jsurl2'

const user = {
  id: 123,
  name: 'Alice',
  email: 'alice@example.com',
  active: true
}

const encoded = stringify(user)
// Result: (id~123~name~Alice~email~alice@example.com~active~~)~
```

--------------------------------

### Roundtrip Guarantee

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/api-reference/parse.md

Demonstrates that stringify and parse operations maintain data integrity.

```typescript
import { stringify, parse } from 'jsurl2'

const original = { users: ['Alice', 'Bob'], count: 2 }
const encoded = stringify(original)
const decoded = parse(encoded)

console.log(decoded) // { users: ['Alice', 'Bob'], count: 2 }
// decoded === original (by value, not reference)
```

--------------------------------

### JSURL2 Exported Functions Signature

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/API-OVERVIEW.md

Core function signatures for stringify, parse, and tryParse operations.

```typescript
stringify(value: any, options?: StringifyOptions): string
parse<T>(encoded: string, options?: ParseOptions): T
tryParse<T>(encoded: string, fallback?: T, options?: ParseOptions): T
```

--------------------------------

### Decode from URL

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/USAGE-GUIDE.md

Extract and decode state from URL query parameters in browser or Node.js environments.

```typescript
import { parse } from 'jsurl2'

// In browser
const params = new URLSearchParams(location.search)
const stateStr = params.get('state')
const state = parse(stateStr, { deURI: true })

// In Node.js
import { URL } from 'url'
const url = new URL('https://example.com?state=...')
const stateStr = url.searchParams.get('state')
const state = parse(stateStr, { deURI: true })
```

--------------------------------

### Roundtrip Guarantee

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/USAGE-GUIDE.md

Verify that encoding and decoding preserves the original data structure.

```typescript
const original = { x: 1, y: 'hello' }
const encoded = stringify(original)
const decoded = parse(encoded)
console.log(JSON.stringify(decoded) === JSON.stringify(original)) // true
```

--------------------------------

### JSON Compatibility

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/api-reference/parse.md

The parser is capable of handling both standard JSON strings and JSURL-encoded strings.

```typescript
// Same parser handles both formats
const json = '{"name":"John","age":42}'
const jsurl = '(name~John~age~42)~'

const obj1 = parse(json)    // Works fine
const obj2 = parse(jsurl)   // Works fine

// Both return: { name: 'John', age: 42 }
```

--------------------------------

### Basic Decoding with jsurl2

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/api-reference/parse.md

Standard usage of the parse function to convert a JSURL string into an object.

```typescript
import { parse } from 'jsurl2'

const encoded = '(name~John_Doe~age~42)~'
const obj = parse(encoded)
// Result: { name: 'John Doe', age: 42 }
```

--------------------------------

### Short Mode Encoding

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/api-reference/stringify.md

Reduces string length by omitting the trailing tilde character.

```typescript
const encoded = stringify(obj, { short: true })
// Result: (name~John_Doe~age~42~children~!Mary~Bill)
// Note: no trailing ~
```

--------------------------------

### Stringify JavaScript values

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/README.md

Encodes JavaScript values into the compact JsUrl2 format.

```typescript
stringify(value: any, options?: StringifyOptions): string
```

```typescript
stringify({ name: 'John', age: 42 })
// Result: (name~John~age~42)~
```

--------------------------------

### Maintain Roundtrip Consistency

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/USAGE-GUIDE.md

Always use the same options during stringification and parsing to ensure data integrity.

```typescript
// Problem
const original = { a: 1 }
const short1 = stringify(original, { short: true })
const decoded = parse(short1)
const short2 = stringify(decoded, { short: true })
console.log(short1 === short2)  // true

// Solution: Always use same options for roundtrip
const encoded = stringify(data, { short: true })
const decoded = parse(encoded)
// Don't expect short2 to equal short1 if stringified without options
```

--------------------------------

### tryParse<T>(encoded: string, fallback?: T, options?: ParseOptions): T

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/api-reference/tryParse.md

Safely decodes a JsUrl2 or JSON encoded string, returning a fallback value if parsing fails instead of throwing an error.

```APIDOC
## tryParse<T>(encoded, fallback, options)

### Description
Safely decodes a JsUrl2 or JSON encoded string. If parsing fails, it returns the provided fallback value instead of throwing an error.

### Parameters
- **encoded** (string) - Required - The JsUrl2 or JSON encoded string to decode.
- **fallback** (T | undefined) - Optional - The value to return if parsing fails. Defaults to `undefined`.
- **options** (ParseOptions) - Optional - Configuration object for parsing behavior.
  - **deURI** (boolean) - Optional - When true, pre-processes the input to remove URI encoding and whitespace before parsing.

### Return Type
- **T** - The decoded value on success, or the fallback value on failure.

### Usage Example
```typescript
import { tryParse } from 'jsurl2';

// Basic usage
const obj = tryParse('(name~John~age~42)~', {});

// Usage with fallback
const config = tryParse<Config>(configStr, defaultConfig);

// Usage with URI decoding
const state = tryParse(stateStr, defaultState, { deURI: true });
```
```

--------------------------------

### Define ParseOptions

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/types.md

Type definition for configuring the parse and tryParse functions.

```typescript
type ParseOptions = {
  deURI?: boolean
}
```

--------------------------------

### Decoding with Rich Types

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/api-reference/parse.md

Supports automatic conversion of special types like Dates and NaN values.

```typescript
const encoded = '(date~_D2024-01-15~value~_n~)~'
const obj = parse(encoded)
// Result: { date: Date('2024-01-15'), value: NaN }
```

--------------------------------

### JSON Detection Pattern

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/ENCODING-FORMAT.md

Regex pattern used by the parser to identify JSON-formatted input strings.

```regex
^({|\[|"|true$|false$|null$)
```

--------------------------------

### Decode Strings

Source: https://github.com/wmertens/jsurl2/blob/master/_autodocs/USAGE-GUIDE.md

Convert encoded strings back into JavaScript objects.

```typescript
import { parse } from 'jsurl2'

const encoded = '(id~123~name~Alice~email~alice@example.com~active~~)~'
const user = parse<User>(encoded)
// Result: { id: 123, name: 'Alice', email: 'alice@example.com', active: true }
```
Tokens:
Raw