Forem: Jonas Antvorskov

Errors are results

Jonas Antvorskov — Fri, 15 Jan 2021 11:01:57 +0000

Errors, Faults & Failures

When writing a server, errors are inevitable, but a distinction should be made between errors caused by things outside the client's control, such as your database crashing - I'll refer to these as Faults. Errors caused by things that are within the client's control, such as attempting to get an entity the client doesn't have access to - I'll refer to these as Failures.

Faults are in their nature temporal and fleeting, whether through automatic corrections made by the system itself, such as the database restarting, or fixes manually implemented by the maintainers of the system. This means that they can safely be omitted from your GraphQL schema because when they occur, the client has no meaningful course of action to mitigate the problem other than waiting for the issue to be fixed.

Failures, on the other hand, are persistent when attempting to get an entity the client doesn't have access to, the client does have meaningful courses of action to correct the issue, for example: not requesting the resource again or informing the user they don't have access. Because of this, it makes sense to treat these failures the same as you would a result. This means that any failures that can occur when resolving a field in a GraphQL server should be declared as part of a union type expressing the possible value types of a given field.

Making Failures Type-safe

In order to make failures as results type-safe without having to add extensive logic around handling errors to the majority of functions within your GraphQL server, while making sure that all failure results are handled.

I suggest using a Result pattern inspired by Rust. This pattern can be used to great effect in TypeScript. It allows us to have both the successful result typed and any possible failures to be typed.

  getUserById(id: string): AsyncResult<UserDataModel, NotFoundError | InvalidIdentifierError> {
    return this.identifierService.user.parse(id)
      .andThenAsync((id) => this.users.load(id.value));
  }

This is an example of what the Result pattern looks like, when in use. This is a function on a user service that attempts to fetch a user. First, the identifierService parses the given string ID into the correct format for the underlying service. This results in an object of type Result<Identifier<'User'>, InvalidIdentifierError> if the ID is valid, the result object contains that parsed ID value. If it is invalid, it contains the InvalidIdentifierError. We can then call andThenAsync on the result object. This is essentially a map function that is only invoked if the result isn't an error and must return a new result object. The lambda function in this example returns the type Result<UserDataModel, NotFoundError>, this type is merged with the result type returned by the identifierService into the final return type of the function.

All of this simplifies the way failures are handled because we only need to care about them when we actually want to process the errors specifically. If we don't have any way to remedy the issue on the server, it should ultimately be returned to the client as a result, and if we don't encounter an error, we can just map an intermediate result to a new result.

When generating a new result, the pattern is also trivial to use. The following is an example of how the identifierService.user.parse(id) method is implemented:

  idMatcher = /(\w+)\/(0|[1-9][0-9]*)/;
  parse(id: string): Result<Identifier<Prefix>, InvalidIdentifierError> {
    const idMatch = idMatcher.exec(id);
    return idMatch && idMatch[1] === this.prefix
      ? Result.ok(new Identifier(this.prefix, parseInt(idMatch[2], 10)))
      : Result.error(new InvalidIdentifierError(id));
  }

Here, the string is matched against a regex and a prefix. If it doesn't match, Result.error() is called, and generates an error result. If it does match, Result.ok() is called to generate a successful result.

Declaring the Schema

When declaring fields on the schema where the field should be resolved with the Result pattern described above, the field should resolve to a union type. As an example, this is how this would be declared using GraphQL Nexus:

export const UserResponse = unionType({
  name: 'UserResponse',
  description: 'The type of the possible results from the user query',
  definition(t) {
    t.members(User, GraphQLNotFoundError, GraphQLInvalidIdentifierError);
    t.resolveType((root) => root.__typename);
  },
});

Unfortunately, there doesn't seem to be any way to add a resolver to the union type, so we can pass it a Result type object and let it unpack the object to the underlying value, thus we have to add a method to the Result class which should be called on the Result object returned to a field that should resolve to a union type like this.

