Add __assertStep support to makeGrafastSchema and makeExtendSchemaPlugin

[benjie]

Description

Relates to #1915 (but doesn't fix it).

Object types in Grafast can indicate that they must be represented by a particular step or set of steps; this can help to catch bugs early. For example, in PostGraphile a database table resource should be represented by a pgSelectSingle or similar class; representing it with object({id: 1}) or similar would mean the step doesn't have the expected helper methods and downstream fields may fail to plan because their expectations are broken.

When writing a schema manually, you set this via objectTypeConfig.extensions.grafast.assertStep which can either be a step class itself (e.g. objectTypeConfig.extensions = {grafast: {assertStep: PgSelectSingleStep}}) or it can be an "assertion function" that throws an error if the passed step is not of the right type, e.g.:

objectTypeConfig.extensions = {
  grafast: {
    assertStep($step) {
      if ($step instanceof PgSelectSingleStep) return true;
      if ($step instanceof PgInsertSingleStep) return true;
      if ($step instanceof PgUpdateSingleStep) return true;
      throw new Error(`Type 'User' expects a step of type PgSelectSingleStep, PgInsertSingleStep or PgUpdateSingleStep; but found step of type '${$step.constructor.name}'.`);
    }
  }
};

Further, if you have a union (e.g. union U = A | B | C) then all types in the union must either expect a plan, or not expect a plan.

Previous to this PR, you could not indicate that your custom type created in makeExtendSchemaPlugin expects a plan. Further, the types of makeGrafastSchema were wrong, filing this under the removed __Step property. This PR makes it so that you can define __assertStep as part of defining the field plans for an object type; the __ prefix ensures that it cannot conflict with any field names (since GraphQL forbids field names that start with __). E.g.:

const plugin = makeExtendSchemaPlugin({
  typeDefs: gql`
    type UnameTaken {
      message: String
    }

    type EmailTaken {
      message: String
    }
  `,
  plans: {
    UnameTaken: {
      __assertStep: ExecutableStep,
    },
    EmailTaken: {
      __assertStep: ($step) => {
        if ($step instanceof ObjectStep) return true;
        throw new Error(`EmailTaken expected an 'ObjectStep' but instead received '${$step.constructor.name}'`);
      }
    },
  }
});

Performance impact

Negligible.

Security impact

None known.

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.

[changeset-bot]

🦋 Changeset detected

Latest commit: af3d8dd

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 15 packages

Name	Type
graphile-utils	Patch
grafast	Patch
postgraphile	Patch
@localrepo/grafast-bench	Patch
@dataplan/json	Patch
@dataplan/pg	Patch
@grafserv/persisted	Patch
grafserv	Patch
ruru-components	Patch
@localrepo/grafast-website	Patch
graphile-build-pg	Patch
graphile-build	Patch
pgl	Patch
graphile-export	Patch
graphile	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR