@bhooai/nexus-graphql 0.1.0

package/src/gateway/createGateway.ts

@@ -0,0 +1,77 @@
+import { execute, subscribe, validate, type GraphQLSchema, type ExecutionResult, type DocumentNode } from 'graphql';
+import type { Gateway, Subgraph, Resolvers, GraphQLContext, ExecuteParams } from '../types.js';
+import { createFieldResolver, createSubscribeFieldResolver } from './fieldResolver.js';
+import { buildPublicSchema } from './publicSchema.js';
+
+/**
+ * Create an in-process gateway over one or more subgraphs.
+ *
+ * Single-subgraph mode (Phase 5): the gateway exposes the subgraph's public
+ * schema and executes operations directly against the subgraph's resolvers —
+ * no network hop, shared in-process context (DB pool, services). This is the
+ * default app shape; federation overhead only kicks in when there are multiple
+ * subgraphs.
+ *
+ * Multi-subgraph composition + query planning is Phase 6; calling with >1
+ * subgraph here throws a clear "not yet" error so the API is forward-compatible.
+ */
+export function createGateway(input: { subgraph: Subgraph } | { subgraphs: Subgraph[] }): Gateway {
+  const subgraphs: Subgraph[] = 'subgraph' in input ? [input.subgraph] : input.subgraphs;
+  if (subgraphs.length === 0) throw new Error('[nexus-graphql] createGateway requires at least one subgraph');
+  if (subgraphs.length > 1) {
+    throw new Error(
+      '[nexus-graphql] Multi-subgraph federation (composition + query planning) is implemented in Phase 6. ' +
+        'Pass a single subgraph here, or use the Phase 6 composeSupergraph/createFederatedGateway.',
+    );
+  }
+
+  const only = subgraphs[0]!;
+  const resolvers: Resolvers = only.resolvers;
+  const schema: GraphQLSchema = buildPublicSchema(only.sdl);
+  const fieldResolver = createFieldResolver(resolvers);
+  const subscribeFieldResolver = createSubscribeFieldResolver(resolvers);
+
+  async function run(document: DocumentNode, params: Omit<ExecuteParams, 'schema' | 'resolvers' | 'document'>) {
+    const errors = validate(schema, document);
+    if (errors.length) return ({ errors: errors.map((e) => ({ message: e.message })) } as unknown) as ExecutionResult;
+    return execute({
+      schema,
+      document,
+      rootValue: params.rootValue,
+      contextValue: params.contextValue as GraphQLContext,
+      variableValues: params.variableValues,
+      operationName: params.operationName,
+      fieldResolver,
+    });
+  }
+
+  return {
+    schema,
+    subgraphs,
+    async execute(params) {
+      return run(params.document, params);
+    },
+    async subscribe(params) {
+      const document = params.document;
+      const errors = validate(schema, document);
+      if (errors.length) {
+        return (async function* () { yield { errors: errors.map((e) => ({ message: e.message })) }; })() as AsyncIterable<ExecutionResult>;
+      }
+      const result = await subscribe({
+        schema,
+        document,
+        rootValue: params.rootValue,
+        contextValue: params.contextValue as GraphQLContext,
+        variableValues: params.variableValues,
+        operationName: params.operationName,
+        subscribeFieldResolver,
+        fieldResolver,
+      });
+      // graphql-js returns an AsyncIterable on success or an ExecutionResult (with errors) otherwise.
+      if (Symbol.asyncIterator in (result as any)) {
+        return result as AsyncIterable<ExecutionResult>;
+      }
+      return (async function* () { yield result as ExecutionResult; })() as AsyncIterable<ExecutionResult>;
+    },
+  };
+}

package/src/gateway/fieldResolver.ts

