# `options.ts`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

Defines `YogaGraphqlOptions`, the Zod-validated configuration boundary that
hosts use to wire `createYogaGraphqlEngine`. Hosts pass a partial bag at the
public surface; `resolveYogaGraphqlOptions` validates the input through a
strict Zod schema and fills in every default so internal code receives a
fully concrete `ResolvedYogaGraphqlOptions`.

The schema covers endpoint routes (`/graphql`, `/graphql/sdl`,
`/graphql/ws`, `/graphql/ui`), the masked-errors and landing-page toggles,
introspection on/off, depth + complexity guard limits, the parser-cache
size, the per-request `timeoutMs`, and the strict-namespace federation
flag.

## Features

- Single source of truth for every Yoga adapter default.
- Boundary input typed as `YogaGraphqlOptions = z.input<...>` so callers
  may pass numbers as numbers (not strings) — no coercion magic.
- Resolved shape is `readonly` and `Object.freeze`d so downstream code
  cannot mutate it by accident.

## Usage: Basic

```ts
import { resolveYogaGraphqlOptions } from "@suaveplan/api-graphql-yoga/options";

const opts = resolveYogaGraphqlOptions({});
// opts.endpoint === "/graphql"
// opts.maxQueryDepth === 10
// opts.maxQueryComplexity === 1000
```

## Usage: Advanced

```ts
import { resolveYogaGraphqlOptions } from "@suaveplan/api-graphql-yoga/options";

const opts = resolveYogaGraphqlOptions({
    endpoint: "/api/graphql",
    sdlEndpoint: "/api/graphql/sdl",
    wsEndpoint: "/api/graphql/ws",
    uiEndpoint: "/api/graphql/ui",
    maxQueryDepth: 8,
    maxQueryComplexity: 250,
    maskedErrors: false,
    introspection: false,
});
```

## API Reference

- `yogaGraphqlOptionsSchema` — the underlying Zod schema, exposed for
  composition into broader host config layers.
- `YogaGraphqlOptions` — input type alias.
- `ResolvedYogaGraphqlOptions` — frozen post-resolution type.
- `YOGA_GRAPHQL_DEFAULTS` — the `ResolvedYogaGraphqlOptions` defaults bag.
- `resolveYogaGraphqlOptions(input?)` — validate + default; throws
  `ZodError` on invalid input.

## Implementation Notes

Each endpoint path must start with `/` (enforced by `startsWith("/")`); the
guard prevents a host from accidentally registering a relative path that
would never match. `maxQueryDepth` and `maxQueryComplexity` are
`.positive()` because zero or negative limits would reject every query —
intent-preserving defaults beat foot-gun acceptance.