Basic middleware system

[benjie]

Description

Add your own validations via a plugin system.

src/index.ts:

import type {} from "gqlcheck";
import { MyPlugin } from "./plugin.js";

declare global {
  namespace GraphileConfig {
    interface GraphQLCheckConfig {
      /** Description here */
      mySetting?: boolean;
    }
  }
}

export const MyPreset: GraphileConfig.Preset = {
  plugins: [MyPlugin],
};

src/plugin.ts:

import type {} from "gqlcheck";
import { MyVisitor } from "./MyVisitor.js";

export const MyPlugin: GraphileConfig.Plugin = {
  name: "MyPlugin",
  version: "0.0.0",
  gqlcheck: {
    middleware: {
      visitors(next, event) {
        event.visitors.push(MyVisitor(event.rulesContext));
        return next();
      },
    },
  },
};

src/MyVisitor.ts:

import { RuleError, type RulesContext } from "gqlcheck";
import type { ASTVisitor } from "graphql";

export function MyVisitor(context: RulesContext): ASTVisitor {
  // Extract configuration.
  const {
    gqlcheck: {
      config: { mySetting = true } = {},
      operationOverrides = Object.create(null),
    } = {},
  } = context.getResolvedPreset();
  return {
    Field(node) {
      // Get GraphQL stuff from here rather than `import` to avoid conflicts
      const { isListType, getNullableType } = context.graphqlLibrary;
      const fieldDef = context.getFieldDef();

      const nodes = [node];
      // A node may be used in more than one operation.
      const allOperationNames = context.getOperationNamesForNodes(nodes);
      // Filter to just the operations where this setting is enabled.
      const operationNames = allOperationNames.filter(
        (n) =>
          // Can only use operationOverrides if the operation is named.
          (n ? operationOverrides[n]?.mySetting : null) ?? mySetting,
      );
      // Find the locations where the setting is enabled.
      const ops = context.getErrorOperationLocationsForNodes(
        nodes,
        operationNames,
      );

      // Only report if there are locations where the setting is enabled.
      if (ops.length > 0) {
        // Nonsense rule, demonstration purposes only. Forbids lists.
        const isList = isListType(getNullableType(fieldDef.type));
        if (isList) {
          context.reportError(
            new RuleError(`Querying lists is not allowed!`, {
              // Typically this will be the name of the setting.
              infraction: `mySetting`,
              nodes,
              errorOperationLocations: ops,
              // If the user merges this override in for this operation, the
              // error should go away.
              override: {
                mySetting: false,
              },
            }),
          );
        }
      }
    },
  };
}

Performance impact

Overhead, but worthwhile.

Security impact

You can now use arbitrary third party plugins... Only use plugins you trust.

Checklist

• My code matches the project's code style and yarn lint:fix passes.
• I've added tests for the new feature, and yarn test passes.
• I have detailed the new feature in the relevant documentation.
• I have added this feature to 'Pending' in the RELEASE_NOTES.md file (if one exists).
• If this is a breaking change I've explained why.