Recommended workflow for omitting excess input properties

[kasper573]

GraphQL servers do not allow you to pass in excess properties on input types. Doing so results in a server side error.

For example, say we have the following GraphQL schema:

input Input {
  foo: String!
  bar: Int!
}

type Mutation {
  send(input: Input!): Boolean
}

Then the client sends the following data to the send mutation:

{ "foo": "hello", "bar": 123, "excess": "excess" }

This would lead to the following server side error:

Variable \"$input\" got invalid value { bar: 123, excess: \"excess\", foo: \"hello\" }; Field \"excess\" is not defined by type \"Input\".

Now, what's the big deal you may wonder, just pass in the correct values? While that is true, I would argue it goes against the purpose of type safety to have to remember to do things right and not trust the compiler or type checker to do its job. And unfortunately, due to the structural nature of typescript, it's actually quite simple to end up with a runtime error that typescript itself cannot detect:

Here is an example react component in typescript that contains no type errors, but one of the mutation calls will end up with the runtime server error mentioned above:

import { useMutation } from "urql";
import { graphql } from "./gql-tada";

export function App() {
  const [mutationResult, sendStuff] = useMutation(mutateGQL);

  const exactInput = { foo: "hello", bar: 123 };

  const excessInput = { foo: "hello", bar: 123, excess: "excess" };
  // This is structurally equal to the input type, but contains excess props, which is a runtime error

  return (
    <div>
      <button onClick={() => sendStuff({ input: exactInput })}>
        Send input to graphql server (with exact input)
      </button>
      <br />
      <button onClick={() => sendStuff({ input: excessInput })}>
        Send input to graphql server (with excess props on input)
      </button>
    </div>
  );
}

const mutateGQL = graphql(`
  mutation Mutate($input: Input!) {
    send(input: $input)
  }
`);

This is a behavior that cannot be disabled in the standard node graphql implementation.

And since gql.tada does not generate any runtime code (i.e. some schema dependent code that filters out excess values), my assumption is also that this falls outside the scope of what gql.tada is responsible of solving.

I wanted to start this discussion and hear what others think of how one should deal with this problem.

I've also made a minimal demo repo with gql.tada, urql and react that demonstrates this issue: https://github.com/kasper573/gql-tada-excess-props-demo

My current solution

What I'm currently doing is using a custom urql exchange that i wrote that omits excess props automatically in the client. It works great, but it comes at the cost that you'll need the schema metadata embedded in your bundle.

[kitten]

gql.tada actually does have some runtime code, but you're right in that it won't generate code based on types for you. While that's certainly technically an option, in practice, it likely won't be something that's suitable for the current approach.

There's probably a way to co-opt graphql.scalar here to do more thorough type checks. Currently, it basically has an identity signature of <T>(typeName: string, input: T) => T, so simplify this. In theory, we could have an extra step for input types that ensure exactness, but without trying this I'm not 100% sure whether that'd be as easy as that.

The problem here is that there always needs to be an exact object literal check where that object is defined, since TypeScript doesn't currently have Exact types in some places.

In certain conditions, TypeScript will however trigger error 2353 (“object literals may only specify known properties”). This doesn't always happen however.

I think the best way to ensure that is to use graphql.scalar to enforce an extra check, but I've noticed that that wasn't working correctly, so I've got a PR on the way to fix that.
That'd look like this:

const exactInput = graphql.scalar('Input', { foo: "hello", bar: 123 });

There's still only certain conditions in which TypeScript can warn you about excess properties, however, I'd say that an API error is in these cases still preferable sometimes

[kasper573]

I believe this could negatively impact DX when working with systems that has many and large forms. Each form would have its associated graphql mutation with its own input type, and if I have to use graphql.scalar I'd be forced into some code duplication.

I'll demonstrate. Here's my preferred form workflow using react-hook-form and urql:

import { useMutation } from "urql";
import { VariablesOf, graphql } from "./client";
import { useForm } from "react-hook-form";

function FooForm() {
  const form = useForm<Input>();
  const [, update] = useMutation(updateFooMutation);
  return (
    <form onSubmit={form.handleSubmit((input) => update({ input }))}>
      <input {...form.register("foo")} />
      <input {...form.register("bar")} />
      <button type="submit">Submit</button>
    </form>
  );
}

type Input = VariablesOf<typeof updateFooMutation>["input"];

const updateFooMutation = graphql(`
  mutation UpdateFoo($input: Input!) {
    send(input: $input)
  }
`);

All the pieces fit together. The useForm hook can reuse the inferred Input type, and useMutation provides an update function that can be connected to the submit handler.

