# graphql-executor

> A customizable GraphQL Spec compliant Executor class.

Latest version **0.0.23** (published 2022-04-12) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install graphql-executor
pnpm add graphql-executor
yarn add graphql-executor
bun add graphql-executor
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 0.0.23 |
| Published | 2022-04-12 |
| First published | 2021-06-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | ^12.22.0 \|\| ^14.16.0 \|\| >=16.0.0 |
| Dependencies | 0 |
| Unpacked size | 464.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 18 |
| Maintainers | yaacovcr |
| Keywords | executor, graphql, graphql-executor, graphql-js |

## Links

- npm: https://www.npmjs.com/package/graphql-executor
- Repository: https://github.com/yaacovCR/graphql-executor
- Issues: https://github.com/yaacovCR/graphql-executor/issues
- npm.io page: https://npm.io/package/graphql-executor

## Alternatives

- [apollo-link-http-common](https://npm.io/package/apollo-link-http-common.md) — 879.0K weekly downloads
- [react-relay](https://npm.io/package/react-relay.md) — 336.8K weekly downloads
- [relay-test-utils](https://npm.io/package/relay-test-utils.md) — 181.6K weekly downloads
- [@vendure/core](https://npm.io/package/@vendure/core.md) — 14.8K weekly downloads
- [@pnpm/deps.graph-sequencer](https://npm.io/package/@pnpm/deps.graph-sequencer.md) — 13.4K weekly downloads

## Recent versions

- 0.0.23 (latest) — 2022-04-12
- 0.0.22 — 2022-03-23
- 0.0.21 — 2022-03-21
- 0.0.20 — 2022-03-20
- 0.0.19 — 2022-03-04
- 0.0.18 — 2022-02-04
- 0.0.17 — 2022-01-27
- 0.0.16 — 2022-01-27
- 0.0.15 — 2022-01-15
- 0.0.14 — 2022-01-06
- 0.0.13 — 2022-01-05
- 0.0.12 — 2022-01-04
- 0.0.11 — 2021-12-07
- 0.0.10 — 2021-11-24
- 0.0.9 — 2021-11-24
- … 8 more at https://npm.io/package/graphql-executor/versions

## README

# GraphQL Executor

A customizable GraphQL Spec compliant Executor based on [graphql-js](https://github.com/graphql/graphql-js/)

### Installation

With npm:

```sh
npm install --save graphql-executor
```

or using yarn:

```sh
yarn add graphql-executor
```

### Usage

For the default GraphQL-Executor behavior:

1. Use the `execute` and `subscribe` methods exported by `graphql-executor` in place of those exported by `graphql-js`.

To customize execution:
(A) fork this package, customize the code, and carry on as above, or
(B) override the internal `Executor` class:

1. Remember to pin the version of `graphql-executor` you use, as the `Executor` class remains internal with all changes considered non-breaking.
2. Subclass the exported `Executor` class.
3. Override your subclassed `Executor` methods as desired to provide your custom functionality.
4. Create a new custom `execute` function calling this subclass.

```ts
import { Executor } from 'graphql-executor';

class MyCustomExecutor extends Executor {
  // ...
}

export function execute(args: ExecutionArgs): PromiseOrValue<ExecutionResult> {
  const executor = new MyCustomExecutor(args);
  return executor.executeQueryOrMutation(args);
}
```

### Why GraphQL Executor?

GraphQL Executor provides:

1. A way to fork the GraphQL.JS executor without introducing multiple versions of
   `graphql-js` into your project. `graphql-executor` is a "smart" fork of only the
   `execution` module of `graphql-js`. You can safely fork `graphql-executor` to
   customize your execution flow as needed.
2. A code-only method of customizing the executor by subclassing the exported internal
   `Executor` class as above.
3. Direct benefits from our own customizations! GraphQL Executor is spec-compliant,
   but also supports experimental features (such as `@defer`/`@stream` support) and provide
   other improvements as possible. See (https://github.com/yaacovCR/graphql-executor/releases)
   to track any new features.

### The Long Version

[GraphQL.js](https://github.com/graphql/graphql-js) occupies a foundational position
within the Javascript GraphQL ecosystem as the central dependency for almost all other
community packages. GraphQL.js provides two key capabilities: building a typed schema
and executing requests against that type schema; it also includes a parser for the
GraphQL language and a handful of additional extremely helpful utilities. The vast
majority of community packages depend in some way upon this bedrock to provide all
additional custom functionality.

GraphQL.js allows for customization in several ways. SDL directives allow schema
and operation writers to specify custom behavior while still using the standard GraphQL
parser. `extensions` fields on most objects allow for setting and passing custom
metadata. In many ways, execution can be customized within resolver functions, perhaps
in combination with the above custom directives and extensions.

Customization of the execution algorithm itself is less straightforward, if not
impossible. GraphQL.js serves as a reference implementation for the
[GraphQL specification](https://spec.graphql.org/). This means that the execution
algorithm included within GraphQL.js is designed not only to be spec-compliant, but
also to most clearly express the algorithms contained within the spec. While
experimentation is encouraged, this is in the context of pull requests to the
specification, which should have a matching pull request within the reference
implementation. Execution algorithm customization is not the main concern of
GraphQL.js, and is usually therefore handled to the extent possible outside the
execution pipeline within the calling code.

For example, take note of [Envelop](https://www.envelop.dev/), a powerful,
server-agnostic method of customizing the GraphQL request layer. Note that the
[available execution hooks](https://www.envelop.dev/docs/plugins/lifecycle#onexecuteapi)
are limited to `onExecuteDone` and `onResolverCalled`, among a few others.
GraphQL.JS provides a hook for field resolution, but not for field completion,
for example, limiting the hooks that Envelop can provide. Free-form user customization
of execution cuts against the role of GraphQL.JS as a strict, spec-conformant reference
implementation. Introduction of middleware in GraphQL.JS [has](https://github.com/graphql/graphql-js/issues/109)
[proved](https://github.com/graphql/graphql-js/issues/1516)
[elusive](https://github.com/graphql/graphql-js/issues/3163).

GraphQL Executor fills this gap by allowing for customization of the entire execution
pipeline. Perhaps the most straightforward method of customizing execution would be to
simply fork the `graphql-js` package for one's own custom use. This is made difficult by
the central position of GraphQL.js in the ecosystem; most projects can safely tolerate
only a single version of `graphql-js`, see
[graphql-js#594](https://github.com/graphql/graphql-js/issues/594) and
["GraphQL.js: Preparing for v14.0.0"](https://medium.com/@leeb/graphql-js-preparing-for-v14-0-0-839f823c144e).

GraphQL Executor is a "smartly" forked version of the `graphql.js` package that includes
only the `execution` module and still depends on the `graphql-js` package for all other
purposes, thereby eliding the issues above.

GraphQL Executor also refactors the execution pipeline from GraphQL.js into an exported
versioned, an `Executor` class. An `execute` function is simply a thin wrapper around
the `Executor.executeQueryOrMutation(args)` and `Executor.executeSubscription(args)`
methods. You can subclass the `Executor` class to customize the executor pipeline without
maintaining a separate repository. The `Executor` class is internal, so when utilizing this
method, you must pin the version of the `graphql-executor` package.

### Contributing

We actively welcome pull requests. GraphQL Executor is spec-compliant but is open to adopting
experimental behavior (such as the already supported `@defer`/`@stream` directives).

### Changelog

We use [`changesets`](https://github.com/atlassian/changesets) for release management.
Changes are therefore tracked as [GitHub releases](https://github.com/yaacovCR/graphql-executor/releases).

### License

GraphQL Executor is [MIT-licensed](./LICENSE).

### Credits

Credit for GraphQL Executor is due mostly to all the hard work done at
[graphql-js](https://github.com/graphql/graphql-js), and especially @IvanGoncharov, who
provided close direction and guidance for this method of customizing execution.

---
_Source: https://npm.io/package/graphql-executor · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._