<!-- source-hash: 35adb97eaacf2c17d09efbd85a569c46 -->
Provides utilities to flatten nested GraphQL input types into URL parameter mappings for cleaner URL state management. Converts complex nested objects like `{ filter: { severity: [...] } }` into simple URL parameters like `?severity=...`.

## Key Components

**Main Functions:**
- `flattenQueryVariables()` - Core function that flattens GraphQL variables using schema introspection
- `mergeDefaults()` - Merges default values into the flattened schema
- `validateSchema()` - Ensures no URL parameter name conflicts exist
- `getArrayParams()` - Identifies which parameters should use repeated URL values
- `getRequiredParams()` - Lists required parameters from the schema
- `shouldIncludeInUrl()` - Determines if a parameter value should be included in the URL

**Types:**
- `FlattenedParam` - Configuration mapping URL parameter names to GraphQL paths with type information

## Usage Example

```typescript
import { flattenQueryVariables, validateSchema } from './flatten-schema'
import { GraphQLIntrospector } from './introspection'

// GraphQL query variables
const queryVars = {
  search: { type: 'string', required: false },
  filter: { type: 'object', graphqlTypeName: 'LogFilterInput' },
  cursor: { type: 'string', required: false }
}

// Flatten to URL parameter schema
const introspector = new GraphQLIntrospector(schema)
const flatSchema = await flattenQueryVariables(queryVars, introspector)

// Result maps nested filter fields to top-level URL params
// flatSchema = {
//   search: { urlParamName: 'search', graphqlPath: 'search', type: 'string' },
//   severity: { urlParamName: 'severity', graphqlPath: 'filter.severity', type: 'array' },
//   toolType: { urlParamName: 'toolType', graphqlPath: 'filter.toolType', type: 'array' }
// }

validateSchema(flatSchema) // Ensure no conflicts
const arrayParams = getArrayParams(flatSchema) // ['severity', 'toolType']
```