@nifrajs/graphql 3.2.0

package/dist/pubsub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pubsub.d.ts","sourceRoot":"","sources":["../src/pubsub.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,wGAAwG;AACxG,MAAM,WAAW,aAAa,CAAC,KAAK,GAAG,OAAO;IAC5C,wDAAwD;IACxD,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,GAAG,IAAI,CAAA;IAC5C,mGAAmG;IACnG,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAA;CACvD;AAED,iDAAiD;AACjD,wBAAgB,YAAY,CAAC,KAAK,GAAG,OAAO,KAAK,aAAa,CAAC,KAAK,CAAC,CAyBpE"}

package/dist/pubsub.js

@@ -0,0 +1,83 @@
+/**
+ * A trivial in-memory pub/sub for `subscription` resolvers - the reference implementation of the
+ * subscription source seam. A resolver's `subscribe` returns `pubsub.subscribe(topic)` (an async
+ * iterator); anything in the process calls `pubsub.publish(topic, payload)` to push an event.
+ *
+ * This is deliberately in-process and unbounded-fan-in only within one server instance - the same
+ * single-instance contract as core's `TopicRegistry`. A durable, multi-instance, or tenant-scoped
+ * pub/sub (Redis, a Durable Object, NATS) is an operated concern: implement the same
+ * `{ publish, subscribe }` shape over your bus and pass it in. Keeping only the in-memory impl here is
+ * the guardrail - a durable payload-carrying sink does not belong in a public package.
+ */
+/** Create an in-memory {@link GraphqlPubSub}. */
+export function createPubSub() {
+    const topics = new Map();
+    const publish = (topic, payload) => {
+        const sinks = topics.get(topic);
+        if (sinks === undefined)
+            return;
+        for (const sink of sinks)
+            sink.push(payload);
+    };
+    const subscribe = (topic) => {
+        let sinks = topics.get(topic);
+        if (sinks === undefined) {
+            sinks = new Set();
+            topics.set(topic, sinks);
+        }
+        const set = sinks;
+        const sink = createSink(() => {
+            set.delete(sink);
+            if (set.size === 0)
+                topics.delete(topic);
+        });
+        set.add(sink);
+        return sink.iterator;
+    };
+    return { publish, subscribe };
+}
+function createSink(onClose) {
+    const queue = [];
+    const pulls = [];
+    let done = false;
+    const push = (payload) => {
+        if (done)
+            return;
+        const pull = pulls.shift();
+        if (pull !== undefined) {
+            pull({ value: payload, done: false });
+            return;
+        }
+        queue.push(payload);
+    };
+    const finish = () => {
+        if (!done) {
+            done = true;
+            onClose();
+            for (const pull of pulls.splice(0))
+                pull({ value: undefined, done: true });
+        }
+        return { value: undefined, done: true };
+    };
+    const iterator = {
+        next() {
+            if (queue.length > 0)
+                return Promise.resolve({ value: queue.shift(), done: false });
+            if (done)
+                return Promise.resolve({ value: undefined, done: true });
+            return new Promise((resolve) => pulls.push(resolve));
+        },
+        return() {
+            return Promise.resolve(finish());
+        },
+        throw(err) {
+            finish();
+            return Promise.reject(err);
+        },
+        [Symbol.asyncIterator]() {
+            return this;
+        },
+    };
+    return { push, iterator };
+}
+//# sourceMappingURL=pubsub.js.map

package/dist/pubsub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pubsub.js","sourceRoot":"","sources":["../src/pubsub.ts"],"names":[],"mappings":"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"}

package/dist/ws.d.ts

