Initial Commit

packages/api-stack/api/api-graphql-apollo/src/persisted-queries/persisted-queries.md

@@ -0,0 +1,74 @@
+# `persisted-queries` — APQ manifest support
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`persisted-queries` implements Apollo's persisted-query manifest lookup
+— the ability for clients to send `{ id }` in place of `{ query }` and
+have the engine resolve the id against a build-time-generated manifest.
+The feature is Apollo-specific (Yoga uses a different protocol variant)
+so the loader lives in this adapter and not in the abstract
+`api-graphql` core.
+
+The module exposes three entry points: a filesystem loader, an
+in-memory parser for callers that already have the JSON text, and a
+direct-from-entries factory for tests. Lookups against an unknown id
+raise `GRAPHQL_APOLLO.PERSISTED_QUERY_NOT_FOUND`; malformed input
+raises `GRAPHQL_APOLLO.PARSE_FAILED` so callers see a single
+configuration-failure code for any manifest shape error.
+
+## Features
+
+- File loader uses `node:fs/promises.readFile` — async-safe in the host
+  start-up sequence.
+- JSON parser validates the manifest is an object of `string → string`
+  before returning; non-string values raise `PARSE_FAILED`.
+- Direct factory accepts any `Iterable<[id, query]>` — useful in tests.
+- Manifest is frozen on construction; the only mutation surface is
+  `lookup(id)` (reads) and `has(id)` (existence check).
+- `entries` accessor returns the frozen map for callers that need to
+  diff manifests across deploys.
+
+## Usage: Basic
+
+```ts
+import { loadPersistedQueryManifest } from "@suaveplan/api-graphql-apollo/persisted-queries";
+
+const manifest = await loadPersistedQueryManifest("./pq.json");
+const query = manifest.lookup("abc123");
+```
+
+## Usage: Advanced
+
+Build a manifest from an in-process source (e.g. a KV-store fetch) and
+wire it into the engine for runtime lookup:
+
+```ts
+import { createApolloGraphqlEngine } from "@suaveplan/api-graphql-apollo";
+import { createPersistedQueryManifest } from "@suaveplan/api-graphql-apollo/persisted-queries";
+
+const entries = await kv.list("pq:");
+const manifest = createPersistedQueryManifest(
+    entries.map((e) => [e.key.slice(3), e.value as string])
+);
+const engine = createApolloGraphqlEngine({ persistedQueries: manifest });
+```
+
+## API Reference
+
+- `PersistedQueryManifest` — `{ entries, lookup, has }`.
+- `loadPersistedQueryManifest(path: string): Promise<PersistedQueryManifest>`
+- `parsePersistedQueryManifest(raw: string): PersistedQueryManifest`
+- `createPersistedQueryManifest(entries): PersistedQueryManifest`
+
+## Implementation Notes
+
+Manifest entries are stored in a `Map<string, string>` — O(1) lookup,
+deterministic iteration order. The `entries` field returns a new `Map`
+constructed from the underlying entries on every access so callers
+cannot mutate the live state. The loader maps every filesystem and JSON
+failure to `GRAPHQL_APOLLO.PARSE_FAILED` so wire-level diagnostics show
+a single code regardless of failure mode.