Forem: Remi van der Laan

A journey towards a type-safe GraphQL API server

Remi van der Laan — Fri, 02 Dec 2022 15:20:36 +0000

Several years ago, we performed a big rewrite of our back-end codebase (now better known as The Great Migration), from a JavaScript monolith into a central GraphQL API written in TypeScript connected to a few micro services.
Since that time, we’ve continuously been upping our TypeScript game to help us guide development. One area that we’ve recently put effort into is configuring type generation for our API schemas.

Our main motivation for generating the types from our API schemas was removing ambiguity. Often in large or complex JavaScript codebases, unless you just wrote a piece of code yourself, you don’t know the exact content of a variable until inspecting it at runtime.
For a long time however, JavaScript’s ambiguity remained in our TypeScript codebase wherever data was coming in or out through an API. The types assigned for that data needed to be manually crafted and maintained whenever the API schema was updated, which is an error-prone process.

In this blogpost, we’re sharing our experience, learnings and desired improvements in generating TypeScript types for our NodeJS GraphQL API server.

Type generation for GraphQL servers

There are two main approaches to keeping the types of the GraphQL schema and entities in business logic in sync. You can generate the schema based on your TypeScript code (e.g. TypeGraphQL), or you can generate types based on your schema (e.g. GraphQL Code Generator). We opted for the latter since it slotted right into our existing GraphQL server implementation using Apollo Server.

The problem

Apollo Server does not provide type generation for resolvers out of the box. Therefore, in our initial implementation we just manually wrote type definitions that reflected the types in the schema. The schema types are enriched with extra fields which we write resolvers for:

// src/customers/customer.ts
export interface ICustomer {
 id: string;
 email: string;
 firstName: string;
 lastName: string;
}

// src/customers/schema.ts
const customerTypeDef = /* GraphQL */ `
 type Customer implements User {
   id: ID!
   firstName: String!
   lastName: String!
   houses: [House!]! # <- A resolved field
 }
`;


// src/customers/resolvers.ts
import { IObjectTypeResolver } from '@graphql-tools/utils';
import { ICustomer } from './customer';

type BaseResolverObject<T> = IObjectTypeResolver<T, ResolverContext, any>;

const customerResolvers: BaseResolverObject<ICustomer> = {
 async houses(customer, _, { context }): Promise<House[]> {
   return CustomerService.findHouses(context, customer.id);
 },
};

For simple resolvers that perform a look-up (like houses), this is not a problem. But with code that evolves fast, and types that are nearly identical to each other, mismatches between the schema and TypeScript definition will occasionally occur:

// src/customers/schema.ts
const mutationTypeDefs = /* GraphQL */ `
 input CustomerRegistrationInput {
   firstName: String!
   lastName: String!
   email: String!
   phone: String
   password: String!
 }

 extend type Mutation {
   registerCustomer(customer: CustomerRegistrationInput!): Customer!
 }
`;

// src/customers/resolvers.ts
const mutations: BaseResolverObject<never> = {
 async registerCustomer(
   _,
   { customer }: { customer: ICustomer & { password: string } },
   { context },
 ): Promise<Customer> {
   return CustomerService.register(context, customer),
 },
};

In cases like this one, it wasn’t uncommon for us to reuse existing type definitions (ICustomer) for the schema’s input types (CustomerRegistrationInput). These usually overlap sufficiently to work with, but more than often contain fields that don't exist on the actual input type or differ in terms of nullability.

The solution

GraphQL Code Generator can eliminate this ambiguity between the GraphQL Schema and TypeScript by generating the required TypeScript types from the GraphQL schema. With a relatively simple configuration file, the resolvers in the example above can be transformed into the following:

// src/customers/resolvers.ts with type generation
import { MutationResolvers } from '../generated/graphql';

const mutations: MutationResolvers = {
 async registerCustomer(_, { customer }, { context }): Promise<Customer> {
   return CustomerService.register(context, customer),
 },
};

The configuration file allows setting up a mapping between the type definitions of our own entities and the types generated through the schema. This allows us to receive and return our own types in the resolvers, keeping our business logic and API layer cleanly separated and reducing code duplication.

# codegen.yml
# Configuration documentation:
# https://www.graphql-code-generator.com/docs/plugins/typescript
# https://www.graphql-code-generator.com/docs/plugins/typescript-resolvers