So far nothing is wrong at all, the code example above works perfectly.

However, let's say you want to add another field to the form that is only used locally, or if you load in default form values that happen contain excess properties (but is still structurally compatible with the input type), then we're going to end up with the error I mentioned in my original post. Here's an example of default form values (I've omitted some repeated code from the first example for brevity):

function FooForm() {
  const [{ data: defaultValues }] = useQuery({ query: dataQuery });
  const form = useForm<Input>({ defaultValues });
  const [, update] = useMutation(updateFooMutation);
  return (
    <form onSubmit={form.handleSubmit((input) => update({ input }))}>
      <input {...form.register("foo")} />
      <input {...form.register("bar")} />
      <span>Baz: {defaultValues?.baz}</span>
      <button type="submit">Submit</button>
    </form>
  );
}

// Observe the extra field "baz"
const dataQuery = graphql(`
  query Data {
    foo
    bar
    baz
  }
`);

The above example is something fairly common when views need to display more information than is editable in the form. And the above example is a very intuitive and practical way of coding such views, but unfortunately it doesn't work out of the box with gql.tada, since it leads to the graphql server error since we're not omitting excess properties.

So finally, if we were to use graphql.scalar to avoid this issue, it would look like this:

function FooForm() {
  const [{ data: defaultValues }] = useQuery({ query: dataQuery });
  const form = useForm<Input>({ defaultValues });
  const [, update] = useMutation(updateFooMutation);
  return (
    <form
      onSubmit={form.handleSubmit((input) =>
        update({
          input: graphql.scalar("Input", {
            bar: input.bar,
            foo: input.foo,
            // Keep in mind that in a system with many large forms, you'd have heaps of properties here,
            // and you'd have to do this repeatedly across the codebase.
          }),
        })
      )}
    >
      <input {...form.register("foo")} />
      <input {...form.register("bar")} />
      <span>Baz: {defaultValues?.baz}</span>
      <button type="submit">Submit</button>
    </form>
  );
}

For smaller projects or as an escape hatch I do not mind this. But to have this as the goto workflow for all form views in larger projects, this quickly becomes a big overhead and something I'd rather want a cleaner solution for.

What I'm currently doing is using a custom urql exchange that i wrote that omits excess props automatically in the client. It works great, but it comes at the cost that you'll need the schema metadata embedded in your bundle. So I'm in no rush to find a different solution, but I still wanted to open this discussion since I felt a bit weird about having to write my own urql exchange to enable my preferred workflow.

[kitten]

The extended answer here to narrow it down is that we don't and won't generate any runtime code: #263 (comment)

That's not a specific goal of the project.
This is basically a problem with all API inputs, and you could also pre-filter arguments on the server-side and instead warn about this if you're concerned about accidentally failing your requests due to smaller changes in the state.

However, I'd say, given the TypeScript constraint here that exact record types aren't possible, it's not too much trouble to map over inputs just before you send them off as a mutation. IMHO, from a perspective of writing out a couple of properties it isn't too bad.

If this does get more you could consider creating utilities for this, maybe.

[kasper573]

All right, got it. Then I'll keep my exchange approach 😄. Thanks for the answers!

[kitten]

Another idea, there's a chance that you could make a generic variables helper.
I don't have time to test this yet, but basically, you could make a function that compares the shape of variables to the nested shape of a variables-like object and disallows extra properties, i.e.

import type { DocumentDecoration } from 'gql.tada';

function variables<Variables extends {}, T extends {}>(
    _query: DocumentDecoration<any, Variables>,
    vars: T & Exact<Variables, T>
): Variables {
    return vars as Variables;
}

type Exact<Shape, T> = {
    [Key in keyof Shape | keyof T]: Key extends keyof Shape
        ? Key extends keyof T
            ? Shape[Key] extends any[]
                ? T[Key] extends any[]
                    ? Exact<Shape[Key][number], T[Key][number]>
                    : Shape[Key]
            : Shape[Key] extends readonly any[]
                ? T[Key] extends readonly any[]
                    ? Exact<Shape[Key][number], T[Key][number]>
                    : Shape[Key]
            : Shape[Key] extends { [key: string | number]: any }
                ? T[Key] extends { [key: string | number]: any }
                    ? Exact<Shape[Key], T[Key]>
                    : Shape[Key]
            : Shape[Key]
        : Shape[Key]
    : never
};

Just to be clear, I haven't tested this yet, but it's basically just a way of comparing the two generic shapes, and making sure that excess properties are marked as never on the input shape T.