@@ -0,0 +1,56 @@
+/**
+ * GraphQL subscriptions over nifra's native WebSocket lane, speaking the `graphql-transport-ws`
+ * protocol (the modern `graphql-ws` wire protocol). This adapts `graphql-ws`'s transport-agnostic
+ * server (`makeServer`) onto a nifra `app.ws()` route, so subscription operations run through the same
+ * socket runtime as every other nifra WebSocket - no separate socket server, no second upgrade path.
+ *
+ * `graphql-ws` owns the per-operation async-iterator lifecycle (one `subscribe` iterator per client
+ * `Subscribe` message, drained to that client's socket). The event *source* those iterators pull from
+ * is yours - typically a {@link ./pubsub.ts | GraphqlPubSub}, whose in-memory reference impl mirrors
+ * core's `TopicRegistry` and can be swapped for a durable bus without touching this transport.
+ *
+ * `graphql-ws` is an optional peer dependency: import this module only when you need subscriptions, and
+ * the dependency (and its bundle weight) stays off every app that doesn't.
+ */
+import type { WebSocketHandler } from "@nifrajs/core/ws";
+import { type GraphQLSchema } from "graphql";
+import { type ConnectionInitMessage, type ServerOptions } from "graphql-ws";
+import { type GraphqlContextBuilder } from "./context.js";
+/** Per-connection state carried on `ws.data` for the graphql-ws bridge. */
+interface GraphqlWsConnection {
+    readonly request: Request;
+    /** Feed one raw inbound frame into graphql-ws (registered via its `onMessage`). */
+    dispatch?: (message: string) => void | Promise<void>;
+    /** Tear the graphql-ws connection down (graphql-ws's `opened()` return value). */
+    closed?: (code: number, reason: string) => void | Promise<void>;
+}
+export interface GraphqlWsOptions<Context extends Record<string, unknown> = Record<string, unknown>> {
+    /** The executable schema. */
+    readonly schema: GraphQLSchema;
+    /** Build the resolver `contextValue` from the upgrade request. Shared with the HTTP transport. */
+    readonly context?: GraphqlContextBuilder<Context>;
+    /**
+     * Called once per connection with the client's `connection_init` payload; return `false` (or throw)
+     * to reject the connection. The seam for authenticating a socket from an init token.
+     */
+    readonly onConnect?: (payload: ConnectionInitMessage["payload"], request: Request) => boolean | Promise<boolean>;
+    /** Additional raw `graphql-ws` server options merged last (advanced escape hatch). */
+    readonly serverOptions?: Partial<ServerOptions>;
+}
+/**
+ * Build a nifra {@link WebSocketHandler} that terminates the `graphql-transport-ws` protocol. Register
+ * it on a route enabled with `.use(websocket())`:
+ *
+ * ```ts
+ * import { websocket } from "@nifrajs/core/ws"
+ * import { graphqlWebSocket } from "@nifrajs/graphql/ws"
+ *
+ * const app = server().use(websocket()).ws("/graphql", graphqlWebSocket({ schema, context }))
+ * ```
+ *
+ * The route MUST negotiate the `graphql-transport-ws` subprotocol at the WebSocket layer for a browser
+ * `graphql-ws` client to connect.
+ */
+export declare function graphqlWebSocket<Context extends Record<string, unknown> = Record<string, unknown>>(options: GraphqlWsOptions<Context>): WebSocketHandler<GraphqlWsConnection>;
+export {};
+//# sourceMappingURL=ws.d.ts.map

package/dist/ws.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.d.ts","sourceRoot":"","sources":["../src/ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAoC,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAC1F,OAAO,EAAW,KAAK,aAAa,EAAa,MAAM,SAAS,CAAA;AAChE,OAAO,EACL,KAAK,qBAAqB,EAI1B,KAAK,aAAa,EACnB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAgB,KAAK,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAEvE,2EAA2E;AAC3E,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACpD,kFAAkF;IAClF,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAChE;AAED,MAAM,WAAW,gBAAgB,CAC/B,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAEjE,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B,kGAAkG;IAClG,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC,OAAO,CAAC,CAAA;IACjD;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CACnB,OAAO,EAAE,qBAAqB,CAAC,SAAS,CAAC,EACzC,OAAO,EAAE,OAAO,KACb,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC/B,sFAAsF;IACtF,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAA;CAChD;AAOD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChG,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC,GACjC,gBAAgB,CAAC,mBAAmB,CAAC,CA4DvC"}

