DataLoader is a generic utility to be used as part of your application's data fetching layer to provide a consistent API over various backends and reduce requests to those backends via batching and caching.
name
in Dataloader instance types by @henrinormak in https://github.com/graphql/dataloader/pull/334
Full Changelog: https://github.com/graphql/dataloader/compare/v2.2.1...v2.2.2
Full Changelog: https://github.com/graphql/dataloader/compare/v2.2.0...v2.2.1
name
to DataLoader
by @SimenB in https://github.com/graphql/dataloader/pull/326
Full Changelog: https://github.com/graphql/dataloader/compare/v2.1.0...v2.2.0
loader.load()
error message https://github.com/graphql/dataloader/commit/249b2b966a8807c50e07746ff04acb8c48fa4357
setImmediate
. setImmediate || setTimeout
doesn't work and it throws setImmediate
is not defined in this case, so we should check setImmediate with typeof. And some environments like Cloudflare Workers don't allow you to set setTimeout directly to another variable. https://github.com/graphql/dataloader/commit/3e62fbe7d42b7ab1ec54818a1491cb0107dd828a
This is the first release since becoming part of the GraphQL Foundation and the most significant since the initial release over four years ago. Read more about the history of the project and this release in the blog post.
Breaking:
.loadMany()
now returns an array which may contain Error
if one of the requested keys failed.
Previously
.loadMany()
was exactly the same as callingPromise.all()
on multiple.load()
calls. While syntactically a minor convenience, this wasn't particularly useful over what could be done withPromise.all
directly and if one key failed, it meant the entire call to.loadMany()
would fail. As of this version,.loadMany()
can now return a mix of values andError
instances in the case that some keys failed, but the Promise it returns will never be rejected. This is similar to the behavior of the new Promise.allSettled method in the upcoming version of JavaScript.This will break any code which relied on
.loadMany()
. To support this change, either ensure the each item in the result of.loadMany()
are checked againstinstanceof Error
or replace calls likeloader.loadMany([k1, k2])
withPromise.all([loader.load(k1), loader.load(k2))
.
batchLoadFn
when { batch: false }
has changed to the end of the run-loop tick.
Previously when batching was disabled the
batchLoadFn
would be called immediately when.load()
is called. This differed from thebatchLoadFn
being called at the end of the tick of the run-loop for when batching was enabled. This timing difference could lead to subtle race conditions for code which dynamically toggled batching on or off. As a simplification, thebatchLoadFn
is now always called at the end of the run-loop tick regardless of whether batching is disabled.Hopefully this will not break your code. It could cause issues for any code which relied on this synchronous call to
batchLoadFn
for loaders where batching was disabled.
Previously when
.load()
encountered a cached value it would return an already resolved (or rejected) Promise. However when additional dependent loads happened after these, the difference in time between the cache hit value resolving and the cache miss value resolving would result in additional unnecessary network requests. As of this version when.load()
encounters a cached value it returns a Promise which waits to resolve until the call tobatchLoadFn
also resolves. This should result in better whole-program performance and is the most significant conceptual change and improvement. This is actually not a new innovation but a correction to match the original behavior of Facebook's "Loader" from 2010 this library is inspired by.This changes the timing of when Promises are resolved and thus could introduce subtle behavioral change in your code, especially if your code is prone to race conditions. Please test carefully.
This also means each return of
.load()
is a new Promise instance. Where prior versions returned the same Promise instance for cached results, this version does not. This may break code which uses the returned Promise as a memoization key or in some other way assumed reference equality.
This really shouldn't break your code because you definitely don't reach into class private variables, right? I just figured it would be something you'd like to know, you know... just in case.
New:
this
in batchLoadFn
The dirty secret of DataLoader is that most of it is quite boring. The interesting bit is the batch scheduling function which takes advantage of Node.js's unique run-loop scheduler to acheive automatic batching without any additional latency. However since its release, ports to other languages have found this bit to be not be easily replicated and have either replaced it with something conceptually simpler (like manual dispatch) or with a scheduler custom fit to a GraphQL execution engine. These are interesting innovations which deserve ground for experimentation in this original library as well.
Via
batchScheduleFn
, you can now provide a custom batch scheduling function and experiment with manual dispatch, added latency dispatch, or any other behavior which might work best for your application.
Types:
cacheKeyFn
and cacheMap
batchLoadFn
to return a PromiseLike
, supporting use of bluebirdbatchLoadFn
to return ArrayLike
, supporting returning read-only arraysError
to .prime()
Fixes:
Error
to .prime()
could incorrectly cause an unhandled promise rejection warningDocumentation:
cacheMap
along with an LRU example.batchLoadFn
.batchLoadFn
.New:
Note: Dataloader in the browser cannot rely on the same post-promise job queuing behavior that allows for best performance in Node environments. A fallback behavior is used in a browser.
This leads to better error messages when in use with custom caches that do not provide the full required interface. It may now produce eager errors where latent bugs were allowed in prior versions.
Fixed:
require("dataloader")
(#135)Due to more recent versions of Flow treating
Array
as invariant, DataLoader uses$ReadOnlyArray
which is covariant.
New:
README.md
reworked and improved and more information in examples/
.New:
Prime values in the cache - #18. — If you have values cached locally, this provides an API for adding those already known values to a DataLoader cache:
let loader = new DataLoader(keys => promiseToGetKeys(keys));
loader.prime('abc', 'My Value');
loader.load('abc').then(val => console.log(val)); // Logs "My Value"
This also works for priming errors:
let loader = new DataLoader(keys => promiseToGetKeys(keys));
loader.prime('abc', new Error('My Error'));
loader.load('abc').catch(err => console.log(err)); // Logs "My Error"
This is particularly useful for allowing two loaders to interact based on two fetchable keys for one type:
let userByIDLoader = new DataLoader(ids => promiseToGetByID(ids).then(users => {
for (let user of users) {
userByUsernameLoader.prime(user.username, user);
}
return users;
}));
let userByUsernameLoader = new DataLoader(names => promiseToGetByUsername(names).then(users => {
for (let user of users) {
userByIDLoader.prime(user.id, user);
}
return users;
}));
New:
Provide a custom cache-key function. #15 — Since JavaScript does not use value equality, but fetch keys are often treated as values, this allows for a custom function to be provided to produce a cache-key for any load-key. Example:
var loader = new DataLoader(keys => promiseToGetKeys(keys), { cacheKeyFn: key => key._id });
var first = loader.load({ _id: 'abc123' });
var second = loader.load({ _id: 'abc123' });
assert(first === second);
Provide a custom cache instance. #17 — By default, DataLoader uses a Map as a cache. However this simple cache does not support anything like TTL or a cache eviction policy. Now you may provide any object which implements the Map API to use as a cache. Example:
var loader = new DataLoader(keys => promiseToGetKeys(keys), { cacheMap: new LRUCacheMap() });
Initial release! See README.md for API details and please report bugs using github issues.