@@ -0,0 +1,45 @@
+import type { GraphQLFieldResolver, GraphQLResolveInfo } from 'graphql';
+import type { Resolvers, GraphQLContext, SubscribeResolver } from '../types.js';
+
+/**
+ * Build a graphql-js `fieldResolver` that dispatches to the user's resolvers
+ * map. Resolution order:
+ *   1. `__typename` → the parent's `__typename` (or the field's parent type name).
+ *   2. `resolvers[typeName][fieldName]` — if it's a `{ resolve, subscribe }`
+ *      shape (subscription field), use `.resolve`; otherwise call it directly.
+ *   3. Default property access: `parent[fieldName]`.
+ */
+export function createFieldResolver(resolvers: Resolvers): GraphQLFieldResolver<any, GraphQLContext> {
+  return (parent, args, context, info: GraphQLResolveInfo) => {
+    const fieldName = info.fieldName;
+    if (fieldName === '__typename') {
+      return parent?.__typename ?? info.parentType.name;
+    }
+    const typeResolvers = resolvers[info.parentType.name];
+    if (typeResolvers) {
+      const field = typeResolvers[fieldName];
+      if (field) {
+        if (typeof field === 'function') return field(parent, args, context, info);
+        if (typeof field === 'object' && field && typeof field.resolve === 'function') {
+          return field.resolve(parent, args, context, info);
+        }
+      }
+    }
+    // Default: read the property off the parent (works for DB docs/objects).
+    return parent != null ? parent[fieldName] : undefined;
+  };
+}
+
+/** Build a `subscribeFieldResolver` for subscription root fields. */
+export function createSubscribeFieldResolver(resolvers: Resolvers): GraphQLFieldResolver<any, GraphQLContext> {
+  return (parent, args, context, info: GraphQLResolveInfo): AsyncIterable<any> | Promise<AsyncIterable<any>> => {
+    const typeResolvers = resolvers[info.parentType.name];
+    const field = typeResolvers?.[info.fieldName];
+    const subscribe: SubscribeResolver | undefined =
+      field && typeof field === 'object' && field ? field.subscribe : undefined;
+    if (typeof subscribe !== 'function') {
+      throw new Error(`No 'subscribe' resolver for ${info.parentType.name}.${info.fieldName}`);
+    }
+    return subscribe(parent, args, context, info);
+  };
+}

package/src/gateway/graphqlHttpHandler.ts

@@ -0,0 +1,90 @@
+import { parse, type DocumentNode } from 'graphql';
+import type { RequestContext, Handler } from '@bhooai/nexus-core';
+import type { Gateway, GraphQLContext } from '../types.js';
+
+export interface GraphqlHandlerOptions {
+  /** The gateway to execute against. */
+  gateway: Gateway;
+  /** Build the per-request resolver context. Defaults to `{ request: ctx, user: ctx.state.user }`. */
+  context?: (ctx: RequestContext) => GraphQLContext | Promise<GraphQLContext>;
+  /** Allow introspection queries (default follows config.graphql.introspection = true). */
+  introspection?: boolean;
+}
+
+interface GraphQLRequestBody {
+  query?: string;
+  variables?: Record<string, any>;
+  operationName?: string;
+}
+
+/** True when a parsed operation set contains an introspection field (`__schema`/`__type`). */
+function isIntrospectionDocument(doc: DocumentNode): boolean {
+  for (const def of doc.definitions) {
+    if (def.kind === 'OperationDefinition') {
+      const sels = def.selectionSet.selections;
+      for (const s of sels) {
+        if (s.kind === 'Field' && (s.name.value === '__schema' || s.name.value === '__type')) return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * HTTP handler for `/graphql`. Accepts POST with `{ query, variables, operationName }`
+ * (or GET with `?query=`). Applies the gateway in-process. Introspection is
+ * rejected when disabled.
+ */
+export function graphqlHttpHandler(options: GraphqlHandlerOptions): Handler {
+  const { gateway, introspection = true } = options;
+  return async (ctx: RequestContext) => {
+    let body: GraphQLRequestBody;
+    if (ctx.method === 'GET') {
+      const q = ctx.query.query;
+      body = { query: Array.isArray(q) ? q[0] : q, variables: parseJsonQuery(ctx.query.variables), operationName: single(ctx.query.operationName) };
+    } else {
+      body = (ctx.body as GraphQLRequestBody) ?? {};
+    }
+
+    if (!body.query) {
+      ctx.json({ errors: [{ message: 'Must provide a query string.' }] }, 400);
+      return;
+    }
+
+    let document: DocumentNode;
+    try {
+      document = parse(body.query);
+    } catch (err) {
+      ctx.json({ errors: [{ message: (err as Error).message }] }, 400);
+      return;
+    }
+
+    if (!introspection && isIntrospectionDocument(document)) {
+      ctx.json({ errors: [{ message: 'Introspection is disabled.' }] }, 403);
+      return;
+    }
+
+    const contextValue = options.context
+      ? await options.context(ctx)
+      : { request: ctx, user: (ctx.state.user as GraphQLContext['user']) };
+
+    const result = await gateway.execute({
+      document,
+      variableValues: body.variables,
+      operationName: body.operationName,
+      contextValue,
+    });
+    ctx.json(result);
+  };
+}
+
+function parseJsonQuery(v: string | string[] | undefined): Record<string, any> | undefined {
+  if (v === undefined) return undefined;
+  const s = Array.isArray(v) ? v[0] : v;
+  if (!s) return undefined;
+  try { return JSON.parse(s as string); } catch { return undefined; }
+}
+function single(v: string | string[] | undefined): string | undefined {
+  if (v === undefined) return undefined;
+  return Array.isArray(v) ? v[0] : v;
+}

package/src/gateway/publicSchema.ts

@@ -0,0 +1,26 @@
+import { buildSchema, GraphQLSchema } from 'graphql';
+
+/**
+ * Strip federation directives from subgraph SDL to produce the *public*
+ * (client-facing) schema. The gateway exposes this clean schema; the federation
+ * internals (`_service`, `_entities`, `@key`, `@external`, ...) are not part of
+ * the public API. For the single-subgraph case the public schema is simply the
+ * user's types without the federation markers.
+ */
+export function buildPublicSchema(subgraphSdl: string): GraphQLSchema {
+  const cleaned = subgraphSdl
+    // Drop the `extend schema @link(...)` clause and any standalone @link.
+    .replace(/extend\s+schema\s*@\s*link\s*\([^)]*\)/g, '')
+    .replace(/@\s*link\s*\([^)]*\)/g, '')
+    // Drop federation field/type directives.
+    .replace(/@\s*key\s*\([^)]*\)/g, '')
+    .replace(/@\s*requires\s*\([^)]*\)/g, '')
+    .replace(/@\s*provides\s*\([^)]*\)/g, '')
+    .replace(/@\s*external\b/g, '')
+    .replace(/@\s*extends\b/g, '')
+    // Collapse multiple blank lines left behind.
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+
+  return buildSchema(cleaned);
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export * from './types.js';
+export * from './subgraph/federationDirectives.js';
+export * from './subgraph/parseKeys.js';
+export * from './subgraph/defineSubgraph.js';
+export * from './gateway/fieldResolver.js';
+export * from './gateway/publicSchema.js';
+export * from './gateway/createGateway.js';
+export * from './gateway/graphqlHttpHandler.js';
+export * from './subscriptions/PubSub.js';
+export * from './subscriptions/SubscriptionServer.js';
+export * from './federation/parseMetadata.js';
+export * from './federation/composeSupergraph.js';
+export * from './federation/executor.js';
+export * from './federation/createFederatedGateway.js';

