RFC: Provide built-in multi-schema support ("Multiple Schemas")

Summary

In applications today, it's not uncommon anymore to consume one (or more) GraphQL API(s) while also building one. When this is done in a monorepo and we wish to use gql.tada to both consume our own GraphQL API on the front-end and third-party APIs on the back-end, we end up with multiple schemas.

Currently, these conflict and setting them up means that:

the schema can't differentiate them unless we were to introduce multiple configs
the TS LSP plugin can't differentiate them unless template is altered and the plugin is added multiple times

Instead, we should be able to natively support multiple schemas.

Proposed Solution

The configuration should be extended to support multiple schemas. Currently, the config is instantiated with a single schema, which is a format we should still support after this change:

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@0no-co/graphqlsp",
        "schema": "./schema.graphql",
        "tadaOutputLocation": "./src/graphql-env.d.ts"
      }
    ]
  }
}

The most convenient configuration would be to allow schema to accept multiple configurations:

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@0no-co/graphqlsp",
        "schema": [
          {
            "url": "./schema.graphql",
            "tadaOutputLocation": "./src/graphql/graphql-env.d.ts"
          },
          {
            "url": "https://api.example.com/graphql",
            "tadaOutputLocation": "./src/graphql/example-graphql-env.d.ts"
          }
        ]
      }
    ]
  }
}

Selecting a schema should be automatically done in the CLI and GraphQLSP.

Requirements

There may be better options to changing schema to a schema[] array in the config. However, we need to definitely scope all tada-specific options to the schema itself, mainly:

tadaOutputLocation?: string;
tadaTurboLocation?: string;
tadaPersistedLocation?: string;

Instead of discovering graphql calls by template, we should:

attempt to find calls matching the template name
fall back to match all calls that are on an identifier and contain a gql.tada-compatible signature
- this is a call with a string literal as the first argument
- and an optional second argument with a literal array or identifier

gql.tada should expose a hidden, optional property on graphql that allows us to identify the schema with a typeChecker check. Retrieveing this property happens using a StringLiteral type check, similar to this union: https://github.com/0no-co/GraphQLSP/blob/c4630f62bd435ffacb89ab2a66860b96a9b9bdee/packages/graphqlsp/src/fieldUsage.ts#L359-L367 The property could have a signature of __schema?: string;, where string is the string literal specifying the schema[].url property.

The gql.tada CLI and graphqlsp can then switch schemas by matching graphql.__schema against schema[].url in the config.

The schema loaders should be extended to automatically support multiple schemas and abstract them away as much as possible.

Open Questions

What happens to declare module in the individual generated tadaOutputLocation files when this is done? Should they be omitted?
How do we enforce initGraphQLTada<> to be used and notify the user if they don't? Should we have a warning for this as part of the diagnostics by detecting type-less graphql calls?
How is the stable key generated?
- Filepaths for SDL present the challenge of paths being potentially unstable, unless we generate them from the git root (which is error-prone)
- URLs present challenges if the URL isn't properly normalised, and could be hard for the LSP to re-retrieve

Requests

Prior discussions

Prior Discord messages

https://discord.com/channels/1082378892523864074/1210514957863485460

0no-co / gql.tada