@alxia/graphql 0.1.1 → 0.2.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/README.md CHANGED
@@ -2,8 +2,8 @@
2
2
 
3
3
  GraphQL for [alxia](https://www.npmjs.com/package/@alxia/core), served by
4
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.
5
+ route like any other: behind the app's middlewares, guarded by its guards, its
6
+ resolvers reading the context those middlewares built — typed, and checked.
7
7
  Yoga's plugin system is yours whole: Envelop's plugins and Yoga's own.
8
8
 
9
9
  ```sh
@@ -34,18 +34,18 @@ const schema = createSchema<GraphQLContext<typeof base>>({
34
34
  },
35
35
  });
36
36
 
37
- const app = base.use((app) => graphql(app, { schema })); // POST and GET /graphql
37
+ const app = base.plugin((app) => graphql(app, { schema })); // POST and GET /graphql
38
38
  app.listen(3000);
39
39
  ```
40
40
 
41
41
  `graphql(app, options)` adds `GET` and `POST` routes at `path` —
42
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.
43
+ to `app.plugin` as a function, it stays in the chain and sees the app's type.
44
44
 
45
45
  ## The context
46
46
 
47
47
  A resolver's context is Yoga's (`request`, `params`), the app's — every
48
- `decorate`, every `derive`, every plugin's: `user`, `db`, `log`,
48
+ `decorate`, every `derive`, every middleware's: `user`, `db`, `log`,
49
49
  `requestId` — and `set`, through which it sets a header or a cookie:
50
50
 
51
51
  ```ts
@@ -108,7 +108,7 @@ graphql(app, {
108
108
  | `renderSandbox(endpoint, options?)`, `SANDBOX_POLICY` | the Sandbox page, and the policy it loads under |
109
109
  | `SandboxOptions` | its options: `title`, `initialDocument`, `initialHeaders`, `pollForSchemaUpdates`, `includeCookies` |
110
110
  | `GraphQLContext<App, UserContext?>` | what a resolver reads |
111
- | `ServerContext<Ctx>`, `GraphQLOptions`, `GraphQLRoutes` | its types |
111
+ | `ServerContext<Ctx>`, `GraphQLOptions` | its types |
112
112
 
113
113
  ## Documentation
114
114
 
package/dist/graphql.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { Alxia, AnyReply, BaseContext, Empty, JoinPath, Reply, RouteEntryOf, RoutePath, StatusCode } from '@alxia/core';
1
+ import type { Alxia, AnyReply, BaseContext, Empty, RoutePath } from '@alxia/core';
2
2
  import type { GraphQLSchemaWithContext, YogaInitialContext, YogaServerOptions } from 'graphql-yoga';
3
3
  import { type YogaContext } from './handler';
4
4
  import type { SandboxOptions } from './sandbox';
@@ -56,9 +56,6 @@ export interface GraphQLOptions<ServerCtx extends YogaContext, UserCtx extends Y
56
56
  type ProvidesContext<Provided, Required> = Provided extends Required ? unknown : {
57
57
  readonly schema: `the schema's resolvers read a context the app does not build: missing ${Exclude<keyof Required, keyof Provided> & string}`;
58
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
59
  /**
63
60
  * A GraphQL endpoint on `app`, served by [GraphQL Yoga](https://the-guild.dev/graphql/yoga-server):
64
61
  * `GET` and `POST` at `path`, behind every hook declared on `app` before it.
@@ -70,9 +67,9 @@ export type GraphQLRoutes<Path extends string, Shortcuts extends AnyReply> = Rou
70
67
  * ```ts
71
68
  * const app = alxia()
72
69
  * .use(bearer({ jwt }))
73
- * .use((app) => graphql(app, { schema, plugins: [useDepthLimit()] }));
70
+ * .plugin((app) => graphql(app, { schema, plugins: [useDepthLimit()] }));
74
71
  * ```
75
72
  */
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>;
73
+ export declare function graphql<Ctx extends object, Prefix extends string, Shortcuts extends AnyReply, SchemaCtx, UserCtx extends YogaContext = Empty, const Path extends RoutePath = '/graphql'>(app: Alxia<Ctx, Prefix, Shortcuts>, options: GraphQLOptions<ServerContext<Ctx>, UserCtx, Path, SchemaCtx> & ProvidesContext<YogaInitialContext & ServerContext<Ctx> & UserCtx, SchemaCtx>): Alxia<Ctx, Prefix, Shortcuts>;
77
74
  export {};
78
75
  //# sourceMappingURL=graphql.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"graphql.d.ts","sourceRoot":"","sources":["../src/graphql.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"graphql.d.ts","sourceRoot":"","sources":["../src/graphql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,KAAK,EACL,QAAQ,EACR,WAAW,EACX,KAAK,EACL,SAAS,EACT,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EACX,wBAAwB,EACxB,kBAAkB,EAClB,iBAAiB,EACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAkB,KAAK,WAAW,EAAe,MAAM,WAAW,CAAC;AAC1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,oFAAoF;AACpF,KAAK,SAAS,GACX,QAAQ,GACR,OAAO,GACP,SAAS,GACT,SAAS,GACT,MAAM,GACN,OAAO,GACP,UAAU,CAAC;AAEd;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,GAAG,IAAI,IAAI,CAAC,WAAW,GAAG,GAAG,EAAE,SAAS,CAAC,CAAC;AAEpE;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,CAAC,GAAG,EAAE,WAAW,GAAG,KAAK,IAAI,GAAG,SAAS;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,CAAC;CAC/B,GACE,kBAAkB,GAAG,aAAa,CAAC,GAAG,CAAC,GAAG,WAAW,GAGtD;IACC,QAAQ,CAAC,QAAQ,EAAE,qEAAqE,CAAC;CACzF,CAAC;AAEJ,MAAM,WAAW,cAAc,CAC9B,SAAS,SAAS,WAAW,EAC7B,OAAO,SAAS,WAAW,EAC3B,IAAI,SAAS,SAAS,EACtB,SAAS,GAAG,OAAO,CAClB,SAAQ,IAAI,CACZ,iBAAiB,CAAC,SAAS,EAAE,OAAO,CAAC,EACrC,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAClD;IACD;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,UAAU,GAAG,gBAAgB,GAAG,KAAK,CAAC;IACrD,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAC1B,iBAAiB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,UAAU,CAAC,EACjD,OAAO,CACP,CAAC;IACF,gEAAgE;IAChE,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC,SAAS,CAAC,CAAC;IACrD,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,iBAAiB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC;CAC9D;AAED;;;;GAIG;AACH,KAAK,eAAe,CAAC,QAAQ,EAAE,QAAQ,IAAI,QAAQ,SAAS,QAAQ,GACjE,OAAO,GACP;IACA,QAAQ,CAAC,MAAM,EAAE,yEAAyE,OAAO,CAChG,MAAM,QAAQ,EACd,MAAM,QAAQ,CACd,GACA,MAAM,EAAE,CAAC;CACV,CAAC;AAEJ;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CACtB,GAAG,SAAS,MAAM,EAClB,MAAM,SAAS,MAAM,EACrB,SAAS,SAAS,QAAQ,EAC1B,SAAS,EACT,OAAO,SAAS,WAAW,GAAG,KAAK,EACnC,KAAK,CAAC,IAAI,SAAS,SAAS,GAAG,UAAU,EAEzC,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAClC,OAAO,EAAE,cAAc,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,GACpE,eAAe,CACd,kBAAkB,GAAG,aAAa,CAAC,GAAG,CAAC,GAAG,OAAO,EACjD,SAAS,CACT,GACA,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,CA4B/B"}
package/dist/handler.d.ts CHANGED
@@ -18,5 +18,7 @@ export declare function yogaServers<UserCtx extends YogaContext>(options: Omit<Y
18
18
  * the route's context — the hooks' work, minus what a resolver has no use
19
19
  * for — as Yoga's server context.
20
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>>>>;
21
+ export declare function graphqlHandler<UserCtx extends YogaContext>(yogaAt: (endpoint: string) => YogaServerInstance<YogaContext, UserCtx>, sandbox: SandboxOptions | false): (ctx: Record<string, unknown> & BaseContext & {
22
+ readonly route: string;
23
+ }) => Promise<import("@alxia/core").Reply<200, string> | import("@alxia/core").Reply<StatusCode, ReadableStream<Uint8Array<ArrayBuffer>>>>;
22
24
  //# sourceMappingURL=handler.d.ts.map
@@ -1 +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"}
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,IAI9B,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,0IAuCxE"}
package/dist/index.d.ts CHANGED
@@ -1,3 +1,3 @@
1
- export { type GraphQLContext, type GraphQLOptions, type GraphQLRoutes, graphql, type ServerContext, } from './graphql';
1
+ export { type GraphQLContext, type GraphQLOptions, graphql, type ServerContext, } from './graphql';
2
2
  export { renderSandbox, SANDBOX_POLICY, type SandboxOptions } from './sandbox';
3
3
  //# sourceMappingURL=index.d.ts.map
@@ -1 +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"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,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.map CHANGED
@@ -2,11 +2,11 @@
2
2
  "version": 3,
3
3
  "sources": ["../src/handler.ts", "../src/sandbox.ts", "../src/graphql.ts"],
4
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",
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\t// A handler's context: its route is the one it was declared at.\n\treturn async (\n\t\tctx: Record<string, unknown> & BaseContext & { readonly route: string },\n\t) => {\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
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"
7
+ "import type {\n\tAlxia,\n\tAnyReply,\n\tBaseContext,\n\tEmpty,\n\tRoutePath,\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/**\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 * .plugin((app) => graphql(app, { schema, plugins: [useDepthLimit()] }));\n * ```\n */\nexport function graphql<\n\tCtx 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, 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<Ctx, Prefix, Shortcuts> {\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
8
  ],
9
- "mappings": "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",
9
+ "mappings": "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",
10
10
  "debugId": "0BBAFC751282FEBB64756E2164756E21",
11
11
  "names": []
12
12
  }
