@btravstack/graphql-server 0.0.0-stage → 0.21.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benoit TRAVERS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,18 @@
-# Temporary Holding Version
+# @btravstack/graphql-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A GraphQL Yoga answerer for the protocol-neutral
+[`@btravstack/http-server`](../http-server) runtime. Supply any
+`GraphQLSchema`; the package has required GraphQL and Yoga peers and no oRPC
+server dependency. `graphql(defineAuth(), { schema })` contributes a
+`HttpHandler` member. A request-scoped unit and the Node incoming request are
+available to resolvers.
+Pass `units` with `unit` to check each injected port against the module the
+selected request kind actually forks. Pass the same `units` record to
+`httpServer({ unit: units })` so the runtime can apply unit test overrides.
+Yoga plugins and CORS policy are explicit
+options; the wildcard CORS default and Yoga console logging are disabled.
+Preflights use Yoga's CORS policy before authentication, and Yoga plugins are
+disposed when the application stops.
+
+See [Serve GraphQL](https://btravstack.github.io/btravstack/how-to/serve-graphql)
+and the [separate GraphQL gateway](../../examples/order-graphql-api).

package/dist/index.cjs

@@ -0,0 +1,87 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _btravstack_di = require("@btravstack/di");
+let _btravstack_http_server_internal = require("@btravstack/http-server/internal");
+let graphql_yoga = require("graphql-yoga");
+let unthrown = require("unthrown");
+//#region src/graphql.ts
+const dispose = Symbol("graphql.dispose");
+const graphql = (api, options) => {
+	const mount = options.prefix ?? "/graphql";
+	let end = mount.length;
+	while (end > 1 && mount.charCodeAt(end - 1) === 47) end--;
+	const prefix = mount.slice(0, end);
+	const requirements = options.requires;
+	const schemes = [...new Set(requirements?.flatMap((requirement) => Object.keys(requirement)) ?? [])];
+	const typed = _btravstack_di.Provider.member(_btravstack_http_server_internal.HttpHandler)({
+		inject: {
+			config: _btravstack_http_server_internal.HttpConfig,
+			units: _btravstack_http_server_internal.HttpUnit,
+			...(0, _btravstack_http_server_internal.schemeDeps)(schemes)
+		},
+		sync: (services) => {
+			const config = services.config;
+			const units = services.units;
+			if (options.units !== void 0) {
+				for (const kind of requirements === void 0 ? ["anonymous"] : schemes) if ((options.units[kind] ?? options.units["anonymous"]) !== (units[kind] ?? units["anonymous"])) throw new Error(`[graphql-server] unit kind ${JSON.stringify(kind)} differs from HttpUnit`);
+			}
+			const authenticators = (0, _btravstack_http_server_internal.schemeServices)(schemes, services);
+			const yoga = (0, graphql_yoga.createYoga)({
+				schema: options.schema,
+				graphqlEndpoint: prefix,
+				cors: options.cors ?? (config.corsOrigin === "" ? false : { origin: config.corsOrigin.split(",").map((origin) => origin.trim()) }),
+				plugins: [{ onRequest: ({ serverContext, fetchAPI, endResponse }) => {
+					if (serverContext.refusalStatus !== void 0) endResponse(new fetchAPI.Response(null, { status: serverContext.refusalStatus }));
+				} }, ...options.plugins ?? []],
+				logging: false,
+				graphiql: false,
+				landingPage: false,
+				multipart: false,
+				maxRequestBodySize: config.bodyLimit === 0 ? false : config.bodyLimit,
+				disposeOnProcessTerminate: false
+			});
+			return {
+				prefix,
+				handle: async (request, response, signal, host) => {
+					if (request.method === "OPTIONS" && request.headers["access-control-request-method"] !== void 0) {
+						await yoga.handle(request, response, {
+							principal: void 0,
+							incoming: request,
+							unit: {},
+							signal
+						});
+						return;
+					}
+					let resolved;
+					if (requirements !== void 0) {
+						const result = await (0, _btravstack_http_server_internal.resolveScheme)(requirements, authenticators, request.headers).mapErrCases((matcher) => matcher.with(unthrown.P.tag("Unauthenticated"), () => 401).with(unthrown.P.tag("UnderScoped"), () => 403));
+						if (result.isDefect()) throw result.cause;
+						if (result.isErr()) {
+							await yoga.handle(request, response, {
+								principal: void 0,
+								incoming: request,
+								unit: {},
+								signal,
+								refusalStatus: result.error
+							});
+							return;
+						}
+						resolved = result.value;
+					}
+					const forked = await (0, _btravstack_http_server_internal.forkUnit)(host, units, api.principals, resolved, options.unit ?? {});
+					if (forked.isDefect()) throw forked.cause;
+					await yoga.handle(request, response, {
+						principal: requirements === void 0 ? void 0 : (0, _btravstack_http_server_internal.principalOf)(requirements, resolved),
+						incoming: request,
+						unit: forked.get(),
+						signal
+					});
+				},
+				[dispose]: () => yoga.dispose()
+			};
+		},
+		onStop: (answerer) => answerer[dispose]()
+	});
+	return Object.assign(typed, { authenticators: api.providers });
+};
+//#endregion
+exports.graphql = graphql;

package/dist/index.d.cts

@@ -0,0 +1,25 @@
+import { OneScheme, Requirements } from "@btravstack/contract";
+import { AnyPort, Provider, Scope } from "@btravstack/di";
+import { Authenticators, HttpAuth, HttpConfig, HttpHandler, HttpUnit, KindOf, Kinds, RequiresGate, SchemePortsOf, UnitFor, UnitsNeedsOf, UnitsOf } from "@btravstack/http-server/internal";
+import { GraphQLSchema } from "graphql";
+import { Plugin, YogaServerOptions } from "graphql-yoga";
+//#region src/graphql.d.ts
+type YogaCors = YogaServerOptions<Record<string, unknown>, Record<string, unknown>>["cors"];
+type MissingUnitPorts<U extends Readonly<Record<string, AnyPort>>, Units, K extends string> = Exclude<keyof U, keyof UnitFor<U, Units, K>>;
+type UnitGate<U extends Readonly<Record<string, AnyPort>>, Units, K extends string> = [MissingUnitPorts<U, Units, K>] extends [never] ? unknown : {
+  readonly "UNIT PORT MISSING — the selected kind does not export": MissingUnitPorts<U, Units, K>;
+};
+/** Serve a GraphQL schema as one answerer under the existing HTTP runtime. */
+type GraphqlOptions<A extends Authenticators, Units extends UnitsOf<A>, R extends Requirements & { readonly [I in keyof R]: OneScheme<R[I]>; }, U extends Readonly<Record<string, AnyPort>>> = {
+  readonly schema: GraphQLSchema;
+  readonly prefix?: `/${string}`;
+  readonly cors?: YogaCors;
+  readonly plugins?: readonly Plugin[];
+  readonly units?: Units & { readonly [K in Exclude<keyof Units, Kinds<A>>]: never; };
+  readonly unit?: U & UnitGate<U, Units, KindOf<R>>;
+  readonly requires?: R & RequiresGate<R, { readonly [K in keyof A]: A[K]["scope"]; }>;
+};
+export declare const graphql: <A extends Authenticators, Units extends UnitsOf<A> = Record<never, never>, const R extends Requirements & { readonly [I in keyof R]: OneScheme<R[I]>; } = never, U extends Readonly<Record<string, AnyPort>> = Record<never, never>>(api: HttpAuth<A>, options: GraphqlOptions<A, Units, R, U>) => Provider<HttpHandler, never, HttpConfig | HttpUnit | Scope | SchemePortsOf<R> | UnitsNeedsOf<Units>> & {
+  authenticators: readonly import("@btravstack/http-server/internal").SchemeProviders<A>[];
+};
+//#endregion

package/dist/index.d.mts

@@ -0,0 +1,25 @@
+import { AnyPort, Provider, Scope } from "@btravstack/di";
+import { Authenticators, HttpAuth, HttpConfig, HttpHandler, HttpUnit, KindOf, Kinds, RequiresGate, SchemePortsOf, UnitFor, UnitsNeedsOf, UnitsOf } from "@btravstack/http-server/internal";
+import { Plugin, YogaServerOptions } from "graphql-yoga";
+import { OneScheme, Requirements } from "@btravstack/contract";
+import { GraphQLSchema } from "graphql";
+//#region src/graphql.d.ts
+type YogaCors = YogaServerOptions<Record<string, unknown>, Record<string, unknown>>["cors"];
+type MissingUnitPorts<U extends Readonly<Record<string, AnyPort>>, Units, K extends string> = Exclude<keyof U, keyof UnitFor<U, Units, K>>;
+type UnitGate<U extends Readonly<Record<string, AnyPort>>, Units, K extends string> = [MissingUnitPorts<U, Units, K>] extends [never] ? unknown : {
+  readonly "UNIT PORT MISSING — the selected kind does not export": MissingUnitPorts<U, Units, K>;
+};
+/** Serve a GraphQL schema as one answerer under the existing HTTP runtime. */
+type GraphqlOptions<A extends Authenticators, Units extends UnitsOf<A>, R extends Requirements & { readonly [I in keyof R]: OneScheme<R[I]>; }, U extends Readonly<Record<string, AnyPort>>> = {
+  readonly schema: GraphQLSchema;
+  readonly prefix?: `/${string}`;
+  readonly cors?: YogaCors;
+  readonly plugins?: readonly Plugin[];
+  readonly units?: Units & { readonly [K in Exclude<keyof Units, Kinds<A>>]: never; };
+  readonly unit?: U & UnitGate<U, Units, KindOf<R>>;
+  readonly requires?: R & RequiresGate<R, { readonly [K in keyof A]: A[K]["scope"]; }>;
+};
+export declare const graphql: <A extends Authenticators, Units extends UnitsOf<A> = Record<never, never>, const R extends Requirements & { readonly [I in keyof R]: OneScheme<R[I]>; } = never, U extends Readonly<Record<string, AnyPort>> = Record<never, never>>(api: HttpAuth<A>, options: GraphqlOptions<A, Units, R, U>) => Provider<HttpHandler, never, HttpConfig | HttpUnit | Scope | SchemePortsOf<R> | UnitsNeedsOf<Units>> & {
+  authenticators: readonly import("@btravstack/http-server/internal").SchemeProviders<A>[];
+};
+//#endregion

package/dist/index.mjs

@@ -0,0 +1,86 @@
+import { Provider } from "@btravstack/di";
+import { HttpConfig, HttpHandler, HttpUnit, forkUnit, principalOf, resolveScheme, schemeDeps, schemeServices } from "@btravstack/http-server/internal";
+import { createYoga } from "graphql-yoga";
+import { P } from "unthrown";
+//#region src/graphql.ts
+const dispose = Symbol("graphql.dispose");
+const graphql = (api, options) => {
+	const mount = options.prefix ?? "/graphql";
+	let end = mount.length;
+	while (end > 1 && mount.charCodeAt(end - 1) === 47) end--;
+	const prefix = mount.slice(0, end);
+	const requirements = options.requires;
+	const schemes = [...new Set(requirements?.flatMap((requirement) => Object.keys(requirement)) ?? [])];
+	const typed = Provider.member(HttpHandler)({
+		inject: {
+			config: HttpConfig,
+			units: HttpUnit,
+			...schemeDeps(schemes)
+		},
+		sync: (services) => {
+			const config = services.config;
+			const units = services.units;
+			if (options.units !== void 0) {
+				for (const kind of requirements === void 0 ? ["anonymous"] : schemes) if ((options.units[kind] ?? options.units["anonymous"]) !== (units[kind] ?? units["anonymous"])) throw new Error(`[graphql-server] unit kind ${JSON.stringify(kind)} differs from HttpUnit`);
+			}
+			const authenticators = schemeServices(schemes, services);
+			const yoga = createYoga({
+				schema: options.schema,
+				graphqlEndpoint: prefix,
+				cors: options.cors ?? (config.corsOrigin === "" ? false : { origin: config.corsOrigin.split(",").map((origin) => origin.trim()) }),
+				plugins: [{ onRequest: ({ serverContext, fetchAPI, endResponse }) => {
+					if (serverContext.refusalStatus !== void 0) endResponse(new fetchAPI.Response(null, { status: serverContext.refusalStatus }));
+				} }, ...options.plugins ?? []],
+				logging: false,
+				graphiql: false,
+				landingPage: false,
+				multipart: false,
+				maxRequestBodySize: config.bodyLimit === 0 ? false : config.bodyLimit,
+				disposeOnProcessTerminate: false
+			});
+			return {
+				prefix,
+				handle: async (request, response, signal, host) => {
+					if (request.method === "OPTIONS" && request.headers["access-control-request-method"] !== void 0) {
+						await yoga.handle(request, response, {
+							principal: void 0,
+							incoming: request,
+							unit: {},
+							signal
+						});
+						return;
+					}
+					let resolved;
+					if (requirements !== void 0) {
+						const result = await resolveScheme(requirements, authenticators, request.headers).mapErrCases((matcher) => matcher.with(P.tag("Unauthenticated"), () => 401).with(P.tag("UnderScoped"), () => 403));
+						if (result.isDefect()) throw result.cause;
+						if (result.isErr()) {
+							await yoga.handle(request, response, {
+								principal: void 0,
+								incoming: request,
+								unit: {},
+								signal,
+								refusalStatus: result.error
+							});
+							return;
+						}
+						resolved = result.value;
+					}
+					const forked = await forkUnit(host, units, api.principals, resolved, options.unit ?? {});
+					if (forked.isDefect()) throw forked.cause;
+					await yoga.handle(request, response, {
+						principal: requirements === void 0 ? void 0 : principalOf(requirements, resolved),
+						incoming: request,
+						unit: forked.get(),
+						signal
+					});
+				},
+				[dispose]: () => yoga.dispose()
+			};
+		},
+		onStop: (answerer) => answerer[dispose]()
+	});
+	return Object.assign(typed, { authenticators: api.providers });
+};
+//#endregion
+export { graphql };

package/package.json

@@ -1,6 +1,77 @@
 {
   "name": "@btravstack/graphql-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.21.0",
+  "description": "The GraphQL Yoga answerer for @btravstack/http-server",
+  "keywords": [
+    "graphql",
+    "http",
+    "server",
+    "typescript"
+  ],
+  "homepage": "https://github.com/btravstack/btravstack#readme",
+  "bugs": {
+    "url": "https://github.com/btravstack/btravstack/issues"
+  },
+  "license": "MIT",
+  "author": "Benoit TRAVERS <benoit.travers.fr@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/btravstack/btravstack.git",
+    "directory": "packages/graphql-server"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@btravstack/contract": "0.21.0",
+    "@btravstack/core": "0.21.0",
+    "@btravstack/di": "0.21.0",
+    "@btravstack/http-server": "0.21.0",
+    "@btravstack/tsconfig": "0.4.0",
+    "@types/node": "26.6.4",
+    "@unthrown/vitest": "5.12.0",
+    "@vitest/coverage-v8": "5.0.3",
+    "graphql": "17.0.2",
+    "graphql-yoga": "5.24.1",
+    "tsdown": "0.23.0",
+    "typescript": "7.0.2",
+    "typescript-consumer": "npm:typescript@5.9.3",
+    "unthrown": "5.12.0",
+    "vitest": "5.0.3"
+  },
+  "peerDependencies": {
+    "@btravstack/contract": "^0.21.0",
+    "@btravstack/di": "^0.21.0",
+    "@btravstack/http-server": "^0.21.0",
+    "graphql": "^16.0.0 || ^17.0.0",
+    "graphql-yoga": "^5.24.1",
+    "unthrown": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=22.15"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsdown src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run --coverage",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test-d.json && node ./node_modules/typescript-consumer/bin/tsc --noEmit -p tsconfig.test-d.json"
+  }
 }