`persisted-queries` — APQ manifest support

(no submodules)

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

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:

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.

2.8 KiB Raw Blame History

persisted-queries — APQ manifest support