first commit

docs/api-stack/api/api-graphql-yoga/src/options/options.md

@@ -0,0 +1,73 @@
+# `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.