Grafast: introduce inhibitOnNull

[benjie]

Description

Follow up to #2014, also addressing #2013.

This pull request builds on the new flag-based system and introduces a new (internal) __FlagStep which applies a particular flag mask to a dependency. This __FlagStep can automatically go away in most cases, by merging into the addDependency call of the dependent, since all it does is adjust the "accepted" flags those flags can be applied to the underlying step instead.

Building on __FlagStep we have the new (public) inhibitOnNull() step. This step tells the system that if a null occurs then anything depending on this value should be inhibited (i.e. prevented from executing and just assumed to be null). This is particularly useful for Relay: imagine we want to use a node ID for a condition, but we are specifically referencing a particular type (e.g. Person); we can decode the Node ID and attempt to get a specification for that type, but if the Node ID is for an alternative type (e.g. Post) or is invalid then there's no point continuing because we know the condition will always be falsy, and thus we can "inhibit" the step to which the condition is being applied, thereby causing it to skip execution.

For PostGraphile users, you can think of this a little bit like a STRICT database function: for a STRICT function if any argument is null then the database knows the result will be null and thus does not need to execute. inhibitOnNull is a little like that, but it only applies to a single argument.

This PR also introduces assertNotNull() and trap() but they are not yet tested (more PRs to come).

Performance impact

Improvement: don't bother to run the following code if you know that it will be invalidated by null.

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: 1df652f

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

This PR includes changesets to release 15 packages

Name	Type
graphile-build-pg	Patch
postgraphile	Patch
grafast	Patch
graphile-utils	Patch
pgl	Patch
graphile	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	Patch
graphile-export	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