@pothos/plugin-directives/README.md

Directive plugin for Pothos, enables using graphql-tools based directives with Pothos

# Directives Plugin

A plugin for using schema directives with schemas generated by Pothos.

Schema Directives are not intended to be used with code first schemas, but there is a large existing
community with several very useful directives based

## Usage

### Install

```bash
yarn add @pothos/plugin-directives
```

### Setup

```typescript
import DirectivePlugin from '@pothos/plugin-directives';
import { rateLimitDirective } from 'graphql-rate-limit-directive';

const builder = new SchemaBuilder<{
  Directives: {
    rateLimit: {
      locations: 'OBJECT' | 'FIELD_DEFINITION';
      args: { limit: number, duration: number };
    };
  };
}>({
  plugins: [DirectivePlugin],
  directives: {
    useGraphQLToolsUnorderedDirectives: true,
  }
});

builder.queryType({
  directives: {
    rateLimit: { limit: 5, duration: 60 },
  },
  fields: (t) => ({
    hello: t.string({ resolve: () => 'world' });
  });
});

const { rateLimitDirectiveTransformer } = rateLimitDirective();
const schema = rateLimitDirectiveTransformer(builder.toSchema());
```

The directives plugin allows you to define types for the directives your schema will use the
`SchemaTypes` parameter. Each directive can define a set of locations the directive can appear, and
an object type representing the arguments the directive accepts.

The valid locations for directives are:

- `ARGUMENT_DEFINITION`
- `ENUM_VALUE`
- `ENUM`
- `FIELD_DEFINITION`
- `INPUT_FIELD_DEFINITION`
- `INPUT_OBJECT`
- `INTERFACE`
- `OBJECT`
- `SCALAR`
- `SCHEMA`
- `UNION`

Pothos does not apply the directives itself, this plugin simply adds directive information to the
extensions property of the underlying GraphQL type so that it can be consumed by other tools like
`graphql-tools`.

By default this plugin uses the format that Gatsby uses \(described
[here](https://github.com/graphql/graphql-js/issues/1343#issuecomment-479871020)\). This format
[was not supported by older versions of `graphql-tools`](https://github.com/ardatan/graphql-tools/issues/2534).
To support older versions of `graphql-tools` or directives that provide a schema visitor based on an
older graphql-tools version like the rate-limit directive from the example above you can set the
`useGraphQLToolsUnorderedDirectives` option. This option does not preserve the order that directives
are defined in. This will be okay for most cases, but may cause issues if your directives need to be
applied in a specific order.

To define directives on your fields or types, you can add a `directives` property in any of the
supported locations using one of the following 2 formats:

```typescript
{
  directives: [
    {
      name: "validation",
      args: {
        regex: "/abc+/"
      }
    },
    {
      name: "required",
      args: {},
    }
  ],
  // or
  directives: {
    validation: {
      regex: "/abc+/"
    },
    required: {}
  }
}
```

Each of these applies the same 2 directives. The first format is preferred, especially when using
directives that are sensitive to ordering, or can be repeated multiple times for the same location.

## Applying directives

For most locations (On fields and types) the options object for the field or type will have a
`directives` option which can be used to define directives.

To apply `SCHEMA` directives, you can use the `schemaDirectives` option on the `toSchema` method.
`directives` on `toSchema` is reserved for the Directive implementations.