This module provides building blocks for the GraphQL Schema that the GraphQL Engine presents.

The functions defined here are used to serve as default implementations for their namesakes in the BackendSchema type class.

When, for some backend, you want to implement a new feature that manifests itself visibly in the schema (e.g., if you're developing support for update mutations), this module is likely where your efforts should start.

Using these functions help us present a consistent GraphQL schema across different backends.

There is a bit of tension however, as sometimes we intentionally do want the GraphQL Schema relating to some backend to be different in some way.

It could be that a backend only has limited support for some common feature, or, more interestingly, that some backend just does things differently (c.f. MSSQL's MERGE statement with PostgreSQL's INSERT .. ON CONFLICT, which are similar enough that we want to use the same overall upsert schema but different enough that we want to use different field names)

When you want to implement new schema for a backend, there is overall three different ways do deal with this tension:

1. You can duplicate existing code and implement the new behavior in the duplicate.
2. You can infuse the new behavior into existing code and switch dynamically at runtime (or via type class instance dispatch, which is the same for our purposes)
3. You can refactor the existing building blocks and compose them differently at use sites to get the desired behavior nuances.

Of these three, steps 1. and 2. are by far the easiest to execute, while 3. requires some critical thought. However, both 1. and 2. produce legacy code that is difficult to maintain and understand.

As a guideline, if you find yourself wanting add new behavior to some of these functions it's very likely that you should consider refactoring them instead, thus shifting the responsibility deciding on the correct behavior to use sites.

It an ongoing effort to adapt and refactor these building blocks such that they have the sizes and shapes that result in the most elegant uses of them that we can manage.