first commit

docs/api-stack/api/api-graphql-yoga/src/engine/execute-helpers.md

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