Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/joonhocho/batchloader
BatchLoader is a utility for data fetching layer to reduce requests via batching written in TypeScript. Inspired by Facebook's DataLoader. Works great with GraphQL, MongoDB, Mongoose, etc.
https://github.com/joonhocho/batchloader
Last synced: about 1 month ago
JSON representation
BatchLoader is a utility for data fetching layer to reduce requests via batching written in TypeScript. Inspired by Facebook's DataLoader. Works great with GraphQL, MongoDB, Mongoose, etc.
- Host: GitHub
- URL: https://github.com/joonhocho/batchloader
- Owner: joonhocho
- License: mit
- Created: 2018-10-04T05:12:10.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-04T04:21:36.000Z (almost 2 years ago)
- Last Synced: 2024-11-10T10:38:25.435Z (about 2 months ago)
- Language: TypeScript
- Homepage:
- Size: 1.06 MB
- Stars: 35
- Watchers: 4
- Forks: 1
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# BatchLoader
BatchLoader is a batching utility for data fetching layer to reduce requests round trips, inspired by [Facebook's DataLoader](https://github.com/facebook/dataloader), written in [TypeScript](https://www.typescriptlang.org/index.html).
BatchLoader is a simplified version of Facebook's DataLoader and can be used with any database such as MongoDB or with GraphQL.
[](https://travis-ci.org/joonhocho/batchloader)
[](https://coveralls.io/github/joonhocho/batchloader?branch=master)
[](https://badge.fury.io/js/batchloader)
[](https://david-dm.org/joonhocho/batchloader)
[](http://doge.mit-license.org)
## Comparison to DataLoader
\+ written in TypeScript
\+ Further reduces data fetching requests by filtering out duplicate keys
\+ Similar api as DataLoader
\+ Smaller in size (0 dependencies)
\+ MappedBatchLoader can be used to compose a new loader using existing loaders.
\- Removed caching functionalities. Leave caching to better cache libraries.
It is a very simple batcher that only does batching, and it does it very well.
## Getting Started
First, install BatchLoader using npm.
```sh
npm install --save batchloader
```
or with Yarn,
```sh
yarn add batchloader
```
> Note: BatchLoader assumes a JavaScript environment with global ES6 `Promise`, available in all supported versions of Node.js.
## Batching
Create loaders by providing a batch loading function and key transformation function (used for finding duplicate keys).
```typescript
import { BatchLoader } from 'batchloader';
const userLoader = new BatchLoader(
(_ids: ObjectId[]) => User.getByIds(_ids), // [required] batch function.
(_id: ObjectId) => _id.toString(), // [optional] key to unique id function. must return string. used for finding duplicate keys.
100 // [optional = 0] batch delay in ms. default 0 ms.
);
const user1 = await userLoader.load(id1);
const [user1, user2] = await userLoader.loadMany([id1, id2]);
const [user1, user1, user1] = await userLoader.loadMany([id1, id1, id1]); // batch function receives only one id1 since duplicate ids. Still returs three items just as requested.
const [user1, user2, user3, user2, user1] = await Promise.all([
userLoader.load(id1),
userLoader.load(id2),
userLoader.load(id3),
userLoader.load(id2),
userLoader.load(id1),
]); // batch function receives [id1, id2, id3] only without duplicate ids.
```
#### Batch Function
A batch loading function must be of the following type:
```typescript
(keys: Key[]) => Value[] | Promise // keys.length === values.length
```
Constraints
- keys.length === values.length
- keys[i] => values[i]
- keys.length > 0
#### KeyToUniqueId Function
A function must return string value given a key:
```typescript
(key: Key) => string
```
If key is not uniquely identifiable, simply pass `null` instead. This will disable filtering out duplicate keys, and still work the same way.
```typescript
const loader = new BatchLoader(
(keys: Key[]) => loadValues(keys),
null // keys cannot be transformed into string. no duplicates filtering.
);
const v1 = await loader.load(k1);
const [v1, v2, v1] = await loader.loadMany([k1, k2, k1]); // batch function receives [k1, k2, k1] as keys
```
## MappedBatchLoader
You can map a loader to create another loader.
```typescript
import { MappedBatchLoader } from 'batchloader';
const getUsername = (user) => user && user.username;
const usernameLoader = userLoader.mapLoader(getUsername);
// or
const usernameLoader = new MappedBatchLoader(userLoader, getUsername);
// same APIs as BatchLoader
const username = await usernameLoader.load(userId);
const [username1, username2] = await usernameLoader.loadMany([userId1, userId2]);
const [user1, username1] = await Promise.all([
userLoader.load(id1),
usernameLoader.load(id1),
]) // one round-trip request with keys being [id1], since usernameLoader is using userLoader internally and id1 is duplicate.
const anotherMappedLoader = usernameLoader.mapLoader(mapFn);
// or
const anotherMappedLoader = new MappedBatchLoader(usernameLoader, mapFn);
```
## Caching
Unlike DataLoader, BatchLoader does not do any caching.
This is intentional, because you may want to use your favorite cache library that is best suited for your own use case.
You can add caching ability easily like so:
```typescript
let userCache = {};
const cachedUserLoader = new BatchLoader(
async (ids) => {
const uncachedIds = ids.filter(id => !userCache[id]);
const users = await getUsersByIds(uncachedIds);
uncachedIds.forEach((id, i) => { userCache[id] = users[i]; });
return ids.map(id => userCache[id]);
},
...
);
delete userCache[id1]; // delete cache by key
userCache[id2] = user2; // add cache by key
userCache = {}; // empty cache
```
Choose whatever caching library you like and simply add it like above.