@@ -28,10 +28,10 @@ const schema = createSchema<GraphQLContext<typeof base>>({
28
28
  },
29
29
  });
30
30
 
31
- const app = base.use((app) => graphql(app, { schema }));
31
+ const app = base.plugin((app) => graphql(app, { schema }));
32
32
  ```
33
33
 
34
- Declare the hooks on a `base` app, type the schema with
34
+ Declare the middlewares on a `base` app, type the schema with
35
35
  `GraphQLContext<typeof base>`, then mount the endpoint on it. The schema
36
36
  cannot be typed from `app` itself: `app` is built from the schema.
37
37
 
@@ -65,7 +65,7 @@ A resolver's context holds:
65
65
  | From | Fields |
66
66
  | --- | --- |
67
67
  | Yoga (`YogaInitialContext`) | `request`, and `params`: the GraphQL request's `query`, `variables`, `operationName`, `extensions` |
68
- | the app's hooks | everything `decorate` and `derive` added before the endpoint, and what plugins such as `@alxia/jwt`'s `bearer` add (`user`) |
68
+ | the app's middlewares | everything `decorate` and `derive` added before the endpoint, and what middlewares such as `@alxia/jwt`'s `bearer` add (`user`) |
69
69
  | the route (`BaseContext`) | `url`, `ip`, `server`, `route`, `pathParams`, `error`, and `set` |
70
70
  | the `context` option | what it returns, as `UserContext` ([below](#the-context-option)) |
71
71
 
@@ -117,7 +117,7 @@ typed with a context the app does not build is refused, and the error names
117
117
  the missing field:
118
118
 
119
119
  ```ts