package/dist/ws.js

@@ -0,0 +1,85 @@
+/**
+ * GraphQL subscriptions over nifra's native WebSocket lane, speaking the `graphql-transport-ws`
+ * protocol (the modern `graphql-ws` wire protocol). This adapts `graphql-ws`'s transport-agnostic
+ * server (`makeServer`) onto a nifra `app.ws()` route, so subscription operations run through the same
+ * socket runtime as every other nifra WebSocket - no separate socket server, no second upgrade path.
+ *
+ * `graphql-ws` owns the per-operation async-iterator lifecycle (one `subscribe` iterator per client
+ * `Subscribe` message, drained to that client's socket). The event *source* those iterators pull from
+ * is yours - typically a {@link ./pubsub.ts | GraphqlPubSub}, whose in-memory reference impl mirrors
+ * core's `TopicRegistry` and can be swapped for a durable bus without touching this transport.
+ *
+ * `graphql-ws` is an optional peer dependency: import this module only when you need subscriptions, and
+ * the dependency (and its bundle weight) stays off every app that doesn't.
+ */
+import { execute, subscribe } from "graphql";
+import { GRAPHQL_TRANSPORT_WS_PROTOCOL, makeServer, } from "graphql-ws";
+import { buildContext } from "./context.js";
+/** A frame is a string for JSON control messages; graphql-ws only speaks text frames. */
+function asText(data) {
+    return typeof data === "string" ? data : new TextDecoder().decode(data);
+}
+/**
+ * Build a nifra {@link WebSocketHandler} that terminates the `graphql-transport-ws` protocol. Register
+ * it on a route enabled with `.use(websocket())`:
+ *
+ * ```ts
+ * import { websocket } from "@nifrajs/core/ws"
+ * import { graphqlWebSocket } from "@nifrajs/graphql/ws"
+ *
+ * const app = server().use(websocket()).ws("/graphql", graphqlWebSocket({ schema, context }))
+ * ```
+ *
+ * The route MUST negotiate the `graphql-transport-ws` subprotocol at the WebSocket layer for a browser
+ * `graphql-ws` client to connect.
+ */
+export function graphqlWebSocket(options) {
+    const gqlServer = makeServer({
+        schema: options.schema,
+        execute,
+        subscribe,
+        onConnect: options.onConnect
+            ? async (ctx) => {
+                return await options.onConnect?.(ctx.connectionParams, ctx.extra.request);
+            }
+            : undefined,
+        context: options.context
+            ? async (ctx) => await buildContext(options.context, { request: ctx.extra.request })
+            : undefined,
+        ...options.serverOptions,
+    });
+    return {
+        upgrade(c) {
+            return { request: c.req };
+        },
+        open(ws) {
+            const protocol = ws.raw?.protocol ?? GRAPHQL_TRANSPORT_WS_PROTOCOL;
+            let onFrame;
+            const closed = gqlServer.opened({
+                protocol,
+                send: async (data) => {
+                    ws.send(data);
+                },
+                close: (code, reason) => {
+                    ws.close(code, reason);
+                },
+                onMessage: (cb) => {
+                    onFrame = cb;
+                },
+            }, { request: ws.data.request });
+            ws.data.closed = closed;
+            ws.data.dispatch = (message) => onFrame?.(message);
+        },
+        message(ws, data) {
+            // Fire-and-forget: graphql-ws's per-message handler does not resolve until a subscription's
+            // iterator completes (`await for await`), so awaiting it here would block every later frame on
+            // this socket - including the client's `Complete` that stops the subscription. graphql-ws drives
+            // its own sends and error frames from inside that loop; we only feed it inbound frames.
+            void ws.data.dispatch?.(asText(data));
+        },
+        close(ws, code, reason) {
+            void ws.data.closed?.(code, reason);
+        },
+    };
+}
+//# sourceMappingURL=ws.js.map

