Green Donut is a DataLoader implementation for .net core and classic
Clone or download

README.md

GreenDonut

GitHub release NuGet Package License Build Tests Coverage Status Quality BCH compliance Join the chat at https://gitter.im/ChilliCream/greendonut


Green Donut is a DataLoader implementation for .net core and classic

Here is a short sentence how facebook describes DataLoaders.

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. -- facebook

DataLoaders are a perfect fit for client-side and server-side scenarios. They decouple any kind of request to a back-end component or resource. This will reduce in general the traffic (round-trips) to e.g. a GraphQL API, REST API, DB, or something completly else.

Getting Started

Before we start let us install the package via NuGet.

For .net core we could use the dotnet CLI. Which is perhaps the preferred way doing this.

dotnet add package GreenDonut

And for .net classic we still could use the following line.

Install-Package GreenDonut

Of course there are more ways to install a package. However, I just focused here on the most common console way for both .net core and classic.

After we have installed the package, we should probably start using it, right. We really tried to keep the API of DataLoaders congruent to the original facebook implementation which is written in JavaScript, but without making the experience for us .net developers weird.

var userLoader = new DataLoader<string, User>(keys => FetchUsers(keys));

In order to change the default behavior of a DataLoader, we have to create a new instance of DataLoaderOptions and pass it right into the DataLoader. Let us see how it would look like.

var options = new DataLoaderOptions<string>
{
    SlidingExpiration = TimeSpan.FromHours(1)
};
var userLoader = new DataLoader<string, User>(keys => FetchUsers(keys), options);

So, what we see here is that we have changed the SlidingExpiration from its default value, which is 0 to 1 hour. 0 means the cache entries will live forever in the cache as long as the max cache size does not exceed. Whereas 1 hour means a single cache entry will stay in the cache as long as the entry gets touched within one hour. This is an additional feature that does not exist in the original facebook implementation.

API

Methods Description
Clear() Empties the complete cache.
DispatchAsync() Dispatches one or more batch requests. In case of auto dispatching we just trigger an implicit dispatch which could mean to interrupt a wait delay. Whereas in a manual dispatch scenario it could mean to dispatch explicitly.
LoadAsync(key) Loads a single value by key. This call may return a cached value or enqueues this single request for bacthing if enabled.
LoadAsync(keys) Loads multiple values by keys. This call may return cached values and enqueues requests which were not cached for bacthing if enabled.
Remove(key) Removes a single entry from the cache.
Set(key, value) Adds a new entry to the cache if not already exists.

Best Practise

  • Consider using a DataLoader instance per request if the results may differ due to user privileges for instance.

Documentation

For more examples and a detailed documentation click here.