package/src/subgraph/defineSubgraph.ts

@@ -0,0 +1,115 @@
+import { buildSchema, parse, validate, GraphQLSchema } from 'graphql';
+import type { DefineSubgraphOptions, Subgraph, Resolvers, GraphQLContext, EntityRepresentation, EntityResolver } from '../types.js';
+import { FEDERATION_DIRECTIVE_SDL, FEDERATION_LINK, FEDERATION_TYPES, entityUnionSdl } from './federationDirectives.js';
+import { parseEntityKeys } from './parseKeys.js';
+import { createFieldResolver } from '../gateway/fieldResolver.js';
+
+const DEFAULT_ENTITY_RESOLVER: EntityResolver = (rep) => rep;
+
+/**
+ * Define a federation-compliant subgraph from user typeDefs + resolvers.
+ *
+ * The user SDL may use federation directives (`@key`, `@external`, `@requires`,
+ * `@provides`, `@extends`). We prepend the directive definitions + the `@link`
+ * clause and append the federation boilerplate (`_Any`, `_Entity`, `_Service`,
+ * `Query._service`, `Query._entities`) so the resulting schema is a valid
+ * subgraph: `_service.sdl` returns the subgraph SDL and `_entities` resolves
+ * representations via the provided `entityResolver` (default: pass-through).
+ *
+ * `defineSubgraph` does NOT compose — it produces a single executable subgraph.
+ * The gateway (`createGateway`) executes it in-process for the single-subgraph
+ * case; Phase 6 composes multiple subgraphs.
+ */
+export function defineSubgraph(options: DefineSubgraphOptions): Subgraph {
+  const { name, typeDefs, resolvers = {}, entityResolver = DEFAULT_ENTITY_RESOLVER } = options;
+
+  const entityKeys = parseEntityKeys(typeDefs);
+  const entityUnion = entityUnionSdl([...entityKeys.keys()]);
+
+  // Subgraph SDL = what _service.sdl returns: the user SDL + the @link clause.
+  // (We keep the federation directives in the published SDL — that's the point.)
+  const sdl = `${FEDERATION_LINK}\n\n${typeDefs.trim()}\n`;
+
+  // Executable schema: directive defs + @link + user SDL + federation types + _Entity union.
+  const fullSdl = [
+    FEDERATION_DIRECTIVE_SDL,
+    FEDERATION_LINK,
+    typeDefs,
+    FEDERATION_TYPES,
+    entityUnion,
+  ].join('\n\n');
+
+  let schema: GraphQLSchema;
+  try {
+    schema = buildSchema(fullSdl, { assumeValid: false });
+  } catch (err) {
+    throw new Error(`[nexus-graphql] Failed to build subgraph schema for "${name}": ${(err as Error).message}`);
+  }
+
+  // The `_Entity` union needs a resolveType so graphql-js can pick the concrete
+  // member type for each resolved entity. Entities carry `__typename` from
+  // their representation; we also backfill it onto results that lack it.
+  const entityType = schema.getType('_Entity') as
+    | { resolveType?: (value: any) => string | null }
+    | undefined;
+  if (entityType && 'resolveType' in entityType) {
+    entityType.resolveType = (value: any) => (value && typeof value === 'object' ? (value as any).__typename ?? null : null);
+  }
+
+  // Auto-wire the federation fields into the resolver map (merged, not mutated).
+  const federationResolvers: Resolvers = {
+    ...resolvers,
+    _Any: {
+      // Custom scalar: pass-through serialize/parse.
+      __serialize: (value: unknown) => value,
+      __parseValue: (value: unknown) => value,
+      __parseLiteral: (value: unknown) => value,
+    } as unknown as Resolvers['_Any'],
+    Query: {
+      ...(resolvers.Query ?? {}),
+      _service: () => ({ sdl }),
+      _entities: (_parent: unknown, args: Record<string, any>, ctx: GraphQLContext) =>
+        Promise.all(((args.representations as EntityRepresentation[] | undefined) ?? []).map(async (rep) => {
+          const resolved = await entityResolver(rep, ctx);
+          if (resolved && typeof resolved === 'object' && !('__typename' in resolved)) {
+            (resolved as Record<string, unknown>).__typename = rep.__typename;
+          }
+          return resolved;
+        })),
+    },
+    _Service: {
+      sdl: (parent: { sdl?: string }) => parent.sdl ?? sdl,
+    },
+  };
+
+  // Validate the SDL parses + that the federation directives are used correctly
+  // (e.g. @key has a `fields` arg). buildSchema already enforces directive
+  // argument types/locations; we additionally assert the SDL parses standalone.
+  parse(sdl);
+
+  return {
+    name,
+    schema,
+    sdl,
+    entityKeys,
+    resolvers: federationResolvers,
+    entityResolver,
+  };
+}
+
+/**
+ * Validate a query against a schema before execution (returns errors array).
+ * Useful for the HTTP handler to reject malformed operations early.
+ */
+export function validateOperation(schema: GraphQLSchema, source: string) {
+  let doc;
+  try {
+    doc = parse(source);
+  } catch (err) {
+    return [(err as Error).message];
+  }
+  return validate(schema, doc).map((e) => e.message);
+}
+
+/** Re-export for the gateway to share the resolver wiring. */
+export { createFieldResolver };

