# `execute-helpers.ts`

## Purpose

Houses the smaller execution helpers the Yoga engine uses on every
request, kept out of `yoga-engine.ts` so the orchestrator file stays
beneath the 300-line hard limit. The helpers cover error masking,
wall-clock timeouts, the introspection-toggle guard, and the wrapper that
adapts GraphQL's `subscribe()` Promise into the engine's
`AsyncIterable<GraphqlResponse>` contract.

The helpers are deliberately pure — they hold no state across calls — so
the engine can compose them per-request without worrying about leakage
across concurrent requests.

## Features

- `maskOrPassthrough` — flips messages to "Unexpected error." when
  `maskedErrors` is on; preserves `path`.
- `withTimeout` — races a Promise against a `setTimeout`; clears the
  timer on either outcome.
- `assertIntrospectionAllowed` — regex-rejects `__schema` / `__type`
  references when the option is off.
- `wrapSubscription` — Promise-of-AsyncIterable to AsyncIterable.

## Usage: Basic

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

const result = await withTimeout(Promise.resolve("ok"), 5000);
```

## Usage: Advanced

```ts
import {
    assertIntrospectionAllowed,
    maskOrPassthrough,
} from "@suaveplan/api-graphql-yoga";
import { GraphQLError } from "graphql";

assertIntrospectionAllowed("{ ping }", { introspection: false } as never);
const masked = maskOrPassthrough(
    [new GraphQLError("internal db unreachable")],
    { maskedErrors: true } as never
);
```

## API Reference

- `maskOrPassthrough(errors, options)`.
- `withTimeout(p, timeoutMs)`.
- `assertIntrospectionAllowed(documentSource, options)`.
- `wrapSubscription(pending, onClose)`.

## Implementation Notes

The introspection guard uses a regex over the raw query text rather than
walking the AST — the goal is a fast pre-execution rejection. The regex
catches every legal way to reference `__schema` / `__type` because GraphQL
forbids those identifiers in any non-introspection context.