<!-- source-hash: a2919980289087039fbf60e645f820e8 -->
Bidirectional converter for synchronizing URL parameters with GraphQL variables, providing type-safe conversion between flat URL params and nested GraphQL objects with support for arrays, type coercion, and validation.

## Key Components

- **`urlParamsToVariables`** - Converts URLSearchParams to GraphQL variables object with proper type coercion
- **`variablesToUrlParams`** - Flattens nested GraphQL variables to URL parameters, excluding defaults
- **`coerceValue`** - Type coercion for URL strings to JavaScript types (number, boolean, array)
- **`setNestedValue`** / **`getNestedValue`** - Utilities for accessing nested object properties via dot notation
- **`mergeVariables`** - Merges parameter updates into existing variables without losing data
- **`clearParams`** - Removes specific parameters from variables
- **`validateVariables`** - Validates variables against schema for required fields and type consistency

## Usage Example

```typescript
import { urlParamsToVariables, variablesToUrlParams } from './url-converter'

// Convert URL to GraphQL variables
const searchParams = new URLSearchParams('?search=error&severity=critical&severity=error&cursor=abc')
const schema = {
  search: { graphqlPath: 'search', type: 'string' as const },
  severity: { graphqlPath: 'filter.severity', type: 'array' as const },
  cursor: { graphqlPath: 'cursor', type: 'string' as const }
}

const variables = urlParamsToVariables(searchParams, schema)
// Result: { search: 'error', filter: { severity: ['critical', 'error'] }, cursor: 'abc' }

// Convert back to URL parameters
const urlParams = variablesToUrlParams(variables, schema)
console.log(urlParams.toString()) // "search=error&severity=critical&severity=error&cursor=abc"
```