Move docs/ package mirror into document-navigator plugin
Relocate the ~6k-file docs tree from the repo root into plugins/document-navigator/docs/ so the plugin is self-contained and portable. docs/superpowers/ (specs and plans) stays at the repo root. Moved via cp+rm rather than git mv because directory rename() fails with EPERM on this WSL /mnt DrvFs mount; git rename-detection pairs the identical-content files at commit time. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,69 @@
|
||||
# @suaveplan/api-graphql-apollo — Apollo Server GraphQL engine adapter for the Suaveplan API plugin system. Implements the GraphqlEngine contract from @suaveplan/api-graphql and passes runGraphqlEngineConformance with the same invariants as the Yoga sibling. Adds Apollo-specific persisted-query manifest support, optional Apollo Studio usage reporting, depth + complexity guards, federated multi-plugin schema merging, per-request DataLoader scoping, engine-agnostic OTel instruments, and graphql-ws subscription bridging.
|
||||
|
||||
Stage-7 Apollo Server GraphQL engine adapter for the Suaveplan API
|
||||
plugin system. Implements the `GraphqlEngine` contract from
|
||||
`@suaveplan/api-graphql` and passes the conformance suite alongside
|
||||
the Yoga sibling — switching engines is a host-config change.
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
## Documentation tree
|
||||
|
||||
- [http](./src/endpoints/http.md) — `endpoints/http` mounts the two HTTP endpoints every GraphQL adapter must expose: `POST /graphql` for operation dispatc…
|
||||
- [ui-proxy](./src/endpoints/ui-proxy.md) — `endpoints/ui-proxy` mounts the `/graphql/ui` endpoint. The Apollo engine never embeds Apollo's landing page — UI is op…
|
||||
- [engine](./src/engine/apollo-engine.md) — `ApolloGraphqlEngine` is the concrete Apollo Server implementation of the `@suaveplan/api-graphql` engine contract. It…
|
||||
- [apollo-engine](./src/engine/apollo-engine.md) — `ApolloGraphqlEngine` is the concrete Apollo Server implementation of the `@suaveplan/api-graphql` engine contract. It…
|
||||
- [error-codes](./src/error-codes/error-codes.md) — `error-codes` defines the stable `GRAPHQL_APOLLO.*` namespace plus the `GraphqlApolloError` class consumed by every oth…
|
||||
- [error-codes](./src/error-codes/error-codes.md) — `error-codes` defines the stable `GRAPHQL_APOLLO.*` namespace plus the `GraphqlApolloError` class consumed by every oth…
|
||||
- [federation](./src/federation/federation.md) — `federation` is the engine's facade over the canonical `mergeSdl` function from `@suaveplan/api-graphql`. Apollo doesn'…
|
||||
- [federation](./src/federation/federation.md) — `federation` is the engine's facade over the canonical `mergeSdl` function from `@suaveplan/api-graphql`. Apollo doesn'…
|
||||
- [guards](./src/guards/depth-and-complexity.md) — `depth-and-complexity` walks a parsed `DocumentNode` and computes two coarse static metrics — the maximum selection-set…
|
||||
- [depth-and-complexity](./src/guards/depth-and-complexity.md) — `depth-and-complexity` walks a parsed `DocumentNode` and computes two coarse static metrics — the maximum selection-set…
|
||||
- [instruments](./src/instruments/instruments.md) — `instruments` owns the five OTel instrument names emitted by every GraphQL engine adapter in the foundation. Both `api-…
|
||||
- [instruments](./src/instruments/instruments.md) — `instruments` owns the five OTel instrument names emitted by every GraphQL engine adapter in the foundation. Both `api-…
|
||||
- [loaders](./src/loaders/loaders.md) — `loaders` defines the per-request DataLoader scope the engine creates around every incoming GraphQL operation. Two conc…
|
||||
- [loaders](./src/loaders/loaders.md) — `loaders` defines the per-request DataLoader scope the engine creates around every incoming GraphQL operation. Two conc…
|
||||
- [options](./src/options/options.md) — `options` owns the Zod-validated configuration surface accepted by `createApolloGraphqlEngine`. The schema mirrors the…
|
||||
- [options](./src/options/options.md) — `options` owns the Zod-validated configuration surface accepted by `createApolloGraphqlEngine`. The schema mirrors the…
|
||||
- [persisted-queries](./src/persisted-queries/persisted-queries.md) — `persisted-queries` implements Apollo's persisted-query manifest lookup — the ability for clients to send `{ id }` in p…
|
||||
- [persisted-queries](./src/persisted-queries/persisted-queries.md) — `persisted-queries` implements Apollo's persisted-query manifest lookup — the ability for clients to send `{ id }` in p…
|
||||
- [studio-reporting](./src/studio-reporting/studio-reporting.md) — `studio-reporting` materialises the configuration descriptor consumed by the engine when an operator opts in to Apollo…
|
||||
- [studio-reporting](./src/studio-reporting/studio-reporting.md) — `studio-reporting` materialises the configuration descriptor consumed by the engine when an operator opts in to Apollo…
|
||||
- [subscriptions](./src/subscriptions/subscriptions.md) — `subscriptions` runs a GraphQL subscription document against a wired schema, returning the `AsyncIterable<ExecutionResu…
|
||||
- [subscriptions](./src/subscriptions/subscriptions.md) — `subscriptions` runs a GraphQL subscription document against a wired schema, returning the `AsyncIterable<ExecutionResu…
|
||||
- [testing](./src/testing/conformance.md) — `testing/conformance` is the re-export of `runGraphqlEngineConformance` from `@suaveplan/api-graphql/testing`, pre-boun…
|
||||
- [conformance](./src/testing/conformance.md) — `testing/conformance` is the re-export of `runGraphqlEngineConformance` from `@suaveplan/api-graphql/testing`, pre-boun…
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## When to choose Apollo over Yoga
|
||||
|
||||
- You want Apollo Studio usage reporting (`studioReporting` option).
|
||||
- You ship persisted-query manifests built by Apollo's CLI / Rover.
|
||||
- Your team already runs Apollo's federation tooling in adjacent
|
||||
services.
|
||||
- You need Apollo's plugin ecosystem (cost analyser, request
|
||||
coalescer, custom cache plugin, …).
|
||||
|
||||
Otherwise, Yoga is the faster default — fewer allocations per request,
|
||||
slimmer dependency closure.
|
||||
|
||||
## Modules
|
||||
|
||||
- `engine` — `ApolloGraphqlEngine`, `createApolloGraphqlEngine`.
|
||||
- `options` — Zod-validated `ApolloGraphqlOptions` schema.
|
||||
- `error-codes` — `GRAPHQL_APOLLO.*` registry + `GraphqlApolloError`.
|
||||
- `instruments` — engine-agnostic `graphql.*` OTel surface.
|
||||
- `guards` — depth + complexity rejection helpers.
|
||||
- `persisted-queries` — APQ manifest loader.
|
||||
- `studio-reporting` — Apollo Studio descriptor bridge.
|
||||
- `subscriptions` — `graphql-ws` runner.
|
||||
- `loaders` — per-request DataLoader scope.
|
||||
- `federation` — `mergeSdl` passthrough.
|
||||
- `endpoints` — HTTP + UI proxy mounts.
|
||||
- `testing` — `runApolloConformance` re-export.
|
||||
|
||||
## Status
|
||||
|
||||
Original. Owned by the `api-stack` super-category.
|
||||
Passes the abstract conformance harness with the same invariants Yoga
|
||||
satisfies — see `src/engine/apollo-engine.spec-conformance.test.ts`.
|
||||
|
||||
Reference in New Issue
Block a user