package/dist/ws.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.js","sourceRoot":"","sources":["../src/ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,OAAO,EAAsB,SAAS,EAAE,MAAM,SAAS,CAAA;AAChE,OAAO,EAEL,6BAA6B,EAE7B,UAAU,GAEX,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,YAAY,EAA8B,MAAM,cAAc,CAAA;AA8BvE,yFAAyF;AACzF,SAAS,MAAM,CAAC,IAAyB;IACvC,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;AACzE,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAkC;IAElC,MAAM,SAAS,GAAG,UAAU,CAAgD;QAC1E,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,OAAO;QACP,SAAS;QACT,SAAS,EAAE,OAAO,CAAC,SAAS;YAC1B,CAAC,CAAC,KAAK,EAAE,GAAoE,EAAE,EAAE;gBAC7E,OAAO,MAAM,OAAO,CAAC,SAAS,EAAE,CAC9B,GAAG,CAAC,gBAAoD,EACxD,GAAG,CAAC,KAAK,CAAC,OAAO,CAClB,CAAA;YACH,CAAC;YACH,CAAC,CAAC,SAAS;QACb,OAAO,EAAE,OAAO,CAAC,OAAO;YACtB,CAAC,CAAC,KAAK,EAAE,GAAoE,EAAE,EAAE,CAC7E,MAAM,YAAY,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;YACvE,CAAC,CAAC,SAAS;QACb,GAAG,OAAO,CAAC,aAAa;KACzB,CAAC,CAAA;IAEF,OAAO;QACL,OAAO,CAAC,CAAmB;YACzB,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,GAAG,EAAE,CAAA;QAC3B,CAAC;QAED,IAAI,CAAC,EAAuC;YAC1C,MAAM,QAAQ,GACX,EAAE,CAAC,GAAyC,EAAE,QAAQ,IAAI,6BAA6B,CAAA;YAC1F,IAAI,OAAgE,CAAA;YACpE,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAC7B;gBACE,QAAQ;gBACR,IAAI,EAAE,KAAK,EAAE,IAAY,EAAE,EAAE;oBAC3B,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;gBACf,CAAC;gBACD,KAAK,EAAE,CAAC,IAAY,EAAE,MAAc,EAAE,EAAE;oBACtC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;gBACxB,CAAC;gBACD,SAAS,EAAE,CAAC,EAAE,EAAE,EAAE;oBAChB,OAAO,GAAG,EAAE,CAAA;gBACd,CAAC;aACF,EACD,EAAE,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAC7B,CAAA;YACD,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;YACvB,EAAE,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,OAAe,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAA;QAC5D,CAAC;QAED,OAAO,CAAC,EAAuC,EAAE,IAAyB;YACxE,4FAA4F;YAC5F,+FAA+F;YAC/F,iGAAiG;YACjG,wFAAwF;YACxF,KAAK,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;QACvC,CAAC;QAED,KAAK,CAAC,EAAuC,EAAE,IAAY,EAAE,MAAc;YACzE,KAAK,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;QACrC,CAAC;KACF,CAAA;AACH,CAAC"}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@nifrajs/graphql",
+  "version": "3.2.0",
+  "description": "Mount a GraphQL endpoint on a nifra app - a spec-compliant GraphQL-over-HTTP handler you mount at POST /graphql, graphql-ws subscriptions over nifra's native WebSocket lane, and typed nifra context piped straight into your resolvers. Uses graphql's own execute/subscribe; no server framework re-bundled.",
+  "keywords": [
+    "bun",
+    "typescript",
+    "nifra",
+    "graphql",
+    "graphql-http",
+    "graphql-ws",
+    "subscriptions",
+    "resolvers",
+    "api"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./http": {
+      "bun": "./src/http.ts",
+      "types": "./dist/http.d.ts",
+      "default": "./dist/http.js"
+    },
+    "./ws": {
+      "bun": "./src/ws.ts",
+      "types": "./dist/ws.d.ts",
+      "default": "./dist/ws.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun run ../../scripts/fix-dts.ts dist"
+  },
+  "peerDependencies": {
+    "@nifrajs/core": "^3.2.0",
+    "graphql": "^17.0.0",
+    "graphql-ws": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@nifrajs/core": {
+      "optional": true
+    },
+    "graphql-ws": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nifrajs/core": "workspace:*",
+    "graphql": "17.0.2",
+    "graphql-ws": "6.2.1"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nifrajs/nifra.git",
+    "directory": "packages/graphql"
+  },
+  "bugs": {
+    "url": "https://github.com/nifrajs/nifra/issues"
+  },
+  "homepage": "https://github.com/nifrajs/nifra#readme"
+}

