@alxia/graphql 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Steve Tsala
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,117 @@
1
+ # @alxia/graphql
2
+
3
+ GraphQL for [alxia](https://www.npmjs.com/package/@alxia/core), served by
4
+ [GraphQL Yoga](https://the-guild.dev/graphql/yoga-server). The endpoint is a
5
+ route like any other: behind the app's hooks, guarded by its guards, its
6
+ resolvers reading the context those hooks built — typed, and checked.
7
+ Yoga's plugin system is yours whole: Envelop's plugins and Yoga's own.
8
+
9
+ ```sh
10
+ bun add @alxia/graphql graphql-yoga graphql @alxia/core
11
+ bun add -d typescript
12
+ ```
13
+
14
+ `graphql-yoga` and `graphql` are peers: the package declares no dependency.
15
+ `graphql` 16 and 17 both work; with 17, `graphql-yoga` must be 5.22 or
16
+ later, the first to accept it.
17
+
18
+ ## Usage
19
+
20
+ ```ts
21
+ import { alxia } from '@alxia/core';
22
+ import { graphql, type GraphQLContext } from '@alxia/graphql';
23
+ import { bearer } from '@alxia/jwt';
24
+ import { createSchema } from 'graphql-yoga';
25
+
26
+ const base = alxia()
27
+ .decorate({ db })
28
+ .use(bearer({ jwt, schema: Claims })); // every route after it needs a token
29
+
30
+ const schema = createSchema<GraphQLContext<typeof base>>({
31
+ typeDefs: /* GraphQL */ `type Query { me: String! }`,
32
+ resolvers: {
33
+ Query: { me: (_, __, { user, db }) => db.name(user.sub) }, // user and db typed
34
+ },
35
+ });
36
+
37
+ const app = base.use((app) => graphql(app, { schema })); // POST and GET /graphql
38
+ app.listen(3000);
39
+ ```
40
+
41
+ `graphql(app, options)` adds `GET` and `POST` routes at `path` —
42
+ `/graphql` by default, under the app's prefix — and returns the app. Given
43
+ to `use` as a function, it stays in the chain and sees the app's type.
44
+
45
+ ## The context
46
+
47
+ A resolver's context is Yoga's (`request`, `params`), the app's — every
48
+ `decorate`, every `derive`, every plugin's: `user`, `db`, `log`,
49
+ `requestId` — and `set`, through which it sets a header or a cookie:
50
+
51
+ ```ts
52
+ login: async (_, { name }, { set }) => {
53
+ set.cookies.set('session', await sign(name), { httpOnly: true });
54
+ return true;
55
+ },
56
+ ```
57
+
58
+ `GraphQLContext<typeof app>` is that type. A schema whose resolvers read
59
+ what the app does not build is a compile error:
60
+
61
+ ```
62
+ the schema's resolvers read a context the app does not build: missing user
63
+ ```
64
+
65
+ ## Yoga's plugins
66
+
67
+ Every Yoga option passes through, but `graphqlEndpoint`, which `path`
68
+ sets, and `graphiql`, which `ide` decides:
69
+
70
+ ```ts
71
+ import { useDepthLimit } from '@envelop/depth-limit';
72
+ import { useResponseCache } from '@graphql-yoga/plugin-response-cache';
73
+
74
+ graphql(app, {
75
+ schema,
76
+ plugins: [useDepthLimit({ maxDepth: 8 }), useResponseCache({ session: ({ request }) => ... })],
77
+ maskedErrors: true, // Yoga's default: an error's message never leaks
78
+ ide: process.env.NODE_ENV === 'production' ? false : 'apollo-sandbox',
79
+ batching: true,
80
+ });
81
+ ```
82
+
83
+ - **Subscriptions** are served over server-sent events, Yoga's default:
84
+ `async *subscribe` in a resolver, `Accept: text/event-stream` on the
85
+ request. `@alxia/compress` leaves an event stream alone by default.
86
+ - **An IDE** answers a `GET` from a browser at the endpoint, with a
87
+ `Content-Security-Policy` that lets it load — `@alxia/secure-headers`
88
+ keeps it. `ide` chooses which:
89
+
90
+ ```ts
91
+ graphql(app, { schema, ide: 'apollo-sandbox', sandbox: { initialDocument: '{ me }' } });
92
+ graphql(app, { schema, ide: Bun.env.NODE_ENV === 'production' ? false : 'graphiql' });
93
+ ```
94
+
95
+ | `ide` | |
96
+ | --- | --- |
97
+ | `'graphiql'` (default) | Yoga's GraphiQL; `graphiql` takes its options |
98
+ | `'apollo-sandbox'` | [Apollo Sandbox](https://www.apollographql.com/docs/graphos/platform/sandbox), embedded, pointed at the address the page was opened at, prefix included — `https` behind a proxy that terminates TLS ([IDE guide](https://github.com/softistx/alxia/blob/develop/packages/graphql/docs/guide/ide.md#apollo-sandbox)). `sandbox` takes `title`, `initialDocument`, `initialHeaders`, `pollForSchemaUpdates`, `includeCookies` |
99
+ | `false` | none |
100
+ - **CORS** is `@alxia/cors`'s for the whole app: Yoga's own is off unless
101
+ `cors` is given.
102
+
103
+ ## API
104
+
105
+ | export | |
106
+ | --- | --- |
107
+ | `graphql(app, options)` | the endpoint: `schema`, `path`, `ide`, `sandbox`, and every Yoga option |
108
+ | `renderSandbox(endpoint, options?)`, `SANDBOX_POLICY` | the Sandbox page, and the policy it loads under |
109
+ | `SandboxOptions` | its options: `title`, `initialDocument`, `initialHeaders`, `pollForSchemaUpdates`, `includeCookies` |
110
+ | `GraphQLContext<App, UserContext?>` | what a resolver reads |
111
+ | `ServerContext<Ctx>`, `GraphQLOptions`, `GraphQLRoutes` | its types |
112
+
113
+ ## Documentation
114
+
115
+ - [Guide](https://github.com/softistx/alxia/tree/develop/packages/graphql/docs): a page per area — mounting the endpoint, the typed context, Yoga's plugins and options, and GraphiQL and Apollo Sandbox.
116
+ - [Troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/graphql/docs/troubleshooting.md): an error message, and what to do about it.
117
+ - [Roadmap](https://github.com/softistx/alxia/blob/develop/packages/graphql/docs/roadmap.md): what is coming, and what is not planned.
@@ -0,0 +1,78 @@
1
+ import type { Alxia, AnyReply, BaseContext, Empty, JoinPath, Reply, RouteEntryOf, RoutePath, StatusCode } from '@alxia/core';
2
+ import type { GraphQLSchemaWithContext, YogaInitialContext, YogaServerOptions } from 'graphql-yoga';
3
+ import { type YogaContext } from './handler';
4
+ import type { SandboxOptions } from './sandbox';
5
+ /** The parts of a route's context Yoga owns, or that mean nothing to a resolver. */
6
+ type RouteOnly = 'params' | 'query' | 'headers' | 'cookies' | 'body' | 'reply' | 'redirect';
7
+ /**
8
+ * What alxia hands Yoga for each request: the context its hooks built —
9
+ * `user`, `db`, `log`… — with `request`, `url`, `ip` and `set`, through
10
+ * which a resolver sets a cookie or a header on the response.
11
+ */
12
+ export type ServerContext<Ctx> = Omit<BaseContext & Ctx, RouteOnly>;
13
+ /**
14
+ * What a resolver reads as its context: Yoga's own, the app's, and what
15
+ * the `context` option adds. Type a schema with it:
16
+ *
17
+ * ```ts
18
+ * const base = alxia().use(bearer({ jwt }));
19
+ * const schema = createSchema<GraphQLContext<typeof base>>({ ... });
20
+ * ```
21
+ */
22
+ export type GraphQLContext<App, UserContext = Empty> = App extends {
23
+ readonly '~context': infer Ctx;
24
+ } ? YogaInitialContext & ServerContext<Ctx> & UserContext : {
25
+ readonly '~error': 'GraphQLContext needs the type of an app: GraphQLContext<typeof app>';
26
+ };
27
+ export interface GraphQLOptions<ServerCtx extends YogaContext, UserCtx extends YogaContext, Path extends RoutePath, SchemaCtx = unknown> extends Omit<YogaServerOptions<ServerCtx, UserCtx>, 'graphqlEndpoint' | 'cors' | 'schema' | 'graphiql'> {
28
+ /**
29
+ * What a browser gets at the endpoint: Yoga's GraphiQL, Apollo Sandbox,
30
+ * or nothing. GraphiQL by default; turn both off in production.
31
+ */
32
+ readonly ide?: 'graphiql' | 'apollo-sandbox' | false;
33
+ /** GraphiQL's options, Yoga's own, when `ide` is `graphiql`. */
34
+ readonly graphiql?: Exclude<YogaServerOptions<ServerCtx, UserCtx>['graphiql'], boolean>;
35
+ /** Apollo Sandbox's options, when `ide` is `apollo-sandbox`. */
36
+ readonly sandbox?: SandboxOptions;
37
+ /**
38
+ * The schema, from Yoga's `createSchema`, Pothos, or any tool that types
39
+ * its context. Its context must be one the app builds: a resolver that
40
+ * reads `user` behind no hook that derives one is a compile error.
41
+ */
42
+ readonly schema: GraphQLSchemaWithContext<SchemaCtx>;
43
+ /** Where the endpoint is, under the app's prefix. `/graphql` by default. */
44
+ readonly path?: Path;
45
+ /**
46
+ * Yoga's own CORS. Off by default: `@alxia/cors` answers for the whole
47
+ * app, this endpoint included.
48
+ */
49
+ readonly cors?: YogaServerOptions<ServerCtx, UserCtx>['cors'];
50
+ }
51
+ /**
52
+ * The check Yoga's types leave out: the context the app builds must hold
53
+ * what the schema's resolvers read. A mistake comes back as a `schema`
54
+ * whose type is the message.
55
+ */
56
+ type ProvidesContext<Provided, Required> = Provided extends Required ? unknown : {
57
+ readonly schema: `the schema's resolvers read a context the app does not build: missing ${Exclude<keyof Required, keyof Provided> & string}`;
58
+ };
59
+ /** What the endpoint answers, as alxia's client sees it: a body to read as GraphQL. */
60
+ type GraphQLReply = Reply<StatusCode, ReadableStream<Uint8Array> | undefined>;
61
+ export type GraphQLRoutes<Path extends string, Shortcuts extends AnyReply> = RouteEntryOf<'GET', Path, Empty, GraphQLReply, Shortcuts> & RouteEntryOf<'POST', Path, Empty, GraphQLReply, Shortcuts>;
62
+ /**
63
+ * A GraphQL endpoint on `app`, served by [GraphQL Yoga](https://the-guild.dev/graphql/yoga-server):
64
+ * `GET` and `POST` at `path`, behind every hook declared on `app` before it.
65
+ * A guard before it guards it; what the hooks derived is in each
66
+ * resolver's context, typed. Yoga's options pass through — `plugins`
67
+ * (Envelop's and Yoga's), `graphiql`, `maskedErrors`, `batching`… —
68
+ * and subscriptions are served over server-sent events.
69
+ *
70
+ * ```ts
71
+ * const app = alxia()
72
+ * .use(bearer({ jwt }))
73
+ * .use((app) => graphql(app, { schema, plugins: [useDepthLimit()] }));
74
+ * ```
75
+ */
76
+ export declare function graphql<Ctx extends object, Routes extends object, Prefix extends string, Shortcuts extends AnyReply, SchemaCtx, UserCtx extends YogaContext = Empty, const Path extends RoutePath = '/graphql'>(app: Alxia<Ctx, Routes, Prefix, Shortcuts>, options: GraphQLOptions<ServerContext<Ctx>, UserCtx, Path, SchemaCtx> & ProvidesContext<YogaInitialContext & ServerContext<Ctx> & UserCtx, SchemaCtx>): Alxia<Ctx, Routes & GraphQLRoutes<JoinPath<Prefix, Path>, Shortcuts>, Prefix, Shortcuts>;
77
+ export {};
78
+ //# sourceMappingURL=graphql.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"graphql.d.ts","sourceRoot":"","sources":["../src/graphql.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,22 @@
1
+ /**
2
+ * The endpoint behind `graphql()`: one Yoga per path it is served at, and
3
+ * the route handler that hands each request to it.
4
+ */
5
+ import type { BaseContext, StatusCode } from '@alxia/core';
6
+ import { type YogaServerInstance, type YogaServerOptions } from 'graphql-yoga';
7
+ import { type SandboxOptions } from './sandbox';
8
+ export type YogaContext = Record<string, any>;
9
+ /**
10
+ * The Yoga serving `endpoint`, created on first use. One per path: a plugin
11
+ * mounted under a prefix serves the same routes at a longer path, and
12
+ * GraphiQL must ask that one.
13
+ */
14
+ export declare function yogaServers<UserCtx extends YogaContext>(options: Omit<YogaServerOptions<YogaContext, UserCtx>, 'graphqlEndpoint'>): (endpoint: string) => YogaServerInstance<YogaContext, UserCtx>;
15
+ /**
16
+ * The handler of the endpoint's `GET` and `POST`: Apollo Sandbox's page to
17
+ * a browser when `sandbox` is not `false`, else the request to Yoga, with
18
+ * the route's context — the hooks' work, minus what a resolver has no use
19
+ * for — as Yoga's server context.
20
+ */
21
+ export declare function graphqlHandler<UserCtx extends YogaContext>(yogaAt: (endpoint: string) => YogaServerInstance<YogaContext, UserCtx>, sandbox: SandboxOptions | false): (ctx: Record<string, unknown> & BaseContext) => Promise<import("@alxia/core").Reply<200, string> | import("@alxia/core").Reply<StatusCode, ReadableStream<Uint8Array<ArrayBuffer>>>>;
22
+ //# sourceMappingURL=handler.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EAEN,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAiC,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAE/E,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAgB9C;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,SAAS,WAAW,EACtD,OAAO,EAAE,IAAI,CAAC,iBAAiB,CAAC,WAAW,EAAE,OAAO,CAAC,EAAE,iBAAiB,CAAC,GACvE,CAAC,QAAQ,EAAE,MAAM,KAAK,kBAAkB,CAAC,WAAW,EAAE,OAAO,CAAC,CAahE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,SAAS,WAAW,EACzD,MAAM,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,kBAAkB,CAAC,WAAW,EAAE,OAAO,CAAC,EACtE,OAAO,EAAE,cAAc,GAAG,KAAK,IAEjB,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,0IAsCxD"}
@@ -0,0 +1,3 @@
1
+ export { type GraphQLContext, type GraphQLOptions, type GraphQLRoutes, graphql, type ServerContext, } from './graphql';
2
+ export { renderSandbox, SANDBOX_POLICY, type SandboxOptions } from './sandbox';
3
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,OAAO,EACP,KAAK,aAAa,GAClB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC"}
package/dist/index.js ADDED
@@ -0,0 +1,139 @@
1
+ // src/handler.ts
2
+ import {
3
+ createYoga
4
+ } from "graphql-yoga";
5
+
6
+ // src/sandbox.ts
7
+ var SANDBOX_POLICY = [
8
+ "default-src 'self'",
9
+ "script-src 'self' 'unsafe-inline' https://embeddable-sandbox.cdn.apollographql.com",
10
+ "style-src 'self' 'unsafe-inline'",
11
+ "frame-src https://sandbox.embed.apollographql.com",
12
+ "img-src 'self' data: https:",
13
+ "connect-src 'self'"
14
+ ].join("; ");
15
+ function renderSandbox(endpoint, options = {}) {
16
+ const config = {
17
+ target: "#sandbox",
18
+ initialEndpoint: endpoint,
19
+ initialState: {
20
+ includeCookies: options.includeCookies ?? true,
21
+ pollForSchemaUpdates: options.pollForSchemaUpdates ?? true,
22
+ ...options.initialDocument === undefined ? {} : { document: options.initialDocument },
23
+ ...options.initialHeaders === undefined ? {} : { headers: options.initialHeaders }
24
+ },
25
+ hideCookieToggle: false,
26
+ endpointIsEditable: false
27
+ };
28
+ return `<!doctype html>
29
+ <html lang="en">
30
+ <head>
31
+ <meta charset="utf-8" />
32
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
33
+ <title>${html(options.title ?? "Sandbox Explorer")}</title>
34
+ <style>html, body { margin: 0; height: 100%; } #sandbox { position: absolute; inset: 0; }</style>
35
+ </head>
36
+ <body>
37
+ <div id="sandbox"></div>
38
+ <script src="https://embeddable-sandbox.cdn.apollographql.com/_latest/embeddable-sandbox.umd.production.min.js"></script>
39
+ <script>
40
+ {
41
+ const config = ${script(config)};
42
+ config.initialEndpoint = new URL(config.initialEndpoint, location.href).href;
43
+ new window.EmbeddedSandbox(config);
44
+ }
45
+ </script>
46
+ </body>
47
+ </html>`;
48
+ }
49
+ function html(text) {
50
+ return text.replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`);
51
+ }
52
+ function script(value) {
53
+ return JSON.stringify(value).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
54
+ }
55
+
56
+ // src/handler.ts
57
+ var GRAPHIQL_POLICY = [
58
+ "default-src 'self'",
59
+ "script-src 'self' 'unsafe-inline' https://unpkg.com",
60
+ "style-src 'self' 'unsafe-inline' https://unpkg.com",
61
+ "img-src 'self' data: https:",
62
+ "font-src 'self' data: https:",
63
+ "worker-src 'self' blob:",
64
+ "connect-src 'self'"
65
+ ].join("; ");
66
+ function yogaServers(options) {
67
+ const servers = new Map;
68
+ return (endpoint) => {
69
+ let yoga = servers.get(endpoint);
70
+ if (yoga === undefined) {
71
+ yoga = createYoga({
72
+ ...options,
73
+ graphqlEndpoint: endpoint
74
+ });
75
+ servers.set(endpoint, yoga);
76
+ }
77
+ return yoga;
78
+ };
79
+ }
80
+ function graphqlHandler(yogaAt, sandbox) {
81
+ return async (ctx) => {
82
+ const {
83
+ params: _params,
84
+ query: _query,
85
+ headers: _headers,
86
+ cookies: _cookies,
87
+ body: _body,
88
+ reply,
89
+ redirect: _redirect,
90
+ ...server
91
+ } = ctx;
92
+ if (sandbox !== false && ctx.request.method === "GET" && ctx.request.headers.get("accept")?.includes("text/html") && !ctx.url.searchParams.has("query")) {
93
+ return reply(200, renderSandbox(ctx.route, sandbox), {
94
+ headers: {
95
+ "content-type": "text/html;charset=utf-8",
96
+ "content-security-policy": SANDBOX_POLICY
97
+ }
98
+ });
99
+ }
100
+ const response = await yogaAt(ctx.route).fetch(ctx.request, server);
101
+ const headers = new Headers(response.headers);
102
+ if (headers.get("content-type")?.startsWith("text/html") && !headers.has("content-security-policy")) {
103
+ headers.set("content-security-policy", GRAPHIQL_POLICY);
104
+ }
105
+ return reply(response.status, response.body ?? undefined, {
106
+ headers
107
+ });
108
+ };
109
+ }
110
+
111
+ // src/graphql.ts
112
+ function graphql(app, options) {
113
+ const {
114
+ path = "/graphql",
115
+ cors = false,
116
+ ide = "graphiql",
117
+ graphiql,
118
+ sandbox,
119
+ ...yogaOptions
120
+ } = options;
121
+ const yogaAt = yogaServers({
122
+ ...yogaOptions,
123
+ cors,
124
+ graphiql: ide === "graphiql" ? graphiql ?? true : false
125
+ });
126
+ const handler = graphqlHandler(yogaAt, ide === "apollo-sandbox" ? sandbox ?? {} : false);
127
+ const route = app;
128
+ route.get(path, handler);
129
+ route.post(path, handler);
130
+ return app;
131
+ }
132
+ export {
133
+ SANDBOX_POLICY,
134
+ graphql,
135
+ renderSandbox
136
+ };
137
+
138
+ //# debugId=0BBAFC751282FEBB64756E2164756E21
139
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1,12 @@
1
+ {
2
+ "version": 3,
3
+ "sources": ["../src/handler.ts", "../src/sandbox.ts", "../src/graphql.ts"],
4
+ "sourcesContent": [
5
+ "/**\n * The endpoint behind `graphql()`: one Yoga per path it is served at, and\n * the route handler that hands each request to it.\n */\nimport type { BaseContext, StatusCode } from '@alxia/core';\nimport {\n\tcreateYoga,\n\ttype YogaServerInstance,\n\ttype YogaServerOptions,\n} from 'graphql-yoga';\nimport { renderSandbox, SANDBOX_POLICY, type SandboxOptions } from './sandbox';\n\nexport type YogaContext = Record<string, any>;\n\n/**\n * What GraphiQL loads: Yoga's page from unpkg, and queries to this server.\n * `@alxia/secure-headers` keeps a policy a response already has.\n */\nconst GRAPHIQL_POLICY = [\n\t\"default-src 'self'\",\n\t\"script-src 'self' 'unsafe-inline' https://unpkg.com\",\n\t\"style-src 'self' 'unsafe-inline' https://unpkg.com\",\n\t\"img-src 'self' data: https:\",\n\t\"font-src 'self' data: https:\",\n\t\"worker-src 'self' blob:\",\n\t\"connect-src 'self'\",\n].join('; ');\n\n/**\n * The Yoga serving `endpoint`, created on first use. One per path: a plugin\n * mounted under a prefix serves the same routes at a longer path, and\n * GraphiQL must ask that one.\n */\nexport function yogaServers<UserCtx extends YogaContext>(\n\toptions: Omit<YogaServerOptions<YogaContext, UserCtx>, 'graphqlEndpoint'>,\n): (endpoint: string) => YogaServerInstance<YogaContext, UserCtx> {\n\tconst servers = new Map<string, YogaServerInstance<YogaContext, UserCtx>>();\n\treturn (endpoint) => {\n\t\tlet yoga = servers.get(endpoint);\n\t\tif (yoga === undefined) {\n\t\t\tyoga = createYoga<YogaContext, UserCtx>({\n\t\t\t\t...options,\n\t\t\t\tgraphqlEndpoint: endpoint,\n\t\t\t});\n\t\t\tservers.set(endpoint, yoga);\n\t\t}\n\t\treturn yoga;\n\t};\n}\n\n/**\n * The handler of the endpoint's `GET` and `POST`: Apollo Sandbox's page to\n * a browser when `sandbox` is not `false`, else the request to Yoga, with\n * the route's context — the hooks' work, minus what a resolver has no use\n * for — as Yoga's server context.\n */\nexport function graphqlHandler<UserCtx extends YogaContext>(\n\tyogaAt: (endpoint: string) => YogaServerInstance<YogaContext, UserCtx>,\n\tsandbox: SandboxOptions | false,\n) {\n\treturn async (ctx: Record<string, unknown> & BaseContext) => {\n\t\tconst {\n\t\t\tparams: _params,\n\t\t\tquery: _query,\n\t\t\theaders: _headers,\n\t\t\tcookies: _cookies,\n\t\t\tbody: _body,\n\t\t\treply,\n\t\t\tredirect: _redirect,\n\t\t\t...server\n\t\t} = ctx;\n\t\tif (\n\t\t\tsandbox !== false &&\n\t\t\tctx.request.method === 'GET' &&\n\t\t\tctx.request.headers.get('accept')?.includes('text/html') &&\n\t\t\t!ctx.url.searchParams.has('query')\n\t\t) {\n\t\t\t// A path: the page resolves it against its own address, so behind\n\t\t\t// a TLS proxy the Sandbox asks over https, as the browser did.\n\t\t\treturn reply(200, renderSandbox(ctx.route, sandbox), {\n\t\t\t\theaders: {\n\t\t\t\t\t'content-type': 'text/html;charset=utf-8',\n\t\t\t\t\t'content-security-policy': SANDBOX_POLICY,\n\t\t\t\t},\n\t\t\t});\n\t\t}\n\t\tconst response = await yogaAt(ctx.route).fetch(ctx.request, server);\n\t\tconst headers = new Headers(response.headers);\n\t\tif (\n\t\t\theaders.get('content-type')?.startsWith('text/html') &&\n\t\t\t!headers.has('content-security-policy')\n\t\t) {\n\t\t\theaders.set('content-security-policy', GRAPHIQL_POLICY);\n\t\t}\n\t\treturn reply(response.status as StatusCode, response.body ?? undefined, {\n\t\t\theaders,\n\t\t});\n\t};\n}\n",
6
+ "/**\n * [Apollo Sandbox](https://www.apollographql.com/docs/graphos/platform/sandbox),\n * embedded: the page a browser gets at the endpoint when the IDE is\n * `apollo-sandbox`. `@nxgt/shared-graphql`'s `renderSandbox`, kept twice: the\n * Sandbox asks the address the page was opened at, as there since\n * nxgt-core#171, but here the page resolves the path itself, so a TLS proxy\n * in front changes nothing.\n */\n\nexport interface SandboxOptions {\n\t/** The page's title. `Sandbox Explorer` by default. */\n\treadonly title?: string;\n\t/** The operation the Sandbox opens with. */\n\treadonly initialDocument?: string;\n\t/** Headers every operation sends, shown and editable in the Sandbox. */\n\treadonly initialHeaders?: Readonly<Record<string, string>>;\n\t/** Whether the Sandbox polls the schema as it changes. On by default. */\n\treadonly pollForSchemaUpdates?: boolean;\n\t/** Whether operations send the browser's cookies: a session cookie. On by default. */\n\treadonly includeCookies?: boolean;\n}\n\n/** What the page loads: the Sandbox's script, its frame, and operations to this server. */\nexport const SANDBOX_POLICY = [\n\t\"default-src 'self'\",\n\t\"script-src 'self' 'unsafe-inline' https://embeddable-sandbox.cdn.apollographql.com\",\n\t\"style-src 'self' 'unsafe-inline'\",\n\t'frame-src https://sandbox.embed.apollographql.com',\n\t\"img-src 'self' data: https:\",\n\t\"connect-src 'self'\",\n].join('; ');\n\n/**\n * The page, its endpoint `endpoint`: a URL, or a path the page resolves\n * against its own address. Every value is escaped into its JavaScript and\n * HTML.\n */\nexport function renderSandbox(\n\tendpoint: string,\n\toptions: SandboxOptions = {},\n): string {\n\tconst config = {\n\t\ttarget: '#sandbox',\n\t\tinitialEndpoint: endpoint,\n\t\tinitialState: {\n\t\t\tincludeCookies: options.includeCookies ?? true,\n\t\t\tpollForSchemaUpdates: options.pollForSchemaUpdates ?? true,\n\t\t\t...(options.initialDocument === undefined\n\t\t\t\t? {}\n\t\t\t\t: { document: options.initialDocument }),\n\t\t\t...(options.initialHeaders === undefined\n\t\t\t\t? {}\n\t\t\t\t: { headers: options.initialHeaders }),\n\t\t},\n\t\thideCookieToggle: false,\n\t\tendpointIsEditable: false,\n\t};\n\treturn `<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\" />\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n<title>${html(options.title ?? 'Sandbox Explorer')}</title>\n<style>html, body { margin: 0; height: 100%; } #sandbox { position: absolute; inset: 0; }</style>\n</head>\n<body>\n<div id=\"sandbox\"></div>\n<script src=\"https://embeddable-sandbox.cdn.apollographql.com/_latest/embeddable-sandbox.umd.production.min.js\"></script>\n<script>\n{\nconst config = ${script(config)};\nconfig.initialEndpoint = new URL(config.initialEndpoint, location.href).href;\nnew window.EmbeddedSandbox(config);\n}\n</script>\n</body>\n</html>`;\n}\n\nfunction html(text: string): string {\n\treturn text.replace(/[&<>\"']/g, (char) => `&#${char.charCodeAt(0)};`);\n}\n\n/** JSON that cannot close the `<script>` it is written in. */\nfunction script(value: unknown): string {\n\treturn JSON.stringify(value)\n\t\t.replace(/</g, '\\\\u003c')\n\t\t.replace(/>/g, '\\\\u003e')\n\t\t.replace(/\\u2028/g, '\\\\u2028')\n\t\t.replace(/\\u2029/g, '\\\\u2029');\n}\n",
7
+ "import type {\n\tAlxia,\n\tAnyReply,\n\tBaseContext,\n\tEmpty,\n\tJoinPath,\n\tReply,\n\tRouteEntryOf,\n\tRoutePath,\n\tStatusCode,\n} from '@alxia/core';\nimport type {\n\tGraphQLSchemaWithContext,\n\tYogaInitialContext,\n\tYogaServerOptions,\n} from 'graphql-yoga';\nimport { graphqlHandler, type YogaContext, yogaServers } from './handler';\nimport type { SandboxOptions } from './sandbox';\n\n/** The parts of a route's context Yoga owns, or that mean nothing to a resolver. */\ntype RouteOnly =\n\t| 'params'\n\t| 'query'\n\t| 'headers'\n\t| 'cookies'\n\t| 'body'\n\t| 'reply'\n\t| 'redirect';\n\n/**\n * What alxia hands Yoga for each request: the context its hooks built —\n * `user`, `db`, `log`… — with `request`, `url`, `ip` and `set`, through\n * which a resolver sets a cookie or a header on the response.\n */\nexport type ServerContext<Ctx> = Omit<BaseContext & Ctx, RouteOnly>;\n\n/**\n * What a resolver reads as its context: Yoga's own, the app's, and what\n * the `context` option adds. Type a schema with it:\n *\n * ```ts\n * const base = alxia().use(bearer({ jwt }));\n * const schema = createSchema<GraphQLContext<typeof base>>({ ... });\n * ```\n */\nexport type GraphQLContext<App, UserContext = Empty> = App extends {\n\treadonly '~context': infer Ctx;\n}\n\t? YogaInitialContext & ServerContext<Ctx> & UserContext\n\t: // Not `never`: a schema typed with `never` would let every resolver\n\t\t// read anything until `graphql()` refused it.\n\t\t{\n\t\t\treadonly '~error': 'GraphQLContext needs the type of an app: GraphQLContext<typeof app>';\n\t\t};\n\nexport interface GraphQLOptions<\n\tServerCtx extends YogaContext,\n\tUserCtx extends YogaContext,\n\tPath extends RoutePath,\n\tSchemaCtx = unknown,\n> extends Omit<\n\t\tYogaServerOptions<ServerCtx, UserCtx>,\n\t\t'graphqlEndpoint' | 'cors' | 'schema' | 'graphiql'\n\t> {\n\t/**\n\t * What a browser gets at the endpoint: Yoga's GraphiQL, Apollo Sandbox,\n\t * or nothing. GraphiQL by default; turn both off in production.\n\t */\n\treadonly ide?: 'graphiql' | 'apollo-sandbox' | false;\n\t/** GraphiQL's options, Yoga's own, when `ide` is `graphiql`. */\n\treadonly graphiql?: Exclude<\n\t\tYogaServerOptions<ServerCtx, UserCtx>['graphiql'],\n\t\tboolean\n\t>;\n\t/** Apollo Sandbox's options, when `ide` is `apollo-sandbox`. */\n\treadonly sandbox?: SandboxOptions;\n\t/**\n\t * The schema, from Yoga's `createSchema`, Pothos, or any tool that types\n\t * its context. Its context must be one the app builds: a resolver that\n\t * reads `user` behind no hook that derives one is a compile error.\n\t */\n\treadonly schema: GraphQLSchemaWithContext<SchemaCtx>;\n\t/** Where the endpoint is, under the app's prefix. `/graphql` by default. */\n\treadonly path?: Path;\n\t/**\n\t * Yoga's own CORS. Off by default: `@alxia/cors` answers for the whole\n\t * app, this endpoint included.\n\t */\n\treadonly cors?: YogaServerOptions<ServerCtx, UserCtx>['cors'];\n}\n\n/**\n * The check Yoga's types leave out: the context the app builds must hold\n * what the schema's resolvers read. A mistake comes back as a `schema`\n * whose type is the message.\n */\ntype ProvidesContext<Provided, Required> = Provided extends Required\n\t? unknown\n\t: {\n\t\t\treadonly schema: `the schema's resolvers read a context the app does not build: missing ${Exclude<\n\t\t\t\tkeyof Required,\n\t\t\t\tkeyof Provided\n\t\t\t> &\n\t\t\t\tstring}`;\n\t\t};\n\n/** What the endpoint answers, as alxia's client sees it: a body to read as GraphQL. */\ntype GraphQLReply = Reply<StatusCode, ReadableStream<Uint8Array> | undefined>;\n\nexport type GraphQLRoutes<\n\tPath extends string,\n\tShortcuts extends AnyReply,\n> = RouteEntryOf<'GET', Path, Empty, GraphQLReply, Shortcuts> &\n\tRouteEntryOf<'POST', Path, Empty, GraphQLReply, Shortcuts>;\n\n/**\n * A GraphQL endpoint on `app`, served by [GraphQL Yoga](https://the-guild.dev/graphql/yoga-server):\n * `GET` and `POST` at `path`, behind every hook declared on `app` before it.\n * A guard before it guards it; what the hooks derived is in each\n * resolver's context, typed. Yoga's options pass through — `plugins`\n * (Envelop's and Yoga's), `graphiql`, `maskedErrors`, `batching`… —\n * and subscriptions are served over server-sent events.\n *\n * ```ts\n * const app = alxia()\n * .use(bearer({ jwt }))\n * .use((app) => graphql(app, { schema, plugins: [useDepthLimit()] }));\n * ```\n */\nexport function graphql<\n\tCtx extends object,\n\tRoutes extends object,\n\tPrefix extends string,\n\tShortcuts extends AnyReply,\n\tSchemaCtx,\n\tUserCtx extends YogaContext = Empty,\n\tconst Path extends RoutePath = '/graphql',\n>(\n\tapp: Alxia<Ctx, Routes, Prefix, Shortcuts>,\n\toptions: GraphQLOptions<ServerContext<Ctx>, UserCtx, Path, SchemaCtx> &\n\t\tProvidesContext<\n\t\t\tYogaInitialContext & ServerContext<Ctx> & UserCtx,\n\t\t\tSchemaCtx\n\t\t>,\n): Alxia<\n\tCtx,\n\tRoutes & GraphQLRoutes<JoinPath<Prefix, Path>, Shortcuts>,\n\tPrefix,\n\tShortcuts\n> {\n\tconst {\n\t\tpath = '/graphql' as Path,\n\t\tcors = false,\n\t\tide = 'graphiql',\n\t\tgraphiql,\n\t\tsandbox,\n\t\t...yogaOptions\n\t} = options;\n\tconst yogaAt = yogaServers<UserCtx>({\n\t\t...(yogaOptions as YogaServerOptions<YogaContext, UserCtx>),\n\t\tcors,\n\t\tgraphiql: (ide === 'graphiql'\n\t\t\t? (graphiql ?? true)\n\t\t\t: false) as YogaServerOptions<YogaContext, UserCtx>['graphiql'],\n\t});\n\tconst handler = graphqlHandler(\n\t\tyogaAt,\n\t\tide === 'apollo-sandbox' ? (sandbox ?? {}) : false,\n\t);\n\n\tconst route = app as unknown as {\n\t\tget(path: string, handler: unknown): unknown;\n\t\tpost(path: string, handler: unknown): unknown;\n\t};\n\troute.get(path, handler);\n\troute.post(path, handler);\n\treturn app as never;\n}\n"
8
+ ],
9
+ "mappings": "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",
10
+ "debugId": "0BBAFC751282FEBB64756E2164756E21",
11
+ "names": []
12
+ }
@@ -0,0 +1,29 @@
1
+ /**
2
+ * [Apollo Sandbox](https://www.apollographql.com/docs/graphos/platform/sandbox),
3
+ * embedded: the page a browser gets at the endpoint when the IDE is
4
+ * `apollo-sandbox`. `@nxgt/shared-graphql`'s `renderSandbox`, kept twice: the
5
+ * Sandbox asks the address the page was opened at, as there since
6
+ * nxgt-core#171, but here the page resolves the path itself, so a TLS proxy
7
+ * in front changes nothing.
8
+ */
9
+ export interface SandboxOptions {
10
+ /** The page's title. `Sandbox Explorer` by default. */
11
+ readonly title?: string;
12
+ /** The operation the Sandbox opens with. */
13
+ readonly initialDocument?: string;
14
+ /** Headers every operation sends, shown and editable in the Sandbox. */
15
+ readonly initialHeaders?: Readonly<Record<string, string>>;
16
+ /** Whether the Sandbox polls the schema as it changes. On by default. */
17
+ readonly pollForSchemaUpdates?: boolean;
18
+ /** Whether operations send the browser's cookies: a session cookie. On by default. */
19
+ readonly includeCookies?: boolean;
20
+ }
21
+ /** What the page loads: the Sandbox's script, its frame, and operations to this server. */
22
+ export declare const SANDBOX_POLICY: string;
23
+ /**
24
+ * The page, its endpoint `endpoint`: a URL, or a path the page resolves
25
+ * against its own address. Every value is escaped into its JavaScript and
26
+ * HTML.
27
+ */
28
+ export declare function renderSandbox(endpoint: string, options?: SandboxOptions): string;
29
+ //# sourceMappingURL=sandbox.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,cAAc;IAC9B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,4CAA4C;IAC5C,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,wEAAwE;IACxE,QAAQ,CAAC,cAAc,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3D,yEAAyE;IACzE,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IACxC,sFAAsF;IACtF,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,2FAA2F;AAC3F,eAAO,MAAM,cAAc,QAOf,CAAC;AAEb;;;;GAIG;AACH,wBAAgB,aAAa,CAC5B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,cAAmB,GAC1B,MAAM,CAqCR"}
package/docs/README.md ADDED
@@ -0,0 +1,16 @@
1
+ # @alxia/graphql documentation
2
+
3
+ The [package README](../README.md) is the short version. This folder is
4
+ the long one: a guide page per area, with the options, defaults, errors and
5
+ a realistic example for each.
6
+
7
+ ## Guide
8
+
9
+ | Page | Read it when |
10
+ | --- | --- |
11
+ | [Mounting the endpoint](guide/endpoint.md) | adding GraphQL to an app, choosing its path under a prefix, putting it behind a guard, reading what it answers, or testing it without a server |
12
+ | [The typed context](guide/context.md) | typing a schema with the app's context, reading `user` or a database handle in a resolver, setting a cookie, adding per-request loaders, or reading the `missing …` compile error |
13
+ | [Yoga's plugins and options](guide/yoga.md) | adding Yoga or Envelop plugins, exposing or masking errors, batching, serving subscriptions, or calling the endpoint from another origin |
14
+ | [GraphiQL and Apollo Sandbox](guide/ide.md) | choosing the IDE a browser gets, configuring it, keeping it working under a strict `Content-Security-Policy`, or turning it off in production |
15
+ | [Troubleshooting](troubleshooting.md) | something went wrong and you have the message |
16
+ | [Roadmap](roadmap.md) | wondering what is coming, and what is not planned |