<!-- source-hash: f6f23c54f1dcd6f13c1c04a935fe719d -->
Utilities for flattening nested GraphQL input type schemas into flat URL parameter mappings, enabling clean URL state management for GraphQL-powered views.

## Key Components

### Interfaces

- **`FlattenedParam`** — Describes a single URL parameter, including its `urlParamName`, `graphqlPath` (e.g., `filter.severity`), `type`, `defaultValue`, `required`, and `isArray` flags.

### Functions

| Function | Description |
|---|---|
| `flattenQueryVariables` | Async. Converts nested GraphQL query variables into a flat `Record<string, FlattenedParam>`. Uses introspection to expand input object fields. |
| `mergeDefaults` | Merges a defaults map into an existing flattened schema, overriding or populating `defaultValue` per param. |
| `validateSchema` | Throws if any two params resolve to the same `urlParamName` (conflict detection). |
| `getArrayParams` | Returns keys of all array-typed params; useful for repeated URL value handling (e.g., `?severity=error&severity=warning`). |
| `getRequiredParams` | Returns keys of all required params. |
| `shouldIncludeInUrl` | Returns `false` for `null`/`undefined`, empty arrays, empty strings, or values matching `defaultValue`; keeps URLs clean. |

## Usage Example

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

const introspector = new GraphQLIntrospector(/* ... */)
await introspector.load()

const queryVariables = {
  search: { type: 'string', required: false, isArray: false },
  filter: { type: 'object', graphqlTypeName: 'LogFilterInput', required: false, isArray: false },
}

// Flatten: { filter: { severity } } → ?severity=...
let schema = await flattenQueryVariables(queryVariables, introspector)

// Apply defaults
schema = mergeDefaults(schema, { severity: ['info'] })

// Validate no URL param name conflicts
validateSchema(schema)

// Check if a value should be written to the URL
const include = shouldIncludeInUrl(['critical'], schema.severity) // true
const skip = shouldIncludeInUrl([], schema.severity)             // false
```

## Source

[`flatten-schema.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/flatten-schema.ts)