package/src/context.ts

@@ -0,0 +1,56 @@
+/**
+ * The context-injection seam - the one thing a hand-rolled `app.all('/graphql', yoga.fetch)` mount
+ * cannot do. A GraphQL executor builds an opaque `contextValue` from the raw `Request`; it never sees
+ * the nifra request context (auth subject, params, env, `waitUntil`). This contract lets a resolver's
+ * `contextValue` be derived from whatever the surrounding nifra handler already resolved.
+ *
+ * The builder is called once per operation (per HTTP request, or once per WS `Subscribe` message),
+ * before `execute`/`subscribe`. It receives the raw `Request` and, on the HTTP path, the nifra route
+ * context `c` when the endpoint is mounted with `mountGraphql` (which has `c` in scope); on the WS path
+ * it receives the upgrade request. Return the object your resolvers read as their third argument.
+ *
+ * MOAT NOTE: this seam only *passes through* context the host already owns. It never persists it. A
+ * tenant-aware or durable resolver-context store is an operated concern and lives outside this package.
+ */
+
+/** What the builder is handed. `request` is always present; `nifra` is the route context when known. */
+export interface GraphqlContextInput<Env = unknown> {
+  readonly request: Request
+  /**
+   * The nifra route context (`c`) when the endpoint was mounted via `mountGraphql`, otherwise
+   * `undefined` (e.g. `respondGraphql` called standalone, or the WS transport before a route context
+   * exists). Typed loosely on purpose so this package never imports core's context type at the value
+   * level - keeping the peer dependency truly optional.
+   */
+  readonly nifra?: NifraContextLike<Env>
+}
+
+/**
+ * The subset of a nifra route context this package surfaces to a resolver-context builder. Structural,
+ * so the real `c` satisfies it without a nominal import. Kept to the non-body accessors a resolver
+ * legitimately needs; the raw body belongs to the GraphQL executor, not the builder.
+ */
+export interface NifraContextLike<Env = unknown> {
+  readonly req: Request
+  readonly params: Record<string, string>
+  readonly env: Env
+  readonly signal: AbortSignal
+  readonly waitUntil: (promise: Promise<unknown>) => void
+}
+
+/**
+ * Build the resolver `contextValue` for one operation. Sync or async; a throw is reported as a GraphQL
+ * error envelope rather than crashing the transport. Omit it and resolvers get `contextValue: {}`.
+ */
+export type GraphqlContextBuilder<Context = unknown, Env = unknown> = (
+  input: GraphqlContextInput<Env>,
+) => Context | Promise<Context>
+
+/** Resolve a context builder to a concrete value, defaulting to an empty object. */
+export async function buildContext<Context, Env>(
+  builder: GraphqlContextBuilder<Context, Env> | undefined,
+  input: GraphqlContextInput<Env>,
+): Promise<Context> {
+  if (builder === undefined) return {} as Context
+  return await builder(input)
+}