Skip to content

Commit cae62e3

Browse files
yaacovCRyaacovCR
committed
docs: restore missing docs
- functions with overloads where the implementation was marked internal were previously being hidden entirely - also no longer hides methods available in deprecated subscription module when they are listed elsewhere
1 parent 35f1ff9 commit cae62e3

9 files changed

Lines changed: 4729 additions & 678 deletions

File tree

‎website/generate-api.js‎

Lines changed: 239 additions & 37 deletions
Large diffs are not rendered by default.

‎website/pages/api-v16/execution.mdx‎

Lines changed: 230 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -589,6 +589,8 @@ of calling that function while passing along args and context value.
589589
<p>
590590
<strong>Functions:</strong><br />
591591
<a href="/api-v16/execution#subscribe">subscribe()</a>
592+
<span aria-hidden="true">&middot;</span>
593+
<a href="/api-v16/execution#createsourceeventstream">createSourceEventStream()</a>
592594
</p>
593595
</div>
594596

@@ -785,6 +787,234 @@ assert('errors' in result);
785787
result.errors[0].message; // => 'Schema is not configured to execute subscription operation.'
786788
```
787789

790+
<hr className="api-item-divider" />
791+
792+
#### createSourceEventStream()
793+
794+
<hr className="api-subsection-divider" />
795+
796+
<div className="api-subsection-title">Overload 1</div>
797+
798+
Implements the "CreateSourceEventStream" algorithm described in the
799+
GraphQL specification, resolving the subscription source event stream.
800+
801+
Returns a Promise that resolves to either an AsyncIterable (if successful)
802+
or an ExecutionResult (error). The promise will be rejected if the schema or
803+
other arguments to this function are invalid, or if the resolved event stream
804+
is not an async iterable.
805+
806+
If the client-provided arguments to this function do not result in a
807+
compliant subscription, a GraphQL Response (ExecutionResult) with
808+
descriptive errors and no data will be returned.
809+
810+
If the source stream could not be created due to faulty subscription
811+
resolver logic or underlying systems, the promise will resolve to a single
812+
ExecutionResult containing `errors` and no `data`.
813+
814+
If the operation succeeded, the promise resolves to the AsyncIterable for the
815+
event stream returned by the resolver.
816+
817+
A Source Event Stream represents a sequence of events, each of which triggers
818+
a GraphQL execution for that event.
819+
820+
This may be useful when hosting the stateful subscription service in a
821+
different process or machine than the stateless GraphQL execution engine,
822+
or otherwise separating these two steps. For more on this, see the
823+
"Supporting Subscriptions at Scale" information in the GraphQL specification.
824+
825+
**Signature:**
826+
827+
<ApiSignature parts={[["name", "createSourceEventStream"], "(\n ", ["parameter", "args"], ": ", ["link", "ExecutionArgs", "/api-v16/execution#executionargs"], ",\n): ", ["type", "Promise"], "\u003c\n ", ["link", "ExecutionResult", "/api-v16/execution#executionresult"], " \u007c ", ["type", "AsyncIterable"], "\u003c", ["keyword", "unknown"], ", ", ["keyword", "any"], ", ", ["keyword", "any"], "\u003e\n\u003e;"]} />
828+
829+
<hr className="api-subsection-divider" />
830+
831+
<div className="api-subsection-title">Arguments</div>
832+
833+
<table>
834+
<thead>
835+
<tr>
836+
<th>Name</th>
837+
<th>Type</th>
838+
<th>Description</th>
839+
</tr>
840+
</thead>
841+
<tbody>
842+
<tr>
843+
<td>args</td>
844+
<td><ApiType parts={[["link", "ExecutionArgs", "/api-v16/execution#executionargs"]]} /></td>
845+
<td>The arguments used to perform the operation.</td>
846+
</tr>
847+
</tbody>
848+
</table>
849+
850+
<hr className="api-subsection-divider" />
851+
852+
<div className="api-subsection-title">Returns</div>
853+
854+
<table>
855+
<thead>
856+
<tr>
857+
<th>Type</th>
858+
<th>Description</th>
859+
</tr>
860+
</thead>
861+
<tbody>
862+
<tr>
863+
<td><ApiType parts={[["type", "Promise"], "\u003c\n ", ["link", "ExecutionResult", "/api-v16/execution#executionresult"], " \u007c ", ["type", "AsyncIterable"], "\u003c", ["keyword", "unknown"], ", ", ["keyword", "any"], ", ", ["keyword", "any"], "\u003e\n\u003e"]} /></td>
864+
<td>The source event stream, or an execution result containing subscription errors.</td>
865+
</tr>
866+
</tbody>
867+
</table>
868+
869+
<hr className="api-subsection-divider" />
870+
871+
<div className="api-subsection-title">Example</div>
872+
873+
```ts
874+
import { parse } from 'graphql/language';
875+
import { buildSchema } from 'graphql/utilities';
876+
import { createSourceEventStream } from 'graphql/execution';
877+
878+
async function* greetings() {
879+
yield { greeting: 'Hello' };
880+
}
881+
882+
const schema = buildSchema(`
883+
type Query {
884+
noop: String
885+
}
886+
887+
type Subscription {
888+
greeting: String
889+
}
890+
`);
891+
892+
const stream = await createSourceEventStream({
893+
schema,
894+
document: parse('subscription { greeting }'),
895+
rootValue: { greeting: () => greetings() },
896+
});
897+
898+
Symbol.asyncIterator in stream; // => true
899+
```
900+
901+
<hr className="api-subsection-divider" />
902+
903+
<div className="api-subsection-title">Overload 2 <span aria-label="Deprecated" className="api-tag" title="Deprecated"></span></div>
904+
905+
Creates the source event stream for a subscription operation using the legacy
906+
positional argument overload. This deprecated overload will be removed in the
907+
next major version; use the args object overload instead.
908+
909+
**Signature:**
910+
911+
<ApiSignature parts={[["name", "createSourceEventStream"], "(\n ", ["parameter", "schema"], ": ", ["link", "GraphQLSchema", "/api-v16/type#graphqlschema"], ",\n ", ["parameter", "document"], ": ", ["link", "DocumentNode", "/api-v16/language#documentnode"], ",\n ", ["parameter", "rootValue"], "?: ", ["keyword", "unknown"], ",\n ", ["parameter", "contextValue"], "?: ", ["keyword", "unknown"], ",\n ", ["parameter", "variableValues"], "?: ", ["type", "Maybe"], "\u003c\u007b\n ", ["keyword", "readonly"], " [", ["parameter", "variable"], ": ", ["keyword", "string"], "]: ", ["keyword", "unknown"], ";\n \u007d\u003e,\n ", ["parameter", "operationName"], "?: ", ["type", "Maybe"], "\u003c", ["keyword", "string"], "\u003e,\n ", ["parameter", "subscribeFieldResolver"], "?: ", ["type", "Maybe"], "\u003c", ["link", "GraphQLFieldResolver", "/api-v16/type#graphqlfieldresolver"], "\u003c", ["keyword", "any"], ", ", ["keyword", "any"], "\u003e\u003e,\n): ", ["type", "Promise"], "\u003c\n ", ["link", "ExecutionResult", "/api-v16/execution#executionresult"], " \u007c ", ["type", "AsyncIterable"], "\u003c", ["keyword", "unknown"], ", ", ["keyword", "any"], ", ", ["keyword", "any"], "\u003e\n\u003e;"]} />
912+
913+
<hr className="api-subsection-divider" />
914+
915+
<div className="api-subsection-title">Arguments</div>
916+
917+
<table>
918+
<thead>
919+
<tr>
920+
<th>Name</th>
921+
<th>Type</th>
922+
<th>Description</th>
923+
</tr>
924+
</thead>
925+
<tbody>
926+
<tr>
927+
<td>schema</td>
928+
<td><ApiType parts={[["link", "GraphQLSchema", "/api-v16/type#graphqlschema"]]} /></td>
929+
<td>GraphQL schema to use.</td>
930+
</tr>
931+
<tr>
932+
<td>document</td>
933+
<td><ApiType parts={[["link", "DocumentNode", "/api-v16/language#documentnode"]]} /></td>
934+
<td>The parsed GraphQL document containing the subscription<br />
935+
operation.</td>
936+
</tr>
937+
<tr>
938+
<td>rootValue?</td>
939+
<td><ApiType parts={[["keyword", "unknown"]]} /></td>
940+
<td>Initial root value passed to the subscription resolver.</td>
941+
</tr>
942+
<tr>
943+
<td>contextValue?</td>
944+
<td><ApiType parts={[["keyword", "unknown"]]} /></td>
945+
<td>Application context value passed to resolvers.</td>
946+
</tr>
947+
<tr>
948+
<td>variableValues?</td>
949+
<td><ApiType parts={[["type", "Maybe"], "\u003c\u007b\n ", ["keyword", "readonly"], " [", ["parameter", "variable"], ": ", ["keyword", "string"], "]: ", ["keyword", "unknown"], ";\n\u007d\u003e"]} /></td>
950+
<td>Runtime variable values keyed by variable name.</td>
951+
</tr>
952+
<tr>
953+
<td>operationName?</td>
954+
<td><ApiType parts={[["type", "Maybe"], "\u003c", ["keyword", "string"], "\u003e"]} /></td>
955+
<td>Name of the subscription operation to execute when<br />
956+
the document contains multiple operations.</td>
957+
</tr>
958+
<tr>
959+
<td>subscribeFieldResolver?</td>
960+
<td><ApiType parts={[["type", "Maybe"], "\u003c", ["link", "GraphQLFieldResolver", "/api-v16/type#graphqlfieldresolver"], "\u003c", ["keyword", "any"], ", ", ["keyword", "any"], "\u003e\u003e"]} /></td>
961+
<td>Resolver used for the root subscription<br />
962+
field.</td>
963+
</tr>
964+
</tbody>
965+
</table>
966+
967+
<hr className="api-subsection-divider" />
968+
969+
<div className="api-subsection-title">Returns</div>
970+
971+
<table>
972+
<thead>
973+
<tr>
974+
<th>Type</th>
975+
<th>Description</th>
976+
</tr>
977+
</thead>
978+
<tbody>
979+
<tr>
980+
<td><ApiType parts={[["type", "Promise"], "\u003c\n ", ["link", "ExecutionResult", "/api-v16/execution#executionresult"], " \u007c ", ["type", "AsyncIterable"], "\u003c", ["keyword", "unknown"], ", ", ["keyword", "any"], ", ", ["keyword", "any"], "\u003e\n\u003e"]} /></td>
981+
<td>The source event stream, or an execution result containing<br />
982+
subscription errors.</td>
983+
</tr>
984+
</tbody>
985+
</table>
986+
987+
<hr className="api-subsection-divider" />
988+
989+
<div className="api-subsection-title">Example</div>
990+
991+
```ts
992+
import { parse } from 'graphql/language';
993+
import { buildSchema } from 'graphql/utilities';
994+
import { createSourceEventStream } from 'graphql/execution';
995+
996+
async function* greetings() {
997+
yield { greeting: 'Hello' };
998+
}
999+
1000+
const schema = buildSchema(`
1001+
type Query {
1002+
noop: String
1003+
}
1004+
1005+
type Subscription {
1006+
greeting: String
1007+
}
1008+
`);
1009+
const document = parse('subscription { greeting }');
1010+
1011+
const stream = await createSourceEventStream(schema, document, {
1012+
greeting: () => greetings(),
1013+
});
1014+
1015+
Symbol.asyncIterator in stream; // => true
1016+
```
1017+
7881018
## Category: Values
7891019

7901020
<div className="api-category-toc">

0 commit comments

Comments
 (0)