A field that resolves to a union type like this in GraphQL Nexus would be declared like this:

  t.field('user', {
    type: UserResponse,
    nullable: false,
    args: {
      id: idArg({ required: true }),
    },
    resolve: (_, { id }, ctx) => ctx.users.getUserById(id).collect(),
  }),

Here the .collect() function call unwraps the AsyncResult<UserDataModel, NotFoundError | InvalidIdentifierError> type object to a Promise<UserDataModel | NotFoundError | InvalidIdentifierError> type object.

Summary

Treating failures as results and declaring them as return options on the field level, makes it apparent and encourages the consumer of your GraphQL API to handle the failures that can be encountered for any given field, and it localizes the data to where it belongs in the result data structure, instead of having it in the errors array on the request-response with a path to where the error originated.

Resources

A demo project utilizing all the techniques described can be found here.

GraphQL as a typesafe contract for your domain!

Jonas Antvorskov — Fri, 27 Nov 2020 09:44:15 +0000

Building type-safe GraphQL schemas with @nexus/schema and TypeScript

In this post, I will discuss how @nexus/schema can be used to construct a typesafe GraphQL schema. I will assume that the reader has a passing familiarity with GraphQL. If interested in learning the basics of GraphQL look up GraphQL's homepage on https://graphql.org/learn/.

Motivation

When writing type-safe GraphQL implementations based on graphql-js in the past, the developer always had to take great care to supply the correct types to all resolvers themselves. Providing the correct types was often error prone; you either had to reference a common type export from the consuming and producing resolver, or take great care to track down all consuming and producing resolvers related to a type if it ever changed. @nexus/schema seeks to make this largely a thing of the past; by combining new type constructors wrapping vanilla graphql-js type constructors and allowing the developer to supply a few type imports, this allows @nexus/schema to generate typescript artifacts when you run your schema. This makes it possible to see most type errors you've made in relation to your schema before even having to test it.

makeSchema

The makeSchema function is what ties everything together and makes the magic of @nexus/schema happen. In order to generate the appropriate type artifacts this function needs to be given the correct configuration, this includes references to all types used by your schema.

export const schema = makeSchema({
  types: [...schemaTypes, ...scalars],
  outputs: {
    schema: path.resolve('./src/generated/schema.graphql'),
    // where to save the schema declaration artifact
    typegen: path.resolve('./src/generated/typings.ts'),
    // where to save the typescript schema definitions artifact
  },
});

Here we provide the config with all types used in the schema and instruct @nexus/schema in where to output the SDL schema artifacts and the typescript typing artifacts, these generated files should ideally not be included in your git repository and should instead be generated ad-hoc in your CI pipeline.

In the schema configuration you should also provide some configuration for where the Context type can be found for the schema.

export const schema = makeSchema({
  ...,
  typegenAutoConfig: {
    sources: [
      {
        source: path.resolve(__dirname, './context.ts'),
        // this points to where the RequestContext type can be imported from
        alias: 'ctx',
        // the alias the module containing the RequestContext type is given in the schema typings artifact
      },
    ],
    contextType: 'ctx.RequestContext',
    // the path to the RequestContext in the typings artifact
  },
});

This instructs @nexus/schema to import the file './context.ts' which is collocated to the file performing the makeSchema function call and using the type exported from that module called RequestContext as the type of the Context parameter for all resolvers in your schema.

Creating schema types

Schema types for a @nexus/schema schema are constructed through the use of a set of constructor methods, each of which takes a config object; containing among other things the name of the type, and an optional description of it.