120
- const app = alxia().use((app) => graphql(app, { schema })); // no hook derives `viewer` or `users`
120
+ const app = alxia().plugin((app) => graphql(app, { schema })); // no middleware derives `viewer` or `users`
121
121
  ```
122
122
 
123
123
  ```text
@@ -128,7 +128,7 @@ error TS2322: Type 'GraphQLSchemaWithContext<…>' is not assignable to type 'Gr
128
128
 
129
129
  With `exactOptionalPropertyTypes` on, the code is `TS2375`; the message
130
130
  ends the same way. The fix is to mount the endpoint on the
131
- app the schema was typed from, after its hooks:
131
+ app the schema was typed from, after its middlewares:
132
132
  [Troubleshooting](../troubleshooting.md#the-schemas-resolvers-read-a-context-the-app-does-not-build-missing-).
133
133
 
134
134
  An untyped schema — `createSchema({ … })` with no type argument — passes
@@ -138,7 +138,7 @@ app's context.
138
138
 
139
139
  ## With a token: `@alxia/jwt`
140
140
 
141
- A guard plugin is a hook like any other. With `@alxia/jwt`'s `bearer`, the
141
+ A guard is a middleware like any other, given to `use` before the endpoint. With `@alxia/jwt`'s `bearer`, the
142
142
  endpoint requires a token and `user` is the token's claims, typed by the
143
143
  schema you give it:
144
144
 
@@ -164,7 +164,7 @@ const schema = createSchema<GraphQLContext<typeof base>>({
164
164
  },
165
165
  });
166
166
 
167
- const app = base.use((app) => graphql(app, { schema }));
167
+ const app = base.plugin((app) => graphql(app, { schema }));
168
168
  ```
169
169
 
170
170
  The guard's `401` and its body are `@alxia/jwt`'s, described in its
@@ -186,7 +186,7 @@ const schema = createSchema<GraphQLContext<typeof base, Loaders>>({
186
186
  },
187
187
  });
188
188
 
189
- const app = base.use((app) =>
189
+ const app = base.plugin((app) =>
190
190
  graphql(app, {
191
191
  schema,
192
192
  // annotate the argument: see below
@@ -219,6 +219,6 @@ as per-request data loaders.
219
219
 
220
220
  ## See also
221
221
 
222
- - [Mounting the endpoint](endpoint.md): which hooks run before it.
223
- - [Hooks](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/hooks.md),
222
+ - [Mounting the endpoint](endpoint.md): which middlewares run before it.
223
+ - [Middlewares](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/middleware.md),
224
224
  in `@alxia/core`'s guide: `decorate` and `derive`.
@@ -1,7 +1,7 @@
1
1
  # Mounting the endpoint
2
2
 
3
3
  This page covers `graphql(app, options)`: where the endpoint is served, what
4
- it answers, which hooks run before it, and how to test it.
4
+ it answers, which middlewares run before it, and how to test it.
5
5
 
6
6
  ```ts