package/src/subgraph/federationDirectives.ts

@@ -0,0 +1,47 @@
+/**
+ * Federation directive definitions and the `@link` schema directive.
+ *
+ * These are prepended to the user's typeDefs so `buildSchema` accepts the
+ * federation directives (`@key`, `@external`, `@requires`, `@provides`,
+ * `@extends`). We target a Federation v2-style subset (the same directives
+ * Apollo uses); composition (Phase 6) is ours, but the directive *surface*
+ * matches the spec so subgraph SDL is interoperable.
+ *
+ * NOTE: `@link` is declared so `extend schema @link(...)` parses. We do not
+ * enforce the import list — the directives are always declared and available.
+ */
+export const FEDERATION_DIRECTIVE_SDL = /* graphql */ `
+  directive @link(url: String!, import: [String!]) on SCHEMA
+  directive @key(fields: String!) repeatable on OBJECT | INTERFACE
+  directive @external on FIELD_DEFINITION
+  directive @requires(fields: String!) on FIELD_DEFINITION
+  directive @provides(fields: String!) on FIELD_DEFINITION
+  directive @extends on OBJECT | INTERFACE | FIELD_DEFINITION
+`;
+
+/** The `extend schema @link(...)` clause advertising the federation import. */
+export const FEDERATION_LINK = /* graphql */ `
+  extend schema @link(
+    url: "https://specs.apollo.dev/federation/v2.0"
+    import: ["@key", "@external", "@requires", "@provides", "@extends"]
+  )
+`;
+
+/** Federation boilerplate types prepended/appended to make a schema subgraph-compliant. */
+export const FEDERATION_TYPES = /* graphql */ `
+  scalar _Any
+  type _Service { sdl: String! }
+  extend type Query {
+    _service: _Service!
+    _entities(representations: [_Any!]!): [_Entity]!
+  }
+`;
+
+/** Build the `_Entity` union SDL for the given entity type names (or a scalar if none). */
+export function entityUnionSdl(entityTypeNames: string[]): string {
+  if (entityTypeNames.length === 0) return `scalar _Entity`;
+  return `union _Entity = ${entityTypeNames.join(' | ')}`;
+}
+
+/** Names of the federation directives we recognize (for stripping when building the public schema). */
+export const FEDERATION_DIRECTIVE_NAMES = ['key', 'external', 'requires', 'provides', 'extends', 'link'];

