Skip to content

docs(composition): fix README inaccuracies for federateSubgraphs #2648

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
comatory merged 2 commits into from
Mar 18, 2026
Merged

docs(composition): fix README inaccuracies for federateSubgraphs #2648

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
086d71f
docs(composition): fix README inaccuracies for federateSubgraphs
comatory Mar 14, 2026
2fec27a
Merge branch 'main' into ondrej/fix-composition-readme
comatory Mar 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 24 additions & 18 deletions composition/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,6 @@ An example federation of two simple subgraphs:
import { federateSubgraphs, FederationResult, Subgraph } from '@wundergraph/composition';
import { parse } from 'graphql';

const result: FederationResult = federateSubgraphs([subgraphA, subgraphB]);

const subgraphA: Subgraph = {
name: 'subgraph-a',
url: 'http://localhost:4001',
Expand All @@ -48,39 +46,47 @@ const subgraphB: Subgraph = {
type Query {
users: [User!]!
}

type User @key(fields: "id") {
id: ID!
interests: [String!]!
}
`),
};

const result: FederationResult = federateSubgraphs({ subgraphs: [subgraphA, subgraphB] });
```

### FederationResult

The `federateSubgraphs` function returns `FederationResult`, which is a union of `FederationResultSuccess` and
`FederationResultFailure`. Both types in the union always define the following mutual properties:
The `federateSubgraphs` function returns `FederationResult`, which is a union of `FederationSuccess` and
`FederationFailure`. Both types in the union always define the following mutual properties:

| property | Description | type |
| -------- | -------------------------------------- | -------------- |
| success | assertion of composition success | boolean |
| warnings | array of composition warnings (if any) | Array<Warning> |

#### FederationResultSuccess
#### FederationSuccess

If federation was successful, the return type is `FederationResultSuccess`.
If federation was successful, the return type is `FederationSuccess`.

| property | Description | type |
| -------------------- | --------------------------------------------------------- | --------------------- |
| federatedGraphAST | an AST object representation of the federated graph sdl | graphql.DocumentNode |
| federatedGraphSchema | a schema object representation of the federated graph sdl | graphql.GraphQLSchema |
| success | assertion that composition was successful | true |
| warnings | array of composition warnings (if any) | Array<Warning> |
| property | Description | type |
| ------------------------------ | --------------------------------------------------------- | ------------------------------------ |
| directiveDefinitionByName | map of directive definitions by name | Map<string, DirectiveDefinitionNode> |
| fieldConfigurations | array of field configurations for the router | Array<FieldConfiguration> |
| federatedGraphAST | an AST object representation of the federated graph SDL | graphql.DocumentNode |
| federatedGraphClientSchema | a schema object with client-facing types only | graphql.GraphQLSchema |
| federatedGraphSchema | a schema object representation of the federated graph SDL | graphql.GraphQLSchema |
| parentDefinitionDataByTypeName | map of parent type definition data by type name | Map<string, ParentDefinitionData> |
| subgraphConfigBySubgraphName | map of normalized subgraph config by subgraph name | Map<string, SubgraphConfig> |
| shouldIncludeClientSchema | whether the client schema should be included (optional) | boolean \| undefined |
| success | assertion that composition was successful | true |
| warnings | array of composition warnings (if any) | Array<Warning> |

#### FederationResultFailure
#### FederationFailure

If federation was unsuccessful, the return type is `FederationResultFailure`.
If federation was unsuccessful, the return type is `FederationFailure`.

| property | Description | type |
| -------- | ------------------------------------------- | -------------- |
Expand All @@ -96,10 +102,10 @@ In these cases, the errors array will be defined and populated.
An example of a simple debugging framework might be:

```typescript
import { federateSubgraphs, FederationResult, Subgraph } from '@wundergraph.composition';
import { federateSubgraphs, FederationResult, Subgraph } from '@wundergraph/composition';
import { print, printSchema } from 'graphql';

const result: FederationResult = federateSubgraphs([subgraphA, subgraphB]);
const result: FederationResult = federateSubgraphs({ subgraphs: [subgraphA, subgraphB] });

if (result.success) {
// Both options to print the federated graph as a string are included for documentational purposes only
Expand All @@ -126,7 +132,7 @@ Errors can happen in three main stages:
(if this stage fails, federation will not be attempted)
3. During the federation process itself.

All errors will be appended to the `FederationResultFailure.errors` array.
All errors will be appended to the `FederationFailure.errors` array.

## Subgraph object

Expand Down
Loading