Repository files navigation

dataloader-codegen is an opinionated JavaScript library for automagically generatingDataLoaders over a set of resources (e.g. HTTP endpoints), with a predictable interface, and maintains type safety.

Read more about the motivation behind this library in our recent blog post:https://engineeringblog.yelp.com/2020/04/open-sourcing-dataloader-codegen.html

Features:

• 🚚 Supports Batched + Non Batched Resources
• ✨ Predictable DataLoader Interfaces
• 🐛 Error Handling
• 🔒 Type Safety (TypeScript)
• 🔧 Resource Middleware

$ yarn add --dev dataloader-codegen

See:https://engineeringblog.yelp.com/2020/04/open-sourcing-dataloader-codegen.html

We believe the DataLoader layer should be (mostly) transparent when implementinga GraphQL server over a set of existing resources (e.g. HTTP API Endpoints).

When fetching data, GraphQL resolver authors should think in terms of theunderlyingresources that they're already familiar with, not an invented setof human defined DataLoaders.

With dataloader-codegen, we build a1:1 mapping of resources to DataLoaders:

This makes it super easy to find the DataLoaders you want - there will beexactly 1 DataLoader available per resource, with a predictable name and interface.

This meansreduced risk of making unnecessary HTTP requests.

If there were (accidentally!) multiple DataLoaders created for a singleendpoint, we potentially lose out on batched requests to that resource.

By keeping the mapping of one DataLoader per resource, we reduce that riskand can make a more efficient set of HTTP requests to the underlying resource.

1. Createdataloader-config.yaml to describe the shape and behaviour of your resources. (Seethe docs for detailed info.)

   Example

   resources:getPeople:docsLink:https://swapi.dev/documentation#peopleisBatchResource:truebatchKey:people_idsnewKey:person_idgetPlanets:docsLink:https://swapi.dev/documentation#planetsisBatchResource:truebatchKey:planet_idsnewKey:planet_id...

   (Can be arbitrarily nested. See theswapi example for an example.)

2. Calldataloader-codegen and pass in your config file:

   $ dataloader-codegen --config swapi.dataloader-config.yaml --output __codegen__/swapi-loaders.js

   See--help for more options.

3. Import the generated loaders and use them in yourresolver methods:

   importgetLoadersfrom'./__codegen__/swapi-loaders';// StarWarsAPI is a clientlib containing fetch calls to swapi.dev// getLoaders is the function that dataloader-codegen generates for usconstswapiLoaders=getLoaders(StarWarsAPI);classPlanet{constructor(id){this.id=id;}asyncdiameter(){const{ diameter}=awaitswapiLoaders.getPlanets.load({planet_id:this.id});returndiameter;}}

   Check out theswapi example to see a working example of this.

TheDataLoader.load interfaceaccepts a single key and returns a single value. Forbatch resources, we'll need to transform the DataLoader interface accordingly.

Example

Consider the following resource that returns information about users:

constgetUserInfo=(args:{user_ids:Array<number>,locale:string,include_slow_fields?:boolean,}):Promise<Array<UserInfo>>=>fetch('/userInfo',args);

This is abatch resource that accepts a list of users (user_ids) and returns a list of corresponding user objects (Array<UserInfo>).

For the DataLoader version of this, we'll want to instead ask for asingle userobject at a time. This means we need to transform the interface in the followingways:

1. Call.load with the same arguments, but switch "user_ids" to "user_id".

2. Return asingleUserInfo object from.load, instead of anarray ofUserInfo objects.

We can control this by specifyingbatchKey andnewKey in the config todescribe the relevant argument in the resource and DataLoader respectively.

The config for ourgetUserInfo would therefore look like this:

resources:getUserInfo:isBatchResource:truebatchKey:user_idsnewKey:user_id

Seethe full docs for more information on how to configure resources.

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

SeePUBLISH.md

MIT