schema: ${SCHEMA_PATH:http://localhost:4000/graphql}
documents: null
generates:
 ./src/generated/graphql.ts:
   plugins:
     - 'typescript'
     - 'typescript-resolvers'
     - add:
         content:
           - import { FileUpload } from 'graphql-upload';

   config:
     # Needed for apollo-server compatibility
     useIndexSignature: true
     contextType: ../BaseResolver#ResolverContext

     # Needed for our mixed use of null and undefined corresponding to nullable values in GraphQL
     maybeValue: T | null | undefined

     # Linking enums inserted into the schema back to their definition in TypeScript, so they don’t get re-generated
     enumValues:
       UserType: '../users/User#UserType'

     # Custom mapping to model types
     # https://www.graphql-code-generator.com/docs/plugins/typescript-resolvers#use-your-model-types-mappers
     mapperTypeSuffix: Model
     showUnusedMappers: true
     mappers:
       Customer: ../users/Customer#Customer

Once this configuration has been set up, any time after updating the schema, the types can be re-generated and the TypeScript compiler will tell you which resolvers need to be updated. By integrating this in the CI/CD pipeline too, the stability of the resolvers is improved greatly.

The configuration of GraphQL Code Generator is very flexible and is continuously being improved. For example, since type names in the schema and code usually overlap, the mapperTypeSuffix option was introduced to automatically redefine the mapped types in the generated code to append a keyword such as “Model”. Similarly for enums, since two identical enum definitions may not be compared in TypeScript, the configuration allows you to map the generated enums in the schema to those defined in your own code.

Benefits

Overall, it’s pretty great. Compared to our previous way of working, it prevents errors, reduces risk and saves us time by eliminating the error-prone process of writing and maintaining types manually. It also reduces code duplication and prevents mismatches in the schema versus the TypeScript types that represent the schema.

An unexpected benefit in our case is that it also enforces the schema to be properly defined. Some schema types that were set up in the very beginning of our use of GraphQL had all fields defined as nullable, and in rare cases fields we expected to be there were completely missing.

Issues we ran into

While the type generation setup we ended up with is really useful overall, it does leave some things to be desired:

The Maybe type

A major gripe we experience is due to GraphQL having no distinction between null and undefined: fields and arguments can just be nullable, which appear as Maybe<T> in the generated types. While null and undefined are similar, they are not interchangeable in JavaScript or TypeScript. Undefined indicates the lack of a value, while null indicates the existence of a value; just that it is null.

Although it is possible to define the Maybe type to just be null or undefined, both of them are needed in our current way of working. We expect nullable values in the schema on input types to be optional in TypeScript, meaning possibly undefined. However, we sometimes define an entity’s fields as possibly being null in TypeScript, which causes trouble when returning it in a resolver. Our usage of null comes from the decision to align with its use of our database client (MongoDB) for the ability to un-set the value of a field. A Partial type of an entity can be passed in an update method, where undefined values remain as-is and only fields explicitly set to null will be un-set.

interface IProduct {
 id: string;
 created: Date;
 /** Can be un-archived by setting this value to null */
 archived: Date | null;
}

...

async unArchiveProduct(id: string) {
 this.productRepository.updateOne(id, { archived: null });
}

For the moment, our Maybe type remains possibly both null or undefined. For input types, we usually strip off all null types using a DeepNonNullable type-cast, since it is not present on the vast majority of our entities.

Alternatively for our situation, null from the Maybe type could be omitted by dealing with the requirement of un-setting fields in the database in another way, such as setting up separate mutations for that purpose and moving the responsibility to the database layer.

type _DeepNonNullableArray<T> = Array<DeepNonNullable<NonNullable<T>>>;

type _DeepNonNullableObject<T> = {
 [P in keyof T]-?: DeepNonNullable<NonNullable<T[P]>>;
};

export type DeepNonNullable<T> = T extends any[]
 ? _DeepNonNullableArray<T[number]>
 : T extends Record<string, unknown>
 ? _DeepNonNullableObject<T>
 : NonNullable<T>;

Keeping generated types separate from business logic

Quickly after introducing generated types from our GraphQL schema, they started leaking into our business logic. Sometimes by accident, due to not paying attention to the automatic import functionality, and sometimes intentionally, to not having to bother with defining TypeScript definitions ourselves for trivial cases in our business logic.

After a while however, cryptic build errors started appearing. When a type that is mapped to in the generated file depends on a generated type, it creates an import cycle. These are notoriously hard to solve, and can appear out of nowhere after re-organizing imports of seemingly unrelated files as to what is causing the cycle. Therefore, we chose to only make use of the generated types in our resolvers: our business logic should remain free of them. To enforce this decision, a lint-rule was set up using the import/no-restricted-paths ESLint plugin:

"import/no-restricted-paths": [
 "error",
 {
   "zones": [
     {
       "target": "src/**/!(resolvers).ts",
       "from": "src/**/generated/graphql.ts",
       "message": "Generated GraphQL types may only be used in resolvers"
     }
   ]
 }
]

Along with our rule to not define business logic in resolvers, this reduces the potential of the generated types somewhat. Though, it does help to separate our API from the other layers in our codebase.
Usually the generated type and its match in the business logic are almost identical, so we can perform a type cast. TypeScript will warn us if there is a mismatch. Writing adapters to perform this task was considered, but disregarded to avoid introducing unneeded overhead. For now, input types are usually converted into our own types directly in the resolvers.

Mapped paths are not validated

A small nitpick: When updating the mapping of entities or enums in the codegen configuration, no warning or error is given when a mistake is made in a path or name of a type when generating the types. The need for updating the configuration is infrequent, so it’s only a small annoyance. For now, we’re relying on the TypeScript compiler to tell us about it in the build process.

Codegen configuration examples

While the documentation of GraphQL Codegen is decent, there aren’t many complex configuration examples to be found. We have posted ours earlier in this article. We based ours on threads like this one. We'd be interested to see more examples, best practices and tips 'n tricks.

Wrap up

Type generation has become one of the techniques we rely most on nowadays, because:

It saves time in maintaining two type definitions that should be identical
It prevents the error-prone process of maintaining mappings of one type definition to another
It reduces easily missed runtime errors by eliminating ambiguity
It helps to avoid introducing breaking schema changes as It enforces correct use of the schema
Writing types yourself is for mugs

Do you like GraphQL? Are you looking for work? Reach out! https://energiebespaarders.recruitee.com/

Creating a Sleek Masonry Gallery with React and WebAssembly

Remi van der Laan — Sun, 18 Apr 2021 21:25:35 +0000

Myself and three others have been working on a tool called Allusion in our spare time: A free image organization application built for artists. It runs in Electron as a ReactJS application.
One of its key components is the image gallery. Since users may import thousands of images, we can't just render them all using pure HTML and CSS. Over the course of the development, we tried out several out-of-the-box ReactJS packages (mainly react-window and react-virtualized) but none really suited our needs - be it their design or performance.
In the end, we wrote our own super slick image gallery from scratch. It turned out quite nice, so I wanted to share our findings.

The requirements we set for ourselves:

Keep as much as possible off the main UI thread to keep everything snappy
Keep computation time within a few milliseconds for up to ~10.000 images
Configurable thumbnail sizes
Three layout modes: A simple grid, vertical (column) masonry, horizontal (row) masonry

The main caveat of our method is that it needs to know image resolutions beforehand, though it could probably be adapted to measure them on the fly too. This is what made the alternatives we tried feel clunky, so we have avoided doing that. Since we store the image dimensions in a database anyways, it's no problem for for our use-case.

Our gallery is built-up out of three main sections:

The masonry layout algorithm itself, written in Rust
The webworker and shared memory between the main thread and WASM
The virtualized image renderer as a ReactJS component

Masonry algorithm in WebAssembly

Rust was was something I wanted to get into for a while already, and it's a natural fit for WASM modules.
The module is set-up with wasm-pack which outputs your WASM file along with TypeScript definitions as an easily importable ES6 module.

Transferring data

To provide the WASM package with the image dimensions it uses as input, we define a vector of Transform structs:

pub struct Transform {
    src_width: u16,
    src_height: u16,
}

We chose to read the output of the layout computation from the same entry, for which we'll need some extra fields:

pub struct Transform {
    src_width: u16, // input dimensions (pixels)
    src_height: u16,
    width: u16,     // output dimensions (pixels)
    height: u16,
    left: u16,      // output offset in the layout (pixels)
    top: u16,
}

We then define a Layout as follows:

pub struct Layout {
    num_items: usize,
    items: Vec<Transform>,
    thumbnail_size: u16, // the desired output size
    padding: u16,        // the amount of pixels in between two images
}

Back in JavaScript land, we ask for a pointer to that items vector in WASM memory, and put our image dimensions in there one by one:

impl Layout {
    pub fn items(&self) -> *const Transform {
        self.items.as_ptr()
    }
}

import { default as init, InitOutput, Layout } from 'masonry/pkg/masonry';
const WASM = await init('masonry/pkg/masonry_bg.wasm');
const layout = Layout.new(numItems);
const ptr = layout.items_ptr();
const items = new Uint16Array(this.WASM.memory.buffer, itemsPtr, MAX_ITEMS);

async function computeLayout(images: Image[]) {
  for (let i = 0; i < imgs.length; i++) {
    // Every item consists of 6 uint16s
    this.items![i * 6 + 0] = imgs[i].width;
    this.items![i * 6 + 1] = imgs[i].height;
  }
  await layout.compute(); // I'll cover this method next!
  // And now we can do something with the layout!
}
function getItemTransform(index: number) {
  return {
    width:  items[index * 6 + 2], // same order as in Rust
    height: items[index * 6 + 3],
    left:   items[index * 6 + 4],
    top:    items[index * 6 + 5],
  };
}

At first, we allocated memory for the transforms anytime the layout is computed, but in practice, the layout is re-computed many times over. To eliminate some overhead, we just reserve a chunk of memory which we use for the lifetime of the module. With just a few megabytes we can support hundreds of thousands of images.
One extra change was necessary: The top offset easily can grow beyond the uint16 of 65,536 pixels. For rows of 4 square images of 200px each, we reach that limit after only 81 rows. That's no good. Therefore, we moved the top offsets to a separate vector of unsigned uint32 values, which will last us over 5 million of such rows.

Layout algorithms

The vertical masonry layout is my personal favourite, so that's the one I'll be covering here. It's quite simple really: We determine the amount of columns that fit within the container width given the desired column width, and then iteratively place the images in the shortest column up to that point.

impl Layout {
    pub fn compute_vertical(&mut self, container_width: u16) -> u32 {
        // First: Determine width of each column and initialize each column height at 0 pixels
        let (col_width, mut col_heights) = {
            let container_width = f32::from(container_width);
            let n_columns = (container_width / f32::from(self.thumbnail_size)).round();
            if n_columns == 0.0 {
                return 0;
            }

            let col_width = (container_width / n_columns).round() as u16;
            let col_heights: Vec<u32> = vec![0; n_columns as usize];
            (col_width, col_heights)
        };
        let item_width = col_width - self.padding;

        // Then loop over all images and place them in the shortest column
        let (current_items, _) = self.items.split_at_mut(self.num_items);
        for (item, top_offset) in current_items.iter_mut().zip(self.top_offsets.iter_mut()) {
            // take into account aspect ratio for the height
            item.height = ((f32::from(item.width) / f32::from(item.src_width)) * h).round() as u16;
            item.width = item_width;

            let shortest_col_index = col_heights
                .iter()
                .enumerate()
                .min_by_key(|(_idx, &val)| val)
                .map_or(0, |(idx, _val)| idx);

            item.left = shortest_col_index as u16 * col_width;
            *top_offset = col_heights[shortest_col_index];

            col_heights[shortest_col_index] += u32::from(item.height) + u32::from(self.padding);
        }

        // Return height of longest column
        col_heights.iter().max().map_or(0, |max| *max)
    }
}

Performance

Now, is this any good in practice? Well, I implemented the same layout computation function in TypeScript (transpiled down to JavaScript), and measured the performance of both for a gallery of 5000 images in release mode:

It's a solid 0.2ms faster! Yeah... WebAssembly might have been a little overkill for a simple O(1) calculation like this. It might be even worse than the TS equivalent, since we need to put all of the image dimensions in a buffer first. Though, it does pave the way for a more complex layout computation (I'll link to some resources at the end) for which I'm sure it would pay off.
As for the high peaks in the WASM measurements, I'm not completely sure what causes those. I would have expected those to happen for the TS version instead, since Rust doesn't do garbage collection. I couldn't find any weird things happening in the glue code generated by wasm-pack so I suspect it must be something from the WebAssembly runtime itself.

