@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:

| Capix | GraphQL | |-------|---------| | intent: 'query' | Query field | | All other intents | Mutation field | | users.getUser | users_getUser field | | z.string() input | String! arg | | z.number() input | Float! arg | | z.boolean() input | Boolean! arg | | .output(schema) | Named output type | | No .output() | JSON scalar | | z.coerce.number().default(N) | Optional Float arg |

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

| Option | Type | Default | Description | |--------|------|---------|-------------| | port | number | — | Port to listen on | | host | string | '0.0.0.0' | Host to bind to | | path | string | '/graphql' | GraphQL endpoint path | | playground | boolean | true | Serve GraphiQL at {path}/playground | | capabilities | GroupTree | server default | Per-transport capability registry |

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