71 lines
2.4 KiB
Markdown
71 lines
2.4 KiB
Markdown
# `federation` — multi-plugin SDL merger
|
|
|
|
<!-- begin:auto-docs -->
|
|
_(no submodules)_
|
|
<!-- end:auto-docs -->
|
|
|
|
## Purpose
|
|
|
|
`federation` is the engine's facade over the canonical `mergeSdl`
|
|
function from `@suaveplan/api-graphql`. Apollo doesn't see federated
|
|
plugin contributions directly — the engine collects every plugin's
|
|
SDL via the abstract `GraphqlRegistry`, federates them through this
|
|
module, and feeds the merged SDL to `buildSchema()`. Collision
|
|
detection, namespace wrapping, and strict-mode policy come for free
|
|
because all three are owned by the abstract merger.
|
|
|
|
The module is intentionally a one-line passthrough; it exists so the
|
|
package surface signals "yes, Apollo federates the same way Yoga
|
|
does — `GRAPHQL.SCHEMA_COLLISION` is the canonical code on either
|
|
engine".
|
|
|
|
## Features
|
|
|
|
- 1:1 delegation to `@suaveplan/api-graphql.mergeSdl` — no shape
|
|
change, no behaviour change.
|
|
- Same collision semantics as Yoga — `GRAPHQL.SCHEMA_COLLISION` is
|
|
raised, NOT a `GRAPHQL_APOLLO.*` code.
|
|
- Strict-mode propagation — `strictNamespace: true` requires every
|
|
plugin to declare a `graphql.namespace`.
|
|
- Returns the canonical `MergedSchema` shape so engine internals stay
|
|
assignable to the abstract contract.
|
|
|
|
## Usage: Basic
|
|
|
|
```ts
|
|
import { federateForApollo } from "@suaveplan/api-graphql-apollo/federation";
|
|
|
|
const merged = federateForApollo([
|
|
{ plugin: "billing", typeDefs: ["type Query { invoice: String! }"] },
|
|
{ plugin: "users", typeDefs: ["extend type Query { me: String! }"] },
|
|
]);
|
|
console.log(merged.sdl);
|
|
```
|
|
|
|
## Usage: Advanced
|
|
|
|
Enable strict-mode federation across all plugins to enforce a
|
|
namespace contract before the host even compiles:
|
|
|
|
```ts
|
|
import { federateForApollo } from "@suaveplan/api-graphql-apollo/federation";
|
|
|
|
federateForApollo(contributions, { strictNamespace: true });
|
|
// → throws GRAPHQL.NAMESPACE_REQUIRED if any plugin omitted namespace
|
|
```
|
|
|
|
## API Reference
|
|
|
|
- `federateForApollo(contributions, options?): MergedSchema`
|
|
- delegates to `@suaveplan/api-graphql.mergeSdl`.
|
|
|
|
## Implementation Notes
|
|
|
|
The function exists primarily so the package's TypeScript exports
|
|
expose a `federateForApollo` symbol that mirrors the sibling
|
|
`federateForYoga` (when the Yoga adapter lands). The behavioural
|
|
contract is owned by the abstract `mergeSdl`. Tests verify that
|
|
`GRAPHQL.SCHEMA_COLLISION` and `GRAPHQL.NAMESPACE_REQUIRED` are raised
|
|
through this wrapper — concrete proof that Apollo and Yoga agree on
|
|
the federation contract.
|