WebWorker with shared memory

Even though the computation only takes less than a millisecond on my machine, it might not on low-end devices or under heavy load.
By computing the layout in a WebWorker, it won't interrupt the main UI thread, meaning that the application will stay responsive.
We opted for setting up a WebWorker using com-link, mainly for its ease of use.
We don't want to copy the memory buffer every time a message is sent from the worker. Figuring out how to set up shared memory between the WASM memory in the worker and the main thread was the biggest time sink of this adventure.
At first we sent the buffer as a Transferrable but this stopped working in a recent release of Chrome. Instead, we configure the WASM memory to become a SharedArrayBuffer, which has the same capability. This is not supported out of the box: follow this guide to learn more.

// masonry.worker.ts
import { default as init, InitOutput, Layout } from 'masonry/pkg/masonry';
import { expose } from 'comlink';

export class MasonryWorker {
  WASM?: InitOutput;
  layout?: Layout;
  items?: Uint16Array;
  initializeLayout(numItems: number): Uint16Array {
    this.WASM = await init('./wasm/masonry/pkg/masonry_bg.wasm');
    this.layout = Layout.new(numItems);
    const itemsPtr = this.layout.items();
    const sharedArrayBuffer = this.WASM.__wbindgen_export_0.buffer;
      this.items = new Uint16Array(sharedArrayBuffer, itemsPtr, MAX_ITEMS);
    return this.items;
  }
}
expose(MasonryWorker, self);

