Runtime

Benzene supports GraphQL execution using a customizable runtime.

Benzene's GraphQL runtime can be configured with the compileQuery option. By default, it will use graphql-js implementation.

Built-in implementations

@benzene/core currently bundles with only graphql-js implementation. graphql-jit implementation can be installed from @benzene/jit package.

graphql-js

graphql-js is the original implementation of GraphQL for JavaScript, which offers the latest features and best stability.

import { makeCompileQuery } from "@benzene/core";
// OR: import { makeCompileQuery } from "@benzene/http";
// OR: import { makeCompileQuery } from "@benzene/ws";
 
const GQL = new Benzene({
  compileQuery: makeCompileQuery(),
});

This is also preferred if your application is deployed in specific environments, such as Cloudflare Workers, which does not allow runtime evaluation required by other implementations.

graphql-jit

graphql-jit is a new implementation of GraphQL for JavaScript, that offers significant performance improvement (up to 10x) compared to the former. You should first install it with:

npm i @benzene/jit

Then set it to compileQuery like so:

import { makeCompileQuery } from "@benzene/jit";
 
const GQL = new Benzene({
  compileQuery: makeCompileQuery(),
});

Check out the benchmarks to see how using this runtime can benefit your application.

💡

Your environment must support evaluation/code generation from strings for this to work.

Custom Configuration

You can define your own runtime by creating a compileQuery function like below:

const GQL = new Benzene({
  compileQuery(schema, document, operationName) {
    // Return the compiled result
    return {
      execute({
        document,
        contextValue,
        variableValues,
        rootValue,
        operationName,
      }) {
        // return execution result
      },
      susbcribe({
        document,
        contextValue,
        variableValues,
        rootValue,
        operationName,
      }) {
        // return subscription result
      },
    };
    // OR: in case of error, return an execution result
    return {
      errors: [new GraphQLError("Compilation failed")],
    };
  },
});

The function will be called with the schema, document node, and optionally operation name and returns either:

An object with three functions execute, subscribe, and optionally stringify.
GraphQL execution result in case of error

The signatures of execute and subscribe are the same as those (non-positional ones) from graphql-js (a difference being that it does not contain schema in the argument).

type CompileQuery = (
  schema: GraphQLSchema,
  document: DocumentNode,
  operationName?: Maybe<string>
) => CompiledQuery | ExecutionResult;
 
type BenzeneGraphQLArgs<T> = Omit<T, "schema">;
 
interface CompiledQuery {
  execute(
    args: BenzeneGraphQLArgs<ExecutionArgs>
  ): ValueOrPromise<ExecutionResult>;
 
  subscribe?(
    args: BenzeneGraphQLArgs<SubscriptionArgs>
  ): Promise<AsyncIterableIterator<ExecutionResult> | ExecutionResult>;
 
  stringify?(result: ExecutionResult): string;
}