package/src/subgraph/parseKeys.ts

@@ -0,0 +1,25 @@
+/**
+ * Parse `@key(fields: "...")` directives from subgraph SDL to learn which types
+ * are entities and what their key field paths are. This is a pragmatic regex scan
+ * (not a full SDL parser) — sufficient for the v1 federation subset and for the
+ * composition step in Phase 6. Composite keys like `@key(fields: "id tenant")` are
+ * supported (space-separated, as in the spec).
+ */
+export function parseEntityKeys(typeDefs: string): Map<string, string[]> {
+  const keys = new Map<string, string[]>();
+  // Match `type X ... {` or `extend type X ... {` (and interfaces) up to the body.
+  const typeHeader = /(?:extend\s+)?(?:type|interface)\s+(\w+)([^{]*)\{/g;
+  let m: RegExpExecArray | null;
+  while ((m = typeHeader.exec(typeDefs)) !== null) {
+    const name = m[1]!;
+    const header = m[2]!;
+    const keyFields: string[] = [];
+    const keyRe = /@key\s*\(\s*fields:\s*"([^"]+)"\s*\)/g;
+    let k: RegExpExecArray | null;
+    while ((k = keyRe.exec(header)) !== null) {
+      keyFields.push(...k[1]!.split(/\s+/).filter(Boolean));
+    }
+    if (keyFields.length) keys.set(name, keyFields);
+  }
+  return keys;
+}

package/src/subscriptions/PubSub.ts

@@ -0,0 +1,64 @@
+import { EventEmitter } from 'node:events';
+
+/**
+ * Minimal in-process PubSub for GraphQL subscriptions. Sufficient for the
+ * single-instance default app; a Redis-backed pub/sub adapter can be plugged in
+ * later for cross-instance fanout (mirrors the realtime adapter pattern).
+ *
+ * Usage in a subscription resolver:
+ *   Subscription: {
+ *     messageAdded: {
+ *       subscribe: () => pubsub.asyncIterator('MESSAGE_ADDED'),
+ *       resolve: (payload) => payload,
+ *     }
+ *   }
+ */
+export class PubSub {
+  private ee = new EventEmitter();
+
+  constructor() {
+    this.ee.setMaxListeners(0);
+  }
+
+  /** Publish a payload to a topic. */
+  publish(topic: string, payload: unknown): void {
+    this.ee.emit(topic, payload);
+  }
+
+  /** Return an AsyncIterable that yields payloads published to the topic(s). */
+  asyncIterator(topics: string | string[]): AsyncIterable<any> {
+    const list = Array.isArray(topics) ? topics : [topics];
+    const ee = this.ee;
+    const queue: any[] = [];
+    let pull: ((v: IteratorResult<any>) => void) | undefined;
+
+    for (const t of list) {
+      const push = (payload: any) => {
+        if (pull) {
+          const resolve = pull;
+          pull = undefined;
+          resolve({ value: payload, done: false });
+        } else {
+          queue.push(payload);
+        }
+      };
+      ee.on(t, push);
+    }
+
+    return {
+      [Symbol.asyncIterator]() {
+        return {
+          next(): Promise<IteratorResult<any>> {
+            if (queue.length) return Promise.resolve({ value: queue.shift(), done: false });
+            return new Promise((resolve) => { pull = resolve; });
+          },
+          return(): Promise<IteratorResult<any>> {
+            // Unsubscribe listeners on early completion (client disconnect).
+            for (const t of list) ee.removeAllListeners(t);
+            return Promise.resolve({ value: undefined, done: true });
+          },
+        };
+      },
+    };
+  }
+}