// MasonryWorkerAdapter.ts
import { Remote, wrap } from 'comlink';
import MasonryWorkerClass, { MasonryWorker } from './masonry.worker';

export class MasonryWorkerAdapter {
  worker?: Remote<MasonryWorker>;

  async initialize(numItems: number) {
    const WorkerFactory = wrap<typeof MasonryWorker>(new MasonryWorkerClass());
    this.worker = await new WorkerFactory();
    this.items = await this.worker.initializeLayout(numItems);
    // And now here in the main thread we can access WASM memory that was initialized in the worker!
  }
}

Virtualized gallery renderer

The last step is to actually render the images in the layout that is computed. Since this is intended for a ReactJS application, the images are rendered as DOM nodes, but the same layout could also be used to render images in a canvas.
We could just put all images in the DOM since the browser is very good at rendering only whatever visible is in the viewport. We can make it lots faster though, by only putting images that are visible in the viewport in the DOM tree. This is called "virtualized rendering".
Any time the viewport dimensions change, or the user scrolls, or for any similar events, we have to re-evaluate which images to render.

const VirtualizedRenderer = ({ containerWidth, images }: VirtualizedRendererProps) => {
  const layout = useMemo(() => ..., []);
  const viewportRef= useRef<HTMLDivElement>(null);
  const containerHeight = useMemo(() => layout.recompute(containerWidth), [containerWidth]);

  // Find the top and bottom edge of the viewport in the layout (omitted for brevity: we do a binary search)
  const [startRenderIndex, endRenderIndex] = determineViewportRegion(layout, viewportRef.scrollTop, viewportRef.clientHeight);

  return (
    // One div as the scrollable viewport
    <div className={className} onScroll={handleScroll} ref={viewportRef}>
      {/* One div for the content */}
      <div style={{ width: containerWidth, height: containerHeight }}>
        {images.slice(startRenderIndex, endRenderIndex + 1).map((im, index) => {
          const fileListIndex = startRenderIndex + index;
          const transform = layout.getItemLayout(fileListIndex);
          return (
            <img
              key={im.id}
              style={transform}
              src={im.src}
            />
          );
        })}
      </div>
    </div>
  );
};

Putting it all together, this is what we ended up with (links to a video on Imgur):

Conclusion

Computing the masonry layout runs great performance-wise. It's also much smoother while scrolling and more flexible compared to popular packages available on NPM we tried out.
Making use of WebAssembly was not really worth the hassle in the end, since the computation is fairly simple. Though, it was a good scope for a problem to learn some Rust for. Running the computation in a WebWorker makes all the difference though. Use workers, people!

There are certainly improvements to be made. You could for instance only compute the layout for the relevant section of the viewport you are in.
There are much bigger bottle necks in the code surrounding the layout computation through: It may take dozens of milliseconds to fetch thousands of images from the database and to insert their image resolutions into WASM memory. This could be solved by streaming in data as it is being fetched. For both of these it would add some unnecessary complexity for our current use case, so we're calling it a day at this point!

Resources:

The Allusion homepage - download it for free!
The final implementation: Masonry algorithm in Rust, Webworker, Masonry renderer which makes use of the Virtualized renderer
Similar blogpost: Building the Google Photos image grid