@graphql-hive/router-query-planner

A high-performance Node.js addon containing the query planner of Hive Router. This package provides GraphQL Federation query planning capabilities built with Rust and N-API for optimal performance.

Overview

This node addon contains the query planner of the Hive Router, enabling you to generate Query Plans used in Apollo Federation. It provides a fast, native implementation for planning GraphQL operations across federated schemas.

Installation

npm install @graphql-hive/router-query-planner
# or
yarn add @graphql-hive/router-query-planner
# or
pnpm add @graphql-hive/router-query-planner

Platform Support

This package supports the following platforms:

• Linux: x86_64 and aarch64
• macOS: x64 and arm64 (Apple Silicon)

The package includes prebuilt binaries for all supported platforms. Node.js 20+ and Bun 1+ are supported.

Usage

Basic Usage

To use in TypeScript, you would go ahead and do something like:

import {
  QueryPlanner,
  type QueryPlan,
} from "@graphql-hive/router-query-planner";

const supergraphSdl = "<your sdl from file or in code>";

const qp = new QueryPlanner(supergraphSdl);

const plan: QueryPlan = qp.plan(/* GraphQL */ `
  {
    posts {
      title
      author {
        name
      }
    }
  }
`);

// see QueryPlan types in lib/node-addon/src/query-plan.d.ts

This will generate you a Query Plan used in Apollo Federation.

Integration with Hive Gateway

Hive Gateway uses this package as an alternative federation query planner in the @graphql-hive/router-runtime.

To use with Hive Gateway, first install the runtime:

npm install @graphql-hive/router-runtime

Then configure your gateway:

// gateway.config.ts
import { defineConfig } from "@graphql-hive/gateway";
import { unifiedGraphHandler } from "@graphql-hive/router-runtime";

export const gatewayConfig = defineConfig({
  unifiedGraphHandler,
});