@capixjs/transport-graphql

@capixjs/transport-graphql

GraphQL transport for Capix. Serves a spec-compliant GraphQL endpoint and an optional GraphiQL playground from your Capix capability registry.

Install

npm install @capixjs/core @capixjs/transport-graphql zod

Usage

import { createServer } from '@capixjs/core';
import { graphqlTransport } from '@capixjs/transport-graphql';
import { buildContext, capabilities } from './capabilities.js';

createServer({
  context: buildContext,
  capabilities,
  transports: [
    graphqlTransport({ port: 4000 }),
  ],
}).start();

GraphQL endpoint: http://localhost:4000/graphql
Playground: http://localhost:4000/graphql/playground

Schema mapping

Capability registries are mapped to a GraphQL schema automatically:

Querying

# Named output type (capability uses .output())
{ users_getUser(id: "1") { id name email } }

# JSON scalar (no .output() — entire object returned as-is)
{ system_ping }

# Variables work for all argument types
query GetUser($id: String!) {
  users_getUser(id: $id) { id name }
}

Options

Per-transport capabilities

createServer({
  context: buildContext,
  transports: [
    graphqlTransport({
      port: 4000,
      capabilities: { users: { list, get } },  // only these capabilities on GraphQL
    }),
  ],
});

Auth header forwarding

The GraphQL transport forwards Authorization and other request headers to buildContext unchanged. Use getHeader(req, 'authorization') inside your context builder to read them:

import { defineContext, getHeader } from '@capixjs/core';

const buildContext = defineContext(async (req) => ({
  requestId: crypto.randomUUID(),
  user: await verifyToken(getHeader(req, 'authorization')),
}));

Limitations

• No subscriptions: the GraphQL transport is request/response only. For real-time updates, use wsTransport with an event bus alongside the GraphQL transport.
• z.lazy falls back to JSON scalar: recursive schemas defined with z.lazy() cannot be statically typed in the generated GraphQL schema and are represented as the JSON scalar.
• No file uploads: multipart file uploads are not supported in the GraphQL transport. Use the REST transport for file upload capabilities.
• No batching: the transport handles one operation per request.

License

MIT