7
7
  import { alxia } from '@alxia/core';
@@ -15,7 +15,7 @@ const schema = createSchema({
15
15
 
16
16
  const app = alxia()
17
17
  .get('/health', ({ reply }) => reply(200, 'ok'))
18
- .use((app) => graphql(app, { schema })); // GET and POST /graphql
18
+ .plugin((app) => graphql(app, { schema })); // GET and POST /graphql
19
19
 
20
20
  app.listen(3000);
21
21
  ```
@@ -28,18 +28,18 @@ curl localhost:3000/graphql -H 'content-type: application/json' -d '{"query":"{
28
28
  ## `graphql`
29
29
 
30
30
  ```ts
31
- function graphql<Ctx, Routes, Prefix, Shortcuts, SchemaCtx, UserCtx = Empty, const Path = '/graphql'>(
32
- app: Alxia<Ctx, Routes, Prefix, Shortcuts>,
31
+ function graphql<Ctx, Prefix, Shortcuts, SchemaCtx, UserCtx = Empty, const Path = '/graphql'>(
32
+ app: Alxia<Ctx, Prefix, Shortcuts>,
33
33
  options: GraphQLOptions<ServerContext<Ctx>, UserCtx, Path, SchemaCtx>,
34
- ): Alxia<Ctx, Routes & GraphQLRoutes<JoinPath<Prefix, Path>, Shortcuts>, Prefix, Shortcuts>;
34
+ ): Alxia<Ctx, Prefix, Shortcuts>;
35
35
  ```
36
36
 
37
37
  `graphql` declares a `GET` and a `POST` route at `path` on `app`, and returns
38
- `app` with those two routes in its type. Hand it to `use` as a function, so
38
+ `app`, its type unchanged. Hand it to `app.plugin` as a function, so
39
39
  it stays in the chain and sees the app as typed so far:
40
40
 
41
41
  ```ts
42
- const app = base.use((app) => graphql(app, { schema }));
42
+ const app = base.plugin((app) => graphql(app, { schema }));
43
43
  ```
44
44
 
45
45
  Calling it directly does the same: `graphql(base, { schema })` declares the
@@ -62,17 +62,17 @@ routes on `base` and returns it.
62
62
  ## Where it is served
63
63
 
64
64
  `path` is joined to the app's prefix, and to the prefix of every app it is
65
- mounted into, in the routes' type as at runtime:
65
+ mounted into:
66
66
 
67
67
  ```ts
68
- import { alxia, type RoutesOf } from '@alxia/core';
68
+ import { alxia } from '@alxia/core';
69
69
 
70
70
  const api = alxia({ prefix: '/api' })
71
- .use((app) => graphql(app, { schema, path: '/gql' })); // /api/gql
71
+ .plugin((app) => graphql(app, { schema, path: '/gql' })); // /api/gql
72
72
 
73
- const root = alxia({ prefix: '/v1' }).use(api); // /v1/api/gql
73
+ const root = alxia({ prefix: '/v1' }).plugin(api); // /v1/api/gql
74
74
 
75
- type Paths = keyof RoutesOf<typeof root>; // '/v1/api/gql'
75
+ root.routes.map((route) => `${route.method} ${route.path}`); // ['GET /v1/api/gql', 'POST /v1/api/gql']
76
76
  ```
77
77
 
78
78
  Two endpoints on one app need two paths: declaring the default path twice
@@ -81,13 +81,13 @@ own path:
81
81
 
82
82
  ```ts
83
83
  const app = alxia()
84
- .use((app) => graphql(app, { schema }))
85
- .use((app) => graphql(app, { schema: admin, path: '/admin/graphql' }));
84
+ .plugin((app) => graphql(app, { schema }))
85
+ .plugin((app) => graphql(app, { schema: admin, path: '/admin/graphql' }));
86
86
  ```
87
87
 
88
- ## Behind the app's hooks
88
+ ## Behind the app's middlewares
89
89
 
90
- The endpoint is a route like any other: every route hook declared **before**
90
+ The endpoint is a route like any other: every middleware declared **before**
91
91
  it runs first, and one that replies ends the request there. A guard before
92
92
  it guards it:
93
93
 
@@ -98,17 +98,34 @@ const app = alxia()
98
98
  ? { viewer: 'service' }
99
99
  : reply(401, { error: 'unauthorized' as const }),
100
100
  )
101
- .use((app) => graphql(app, { schema })); // 401 without the token
101
+ .plugin((app) => graphql(app, { schema })); // 401 without the token
102
+ ```
103
+
104
+ A middleware declared **after** `app.plugin` does not run for the endpoint: it
105
+ answers without it. Give the observers (`@alxia/logger`, `@alxia/cors`,
106
+ `@alxia/secure-headers`, `@alxia/compress`) to `use` first, so they wrap the
107
+ endpoint, and every other request, the 404s included:
108
+
109
+ ```ts
110
+ import { alxia } from '@alxia/core';
111
+ import { cors } from '@alxia/cors';
112
+ import { graphql } from '@alxia/graphql';
113
+ import { logger } from '@alxia/logger';
114
+ import { secureHeaders } from '@alxia/secure-headers';
115
+
116
+ const app = alxia()
117
+ .use(logger())
118
+ .use(secureHeaders())
119
+ .use(cors({ origin: 'https://app.example.com' }))
120
+ .plugin((app) => graphql(app, { schema }));
102
121
  ```
103
122
 
104
- A hook declared **after** `use` does not run for it: the endpoint answers
105
- without it. The order is core's, explained in
106
- [Hooks](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/hooks.md#route-hooks-and-global-hooks).
107
- Global hooks — `onRequest`, `onResponse`, `around`, and the plugins built on
108
- them, such as `@alxia/cors` or `@alxia/secure-headers` — apply wherever they
109
- are declared.
123
+ A guard given to the app's `use` (`bearer`, a required session) also runs on
124
+ a request no route matches: an anonymous request to a missing path is a 401,
125
+ not a 404. The order is core's, explained in
126
+ [Middlewares](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/middleware.md).
110
127
 
111
- What the hooks added is in each resolver's context: that is the next page,
128
+ What the middlewares added is in each resolver's context: that is the next page,
112
129
  [The typed context](context.md).
113
130
 
114
131
  ## What it answers
@@ -123,7 +140,7 @@ IDE page ([GraphiQL and Apollo Sandbox](ide.md)).
123
140
  | `GET ?query=…` | the same, for a query; a mutation is a `405` |
124
141
  | `POST` a subscription with `Accept: text/event-stream` | `200`, a `text/event-stream` of results ([subscriptions](yoga.md#subscriptions)) |
125
142
  | `GET` from a browser (`Accept: text/html`), no `query` | the IDE page; with `ide: false`, a GraphQL answer (`Must provide query string.`) |
126
- | a hook replied first | that hook's reply, such as a `401` |
143
+ | a middleware replied first | that middleware's reply, such as a `401` |
127
144
 
128
145
  ```text
129
146
  POST {"query":"{ nope }"} → 200 {"errors":[{"message":"Cannot query field \"nope\" on type \"Query\".", … "extensions":{"code":"GRAPHQL_VALIDATION_FAILED"}}]}
@@ -131,15 +148,8 @@ GET ?query=mutation { m } → 405 {"errors":[{"message":"Can only pe
131
148
  POST {} → 200 {"errors":[{"message":"Must provide query string.","extensions":{"code":"BAD_REQUEST"}}]}
132
149
  ```
133
150
 
134
- The reply's type is `Reply<StatusCode, ReadableStream<Uint8Array> | undefined>`
135
- for both methods, plus the replies of the hooks before it: a typed client
136
- sees a body to read as GraphQL, and the guard's `401`.
137
-
138
- ```ts
139
- type GraphQLRoutes<Path extends string, Shortcuts extends AnyReply> =
140
- RouteEntryOf<'GET', Path, Empty, GraphQLReply, Shortcuts> &
141
- RouteEntryOf<'POST', Path, Empty, GraphQLReply, Shortcuts>;
142
- ```
151
+ Both methods answer a body to read as GraphQL, whatever its status, and
152
+ the replies of the middlewares before them — a guard's `401`, say.
143
153
 
144
154
  ## Testing it
145
155
 
@@ -158,7 +168,7 @@ const schema = createSchema({
158
168
  resolvers: { Query: { hello: (_, { name }: { name: string }) => `hello ${name}` } },
159
169
  });
160
170
 
161
- const app = alxia().use((app) => graphql(app, { schema, logging: false }));
171
+ const app = alxia().plugin((app) => graphql(app, { schema, logging: false }));
162
172
 
163
173
  const execute = (query: string, variables?: Record<string, unknown>) =>
164
174
  app.request('/graphql', {
package/docs/guide/ide.md CHANGED
@@ -15,7 +15,7 @@ const schema = createSchema({
15
15
  resolvers: { Query: { hello: () => 'world' } },
16
16
  });
17
17
 
18
- const app = alxia().use((app) =>
18
+ const app = alxia().plugin((app) =>
19
19
  graphql(app, {
20
20
  schema,
21
21
  ide: Bun.env['NODE_ENV'] === 'production' ? false : 'apollo-sandbox',
@@ -43,7 +43,7 @@ only `text/html` gets a [`406` with an empty
43
43
  body](../troubleshooting.md#406-with-an-empty-body) instead.
44
44
 
45
45
  Both IDEs run the schema's introspection and any operation against the
46
- endpoint, behind the same hooks as every other request: a guard before
46
+ endpoint, behind the same middlewares as every other request: a guard before
47
47
  the endpoint guards the page too, and a browser without a token gets the
48
48
  guard's reply. Turn the IDE off in production unless you mean to publish
49
49
  it.
@@ -128,22 +128,24 @@ default-src 'self'; script-src 'self' 'unsafe-inline' https://embeddable-sandbox
128
128
  ## With `@alxia/secure-headers`
129
129
 
130
130
  `@alxia/secure-headers` keeps a header a response already has, so the
131
- IDE's policy survives it and every other route keeps the strict one. A hook
131
+ IDE's policy survives it and every other route keeps the strict one. A middleware
132
132
  of your own that **overwrites** `Content-Security-Policy` on every
133
133
  response blocks the IDE's scripts, and the page stays blank: set it only
134
134
  when the response has none.
135
135
 
136
136
  ```ts
137
- import { alxia, withHeaders } from '@alxia/core';
137
+ import { alxia, defineMiddleware, settle, withHeaders } from '@alxia/core';
138
+
139
+ const defaultPolicy = defineMiddleware(async (ctx, next) =>
140
+ withHeaders(await settle(ctx, next()), (headers) => {
141
+ if (!headers.has('content-security-policy'))
142
+ headers.set('content-security-policy', "default-src 'self'");
143
+ }),
144
+ );
138
145
 
139
146
  const app = alxia()
140
- .onResponse((response) =>
141
- withHeaders(response, (headers) => {
142
- if (!headers.has('content-security-policy'))
143
- headers.set('content-security-policy', "default-src 'self'");
144
- }),
145
- )
146
- .use((app) => graphql(app, { schema }));
147
+ .use(defaultPolicy)
148
+ .plugin((app) => graphql(app, { schema }));
147
149
  ```
148
150
 
149
151
  ## `renderSandbox`
@@ -165,7 +167,7 @@ import { alxia } from '@alxia/core';
165
167
  import { graphql, renderSandbox, SANDBOX_POLICY } from '@alxia/graphql';
166
168
 
167
169
  const app = alxia()
168
- .use((app) => graphql(app, { schema, ide: false }))
170
+ .plugin((app) => graphql(app, { schema, ide: false }))
169
171
  .get('/explorer', ({ reply }) =>
170
172
  reply(200, renderSandbox('/graphql', { title: 'Users API' }), {
171
173
  headers: {
@@ -182,5 +184,5 @@ another server: `renderSandbox('https://api.example.com/graphql')`.
182
184
 
183
185
  ## See also
184
186
 
185
- - [Mounting the endpoint](endpoint.md): which hooks run before the page.
187
+ - [Mounting the endpoint](endpoint.md): which middlewares run before the page.
186
188
  - [Troubleshooting](../troubleshooting.md#the-ide-page-is-blank): a blank IDE page.
@@ -14,7 +14,7 @@ const schema = createSchema({
14
14
  resolvers: { Query: { hello: () => 'world' } },
15
15
  });
16
16
 
17
- const app = alxia().use((app) =>
17
+ const app = alxia().plugin((app) =>
18
18
  graphql(app, {
19
19
  schema,
20
20
  plugins: [useExecutionCancellation()], // stop resolvers when the client goes away
@@ -210,7 +210,7 @@ import { graphql } from '@alxia/graphql';
210
210
 
211
211
  const app = alxia()
212
212
  .use(cors({ origin: 'https://app.example.com', credentials: true }))
213
- .use((app) => graphql(app, { schema }));
213
+ .plugin((app) => graphql(app, { schema }));
214
214
  // OPTIONS /graphql → 204, Access-Control-Allow-Origin: https://app.example.com
215
215
  ```
216
216
 
@@ -34,6 +34,8 @@ symptom.
34
34
  **Traps**
35
35
 
36
36
  - [The endpoint answers without a guard declared after it](#the-endpoint-answers-without-a-guard-declared-after-it)
37
+ - [The logger, CORS or secure headers miss the endpoint](#the-logger-cors-or-secure-headers-miss-the-endpoint)
38
+ - [An anonymous request to a missing path is a 401](#an-anonymous-request-to-a-missing-path-is-a-401)
37
39
  - [A WebSocket client cannot connect: `Expected 101 status code`](#a-websocket-client-cannot-connect-expected-101-status-code)
38
40
  - [The IDE page is blank](#the-ide-page-is-blank)
39
41
  - [GraphiQL is served in production](#graphiql-is-served-in-production)
@@ -75,17 +77,17 @@ error TS2322: Type 'GraphQLSchemaWithContext<…>' is not assignable to type 'Gr
75
77
  ```
76
78
 
77
79
  **Why:** the schema was typed with `GraphQLContext<typeof base>`, and its
78
- resolvers read what `base`'s hooks add, but `graphql` was given an app that
79
- does not run those hooks: another app, or the endpoint declared before the
80
+ resolvers read what `base`'s middlewares add, but `graphql` was given an app that
81
+ does not run those middlewares: another app, or the endpoint declared before the
80
82
  `derive` or the guard.
81
83
 
82
84
  **Fix:** mount the endpoint on the app the schema was typed from, after its
83
- hooks ([The typed context](guide/context.md)):
85
+ middlewares ([The typed context](guide/context.md)):
84
86
 
85
87
  ```ts
86
88
  const base = alxia().use(bearer({ jwt })); // adds user
87
89
  const schema = createSchema<GraphQLContext<typeof base>>({ … });
88
- const app = base.use((app) => graphql(app, { schema })); // not alxia().use(…)
90
+ const app = base.plugin((app) => graphql(app, { schema })); // not alxia().plugin(…)
89
91
  ```
90
92
 
91
93
  **When the missing field comes from the `context` option** — `missing
@@ -121,7 +123,7 @@ createSchema<GraphQLContext<typeof base>>({ … }); // not GraphQLContext<type
121
123
  ### `Property 'viewer' does not exist on type 'YogaInitialContext'`
122
124
 
123
125
  **When:** a resolver of a schema created with `createSchema({ … })`, no type
124
- argument, reads what the app's hooks add.
126
+ argument, reads what the app's middlewares add.
125
127
 
126
128
  **Why:** an untyped schema's context is Yoga's alone. The field is there at
127
129
  runtime; its type is not.
@@ -205,7 +207,7 @@ graphql(app, { schema, path: '/gql' });
205
207
  `get('/graphql', …)` beside the endpoint.
206
208
 
207
209
  **Why:** each `graphql` call declares `GET` and `POST` at its `path`, and
208
- two endpoints with the default path collide. `use((app) => graphql(app, …))`
210
+ two endpoints with the default path collide. `plugin((app) => graphql(app, …))`
209
211
  declares the routes on the app it is called on, so calling it twice on the
210
212
  same `base` — for two variants of an app — declares them twice there.
211
213
 
@@ -213,8 +215,8 @@ same `base` — for two variants of an app — declares them twice there.
213
215
 
214
216
  ```ts
215
217
  const app = alxia()
216
- .use((app) => graphql(app, { schema }))
217
- .use((app) => graphql(app, { schema: admin, path: '/admin/graphql' }));
218
+ .plugin((app) => graphql(app, { schema }))
219
+ .plugin((app) => graphql(app, { schema: admin, path: '/admin/graphql' }));
218
220
  ```
219
221
 
220
222
  ## Responses
@@ -247,16 +249,17 @@ throw createGraphQLError('Admins only', {
247
249
  fails and the console reports a CORS error.
248
250
 
249
251
  **Why:** Yoga's CORS is off, and the app answers no `OPTIONS` without a
250
- CORS plugin.
252
+ CORS middleware.
251
253
 
252
- **Fix:** `@alxia/cors`, for the whole app ([CORS](guide/yoga.md#cors)):
254
+ **Fix:** `@alxia/cors`, given to `use` first, for the whole app: it answers a
255
+ preflight itself, before the router's 404 or 405 ([CORS](guide/yoga.md#cors)):
253
256
 
254
257
  ```ts
255
258
  import { cors } from '@alxia/cors';
256
259
 
257
260
  const app = alxia()
258
261
  .use(cors({ origin: 'https://app.example.com', credentials: true }))
259
- .use((app) => graphql(app, { schema }));
262
+ .plugin((app) => graphql(app, { schema }));
260
263
  ```
261
264
 
262
265
  ### `405 {"errors":[{"message":"Can only perform a mutation operation from a POST request."}]}`
@@ -328,19 +331,61 @@ await app.request(`/graphql?query=${encodeURIComponent('{ me }')}`, {
328
331
 
329
332
  ### The endpoint answers without a guard declared after it
330
333
 
331
- **When:** `.use((app) => graphql(app, { schema }))` comes before
334
+ **When:** `.plugin((app) => graphql(app, { schema }))` comes before
332
335
  `.use(bearer(…))` or a guarding `derive`: the endpoint answers anonymous
333
336
  requests, and its resolvers read no `user`.
334
337
 
335
- **Why:** a route hook applies to the routes declared after it. The endpoint
336
- is a route, declared where `graphql` is called. A schema typed from the
338
+ **Why:** a middleware applies to the routes declared after it. The endpoint
339
+ is a route, declared where `graphql` is called, so a middleware given to `use`
340
+ after it never runs for it. A schema typed from the
337
341
  guarded app is refused (`missing user`); an untyped one is not.
338
342
 
339
343
  **Fix:** declare the guard first:
340
344
 
341
345
  ```ts
342
346
  const base = alxia().use(bearer({ jwt }));
343
- const app = base.use((app) => graphql(app, { schema }));
347
+ const app = base.plugin((app) => graphql(app, { schema }));
348
+ ```
349
+
350
+ ### The logger, CORS or secure headers miss the endpoint
351
+
352
+ **When:** `use(logger())`, `use(cors(…))` or `use(secureHeaders())` comes
353
+ after `.plugin((app) => graphql(app, { schema }))`: the endpoint is not
354
+ logged, its responses carry no CORS or security headers.
355
+
356
+ **Why:** a `use` middleware runs on the routes declared after it, and on a
357
+ request no route matches. The endpoint is declared before it.
358
+
359
+ **Fix:** give the observers to `use` first:
360
+
361
+ ```ts
362
+ const app = alxia()
363
+ .use(logger())
364
+ .use(cors({ origin: 'https://app.example.com' }))
365
+ .plugin((app) => graphql(app, { schema }));
366
+ ```
367
+
368
+ ### An anonymous request to a missing path is a 401
369
+
370
+ **When:** `use(bearer(…))` is on the app, and `GET /nope` answers
371
+ `401` rather than `404`.
372
+
373
+ **Why:** a guard given to the app's `use` runs on every request, a request
374
+ no route matches included, and answers before the 404.
375
+
376
+ **Fix:** scope the guard to what it guards, with a `group`. A path-scoped
377
+ `use('/graphql', bearer(…))` does not compile: a middleware given a path may
378
+ add nothing to the context, and `bearer` adds `user`.
379
+
380
+ ```ts
381
+ const app = alxia()
382
+ .get('/health', ({ reply }) => reply(200, 'ok'))
383
+ .group('/api', (api) =>
384
+ api
385
+ .use(bearer({ jwt }))
386
+ .plugin((app) => graphql(app, { schema })), // /api/graphql: a 401 without a token
387
+ );
388
+ // GET /nope → 404, GET /api/nope → 404
344
389
  ```
345
390
 
346
391
  ### A WebSocket client cannot connect: `Expected 101 status code`
@@ -367,7 +412,7 @@ graphql(app, { schema, graphiql: { subscriptionsProtocol: 'SSE' } });
367
412
  console reports scripts refused by the `Content-Security-Policy`.
368
413
 
369
414
  **Why:** the endpoint sends the IDE with a policy that lets it load its
370
- scripts from `unpkg.com` or Apollo's CDN. A hook of the app that sets its
415
+ scripts from `unpkg.com` or Apollo's CDN. A middleware of the app that sets its
371
416
  own `Content-Security-Policy` on every response replaces it.
372
417
  `@alxia/secure-headers` does not: it keeps a policy a response already has.
373
418
 
@@ -375,12 +420,14 @@ own `Content-Security-Policy` on every response replaces it.
375
420
  ([With `@alxia/secure-headers`](guide/ide.md#with-alxiasecure-headers)):
376
421
 
377
422
  ```ts
378
- app.onResponse((response) =>
379
- withHeaders(response, (headers) => {
423
+ const defaultPolicy = defineMiddleware(async (ctx, next) =>
424
+ withHeaders(await settle(ctx, next()), (headers) => {
380
425
  if (!headers.has('content-security-policy'))
381
426
  headers.set('content-security-policy', "default-src 'self'");
382
427
  }),
383
428
  );
429
+
430
+ app.use(defaultPolicy); // before the endpoint, so it wraps it
384
431
  ```
385
432
 
386
433
  ### GraphiQL is served in production
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alxia/graphql",
3
- "version": "0.1.1",
3
+ "version": "0.2.0",
4
4
  "description": "GraphQL for alxia with GraphQL Yoga: its plugins, subscriptions over SSE and GraphiQL, behind the app's hooks, its resolvers reading the app's typed context",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -41,13 +41,13 @@
41
41
  ]
42
42
  },
43
43
  "devDependencies": {
44
- "@alxia/core": "^0.2.0",
44
+ "@alxia/core": "^0.4.0",
45
45
  "@types/bun": "^1.4.2",
46
46
  "graphql": "^16.11.0",
47
47
  "graphql-yoga": "^5.16.0"
48
48
  },
49
49
  "peerDependencies": {
50
- "@alxia/core": "^0.2.0",
50
+ "@alxia/core": "^0.4.0",
51
51
  "graphql": "^16.11.0 || ^17.0.0",
52
52
  "graphql-yoga": "^5.16.0",
53
53
  "typescript": "^6.0.3 || ^7.0.0"