objectType: This function is used for constructing the underlying GraphQLObjectType. The config must be provided with a definition function which takes an ObjectDefinitionBlock parameter. This parameter is what is used to add fields to the type by calling methods named after the type the field should return or by calling field and providing it with the correct return type of the field. Each of these functions must be provided with the name of the field that they are adding and a config for the field containing a resolve function, this function becomes typesafe after the type artifacts have been generated. The ObjectDefinitionBlock is also used to instructing GraphQL that the object type should implement an interface through the use of the implements method.
interfaceType: The interfaceType function works much the same as the objectType function, it is used to construct the underlying GraphQLInterfaceType.
unionType: This function is used to constructing the underlying GraphQLUnionType. The config for this type must be provided with a definition function which takes a UnionDefinitionBlock. This is used to add members to the type through the members method, and instructing graphql-js in how to determine which member type a given object, returned to a field that should resolve to the union type, should resolve to.
extendType: This function is used to append an existing object type. It should be given a config containing the type that is being extended and a definition function like objectType which adds any new fields.
queryField: This is a decorated version of the extendType function which only acts on the Query type and thus is only given the definition function. It should be used to declare any queries possible in the schema.
mutationField: This is a decorated version of the extendType function which only acts on the Mutation type and thus is only given the definition function. It should be used to declare any mutations possible in the schema.
enumType: The enumType function is used to construct the GraphQLEnumType. This function must be given the set of members of the enum through the members property.
scalarType: The scalarType function is used to construct scalar types. These types have special handling, if asNexusMethod is set to true in their config they will become available on the ObjectDefinitionBlock type. The config should also specify 3 functions:
- parseLiteral: This function is used to parse the value of the field if written in the SDL.
- parseValue: This function is used to parse the value of the field if given as a parameter.
- serialize: This function is used to transform the value given to the field to a scalar value to be transferred to the client.

rootTyping

You should only specify the rootTyping property when declaring an object, interface, or scalar type, when specifying other types @nexus/schema is smart enough to infer the correct type graphql-js will be expecting. Specifying another type for these cases is more likely to trip you up than to give you any benefit.

When specifying the rootTyping I always use __filename for the path property. This variable contains the absolute path to the current module. This means that if I ever move the file, I don't have to worry about changing the file import paths manually - I simply have to generate new artifacts. If the declaration of a schema type is not collocated with its root type; I suggest placing the RootTypingImport with the type declaration and importing that constant to the schema type declaration in order to maintain this behavior.

Runtime

Setting up a runtime configuration for running a @nexus/schema server is made a lot easier by using ts-node, it removes the need for adding .js and .js.map files to your .gitignore and having to filter them out in your editor of choice; or outputting your typescript compilation to a separate dist folder, and thus doesn't change the value of the __filename variables in the runtime.

Generating artifacts and making changes

When working on your schema you will from time to time need to verify that the changes you've made to the schema are typed correctly before finalizing all the schema changes you're making to the server. To do this, you need to generate new artifacts for the schema. This can be simplified by adding a check to the makeSchema constructor:

export const schema = makeSchema({
  ...,
  shouldExitAfterGenerateArtifacts: process.argv.includes('--nexus-exit'),
  // if the --nexus-exit param is given to the process, exit after the schema artifacts have been generated
});

And using the following script to generate the type artifacts:

"scripts": {
  "generate": "yarn ts-node ./src/server --nexus-exit",
},

This script will run the schema up to the point where the artifacts are generated, and then exit. This is useful behavior when working on the schema since the correctness of the types can only truly be ascertained after the new artifacts are generated. This script would also be useful to run as a step in your CI process, as it allows you to remove the generated artifacts from your git repository improving clarity of pull requests.

Sometimes you will need to make changes to your schema, or how some field should be resolved. This can be a hassle if you've already generated the type artifacts for the schema earlier, and you're running on ts-node. To resolve this issue, use the following script:

"scripts": {
  "generate:force": "yarn ts-node --log-error ./src/server --nexus-exit",
},

With the --log-error flag set, ts-node will find just any type errors and still execute the script. This means, you can generate your new type artifacts even when in the middle of making a large set of changes where your server won't compile correctly until all changes are finalized, giving you invaluable type checking for the changes you've already made. The errors reported by the script should generally be ignored though, since they will be based on the old type artifacts.

Resources

A demo project utilizing all the techniques described can be found here.