@plasius/graph-gateway-core

Read-path graph gateway orchestration core with stale-serving, retry, and timeout controls.

Apache-2.0. ESM + CJS builds. TypeScript types included.

Requirements

• Node.js 24+ (matches .nvmrc and CI/CD)
• @plasius/graph-contracts

Installation

npm install @plasius/graph-gateway-core

Exports

import { GraphGateway, type GraphGatewayOptions } from "@plasius/graph-gateway-core";

Quick Start

import { GraphGateway } from "@plasius/graph-gateway-core";

const gateway = new GraphGateway({
  resolver: {
    async resolve(request) {
      return {
        key: request.key,
        data: { id: request.key },
        stale: false,
        tags: request.tags ?? [],
      };
    },
  },
  maxFanout: 8,
  timeoutMs: 750,
  retryAttempts: 2,
  retryBudgetMs: 1_500,
  circuitBreaker: {
    canRequest: async (resolver) => resolver !== "disabled.resolver",
  },
});

const result = await gateway.execute({
  requests: [{ resolver: "user.profile", key: "user:1" }],
});

console.log(result.partial, result.stale);

Development

npm run clean
npm install
npm run lint
npm run typecheck
npm run test:coverage
npm run build

Resilience and Observability

• Query planning/fanout control via maxFanout.
• Retry policy controls:
  • timeoutMs
  • retryAttempts
  • retryBudgetMs
  • retryBackoffMs
  • retryJitterRatio
• Circuit breaker hooks:
  • canRequest
  • onSuccess
  • onFailure
• Telemetry events:
  • graph.execute.latency
  • graph.cache.outcome
  • graph.resolve.latency
  • graph.resolve.backoff_ms
  • graph.upstream.error
• Runtime query payloads are validated at execution boundary (isGraphQuery).

Architecture

• Package ADRs: docs/adrs
• Cross-package ADRs: plasius-ltd-site/docs/adrs/adr-0020 to adr-0024

License

Licensed under the Apache-2.0 License.