Repository: graphql/dataloader
Branch: main
Commit: 468257a47a8f
Files: 31
Total size: 125.0 KB
Directory structure:
gitextract_vqab7clx/
├── .changeset/
│ ├── README.md
│ └── config.json
├── .eslintignore
├── .eslintrc
├── .flowconfig
├── .github/
│ ├── ISSUE_TEMPLATE/
│ │ ├── bug-report.md
│ │ ├── feature-request.md
│ │ └── question.md
│ └── workflows/
│ └── validation.yml
├── .gitignore
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── babel.config.js
├── examples/
│ ├── CouchDB.md
│ ├── GoogleDatastore.md
│ ├── Knex.md
│ ├── Redis.md
│ ├── RethinkDB.md
│ └── SQL.md
├── flow-typed/
│ └── npm/
│ └── jest_v24.x.x.js
├── package.json
├── renovate.json
├── resources/
│ ├── prepublish.sh
│ └── watch.js
└── src/
└── __tests__/
├── abuse.test.js
├── browser.test.js
├── dataloader.test.js
├── oldbrowser.test.js
└── unhandled.test.js
================================================
FILE CONTENTS
================================================
================================================
FILE: .changeset/README.md
================================================
# Changesets
Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
with multi-package repos, or single-package repos to help you version and publish your code. You can
find the full documentation for it [in our repository](https://github.com/changesets/changesets)
We have a quick list of common questions to get you started engaging with this project in
[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)
================================================
FILE: .changeset/config.json
================================================
{
"$schema": "https://unpkg.com/@changesets/config@2.1.0/schema.json",
"changelog": [
"@changesets/changelog-github",
{ "repo": "graphql/dataloader" }
],
"commit": false,
"fixed": [],
"linked": [],
"access": "public",
"baseBranch": "main",
"updateInternalDependencies": "patch",
"ignore": []
}
================================================
FILE: .eslintignore
================================================
dist/
flow-typed/
================================================
FILE: .eslintrc
================================================
{
"globals": {
"$ReadOnlyArray": true
},
"parser": "babel-eslint",
"plugins": ["prettier"],
"env": {
"es6": true,
"node": true,
"jest": true
},
"rules": {
"block-scoped-var": 0,
"callback-return": 2,
"camelcase": [2, {"properties": "always"}],
"comma-dangle": 0,
"comma-spacing": 0,
"complexity": 0,
"computed-property-spacing": [2, "never"],
"consistent-return": 0,
"consistent-this": 0,
"default-case": 0,
"dot-location": [2, "property"],
"dot-notation": 0,
"eol-last": 2,
"eqeqeq": 2,
"func-names": 0,
"func-style": 0,
"generator-star-spacing": [0, {"before": true, "after": false}],
"guard-for-in": 2,
"handle-callback-err": [2, "error"],
"id-length": 0,
"id-match": [2, "^(?:_?[a-zA-Z0-9]*)|[_A-Z0-9]+$"],
"init-declarations": 0,
"key-spacing": [2, {"beforeColon": false, "afterColon": true}],
"keyword-spacing": 2,
"linebreak-style": 2,
"lines-around-comment": 0,
"max-depth": 0,
"max-nested-callbacks": 0,
"max-params": 0,
"max-statements": 0,
"new-cap": 0,
"new-parens": 2,
"newline-after-var": 0,
"no-alert": 2,
"no-array-constructor": 2,
"no-bitwise": 0,
"no-caller": 2,
"no-catch-shadow": 0,
"no-class-assign": 2,
"no-cond-assign": 2,
"no-console": 1,
"no-const-assign": 2,
"no-constant-condition": 2,
"no-continue": 0,
"no-control-regex": 0,
"no-debugger": 1,
"no-delete-var": 2,
"no-div-regex": 2,
"no-dupe-args": 2,
"no-dupe-keys": 2,
"no-duplicate-case": 2,
"no-else-return": 2,
"no-empty": 2,
"no-empty-character-class": 2,
"no-eq-null": 0,
"no-eval": 2,
"no-ex-assign": 2,
"no-extend-native": 2,
"no-extra-bind": 2,
"no-extra-boolean-cast": 2,
"no-extra-parens": 0,
"no-extra-semi": 2,
"no-fallthrough": 2,
"no-floating-decimal": 2,
"no-func-assign": 2,
"no-implicit-coercion": 2,
"no-implied-eval": 2,
"no-inline-comments": 0,
"no-inner-declarations": [2, "functions"],
"no-invalid-regexp": 2,
"no-invalid-this": 0,
"no-irregular-whitespace": 2,
"no-iterator": 2,
"no-label-var": 2,
"no-labels": 0,
"no-lone-blocks": 2,
"no-lonely-if": 2,
"no-loop-func": 0,
"no-mixed-requires": [2, true],
"no-mixed-spaces-and-tabs": 2,
"no-multi-spaces": 2,
"no-multi-str": 2,
"no-multiple-empty-lines": 0,
"no-native-reassign": 0,
"no-negated-in-lhs": 2,
"no-nested-ternary": 0,
"no-new": 2,
"no-new-func": 0,
"no-new-object": 2,
"no-new-require": 2,
"no-new-wrappers": 2,
"no-obj-calls": 2,
"no-octal": 2,
"no-octal-escape": 2,
"no-param-reassign": 2,
"no-path-concat": 2,
"no-plusplus": 0,
"no-process-env": 0,
"no-process-exit": 0,
"no-proto": 2,
"no-redeclare": 2,
"no-regex-spaces": 2,
"no-restricted-modules": 0,
"no-return-assign": 2,
"no-script-url": 2,
"no-self-compare": 0,
"no-sequences": 2,
"no-shadow": 2,
"no-shadow-restricted-names": 2,
"no-spaced-func": 2,
"no-sparse-arrays": 2,
"no-sync": 2,
"no-ternary": 0,
"no-this-before-super": 2,
"no-throw-literal": 2,
"no-trailing-spaces": 2,
"no-undef": 2,
"no-undef-init": 2,
"no-undefined": 0,
"no-underscore-dangle": 0,
"no-unexpected-multiline": 2,
"no-unneeded-ternary": 2,
"no-unreachable": 2,
"no-unused-expressions": 2,
"no-unused-vars": [2, {"vars": "all", "args": "after-used"}],
"no-use-before-define": 0,
"no-useless-call": 2,
"no-var": 0,
"no-void": 2,
"no-warning-comments": 0,
"no-with": 2,
"object-curly-spacing": [0, "always"],
"object-shorthand": [2, "always"],
"one-var": [2, "never"],
"operator-assignment": [2, "always"],
"prefer-const": 0,
"prefer-reflect": 0,
"prefer-spread": 0,
"quote-props": [2, "as-needed"],
"radix": 2,
"require-yield": 2,
"semi-spacing": [2, {"before": false, "after": true}],
"sort-vars": 0,
"space-before-blocks": [2, "always"],
"space-before-function-paren": [2, {"anonymous": "always", "named": "never"}],
"space-in-parens": 0,
"space-infix-ops": [2, {"int32Hint": false}],
"space-unary-ops": [2, {"words": true, "nonwords": false}],
"spaced-comment": [2, "always"],
"strict": 0,
"use-isnan": 2,
"valid-jsdoc": 0,
"valid-typeof": 2,
"vars-on-top": 0,
"wrap-iife": 2,
"wrap-regex": 0,
"yoda": [2, "never", {"exceptRange": true}],
"prettier/prettier": 2
}
}
================================================
FILE: .flowconfig
================================================
[ignore]
.*/lib/.*
.*/dist/.*
.*/coverage/.*
.*/resources/.*
.*/node_modules/y18n/test/.*
[include]
[libs]
[options]
suppress_comment=\\(.\\|\n\\)*\\$FlowExpectError
include_warnings=true
================================================
FILE: .github/ISSUE_TEMPLATE/bug-report.md
================================================
---
name: Bug report
about: Create a report to help us improve
title: "[BUG]"
labels: bug
---
<!-- Before filing a bug, please consider submitting a pull request with a failing test -->
## Expected Behavior
<!-- Describe what should happen -->
## Current Behavior
<!-- Describe what happens instead of the expected behavior -->
## Possible Solution
<!-- Not obligatory, but ideally suggest a fix or hypothesis for the bug -->
## Steps to Reproduce
<!-- Provide a link to a live example, or an unambiguous set of steps to reproduce this bug -->
<!-- Please consider submitting this as a pull request which adds a failing test case -->
## Context
<!-- Any additional information about your environment or what are you trying to accomplish that might be relevant? -->
================================================
FILE: .github/ISSUE_TEMPLATE/feature-request.md
================================================
---
name: Feature request
about: Suggest an idea for this project
title: "[REQUEST]"
labels: enhancement
---
## What problem are you trying to solve?
<!-- A concise description of what the problem is that this project should help solve -->
## Describe the solution you'd like
<!-- What should the API and behavior look like to address that problem? -->
## Describe alternatives you've considered
<!-- Are there any alternative solutions or features you've considered that are inadequate for solving this problem? -->
## Additional context
<!-- Any other context, examples, or adoptions paths to share? -->
================================================
FILE: .github/ISSUE_TEMPLATE/question.md
================================================
---
name: Question
about: Not a bug or feature request?
title: "[QUESTION]"
labels: help wanted
---
<!--
Please consider StackOverflow or other community discussion venues for general questions
since this issue tracker is intended for bugs and feature requests to DataLoader. Questions
asked here are unlikely to get an answer in a timely fashion and might be closed without answer.
https://graphql.org/community/
https://stackoverflow.com/questions/tagged/graphql+dataloader
-->
================================================
FILE: .github/workflows/validation.yml
================================================
name: Flow check, Lint and Tests
on: push
jobs:
validation:
name: Testing on Node ${{ matrix.node-version }}
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [18, 20, 22]
steps:
- name: Checkout Repository
uses: actions/checkout@v4
- name: Use Node ${{ matrix.node-version }}
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: 'yarn'
- name: Install Dependencies using Yarn
run: yarn --ignore-engines
- name: Tests
run: yarn test:ci
- name: Upload coverage to Codecov
uses: codecov/codecov-action@v4
env:
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
with:
fail_ci_if_error: true
================================================
FILE: .gitignore
================================================
*.swp
*~
*.iml
.*.haste_cache.*
.DS_Store
.idea
npm-debug.log
node_modules
coverage
dist
# Generated with release scripts
index.d.ts
index.js
index.js.flow
================================================
FILE: CHANGELOG.md
================================================
# dataloader
## 2.2.3
### Patch Changes
- [#342](https://github.com/graphql/dataloader/pull/342) [`38fedd4`](https://github.com/graphql/dataloader/commit/38fedd4106e9e3e7eb77bd68e42abc088110bd43) Thanks [@abendi](https://github.com/abendi)! - Ensure `cacheKeyFn` is not called when caching is disabled, since the key is not utilized in that case.
## 2.2.2
### Patch Changes
- [#334](https://github.com/graphql/dataloader/pull/334) [`e286f66`](https://github.com/graphql/dataloader/commit/e286f662657675fa790f33abcd6aa87b5aac2be3) Thanks [@henrinormak](https://github.com/henrinormak)! - Added missing type definition for Dataloader.name
## 2.2.1
### Patch Changes
- [#331](https://github.com/graphql/dataloader/pull/331) [`6d2efb7`](https://github.com/graphql/dataloader/commit/6d2efb7dd0363062de255e723c29a781d0ea9937) Thanks [@saihaj](https://github.com/saihaj)! - `name` is an optional property
## 2.2.0
### Minor Changes
- [#326](https://github.com/graphql/dataloader/pull/326) [`6c758d0`](https://github.com/graphql/dataloader/commit/6c758d03bef628a69b238f053da3b263cd5e3321) Thanks [@SimenB](https://github.com/SimenB)! - Add `name` property to `DataLoader`. Useful in APM tools.
### Patch Changes
- [#318](https://github.com/graphql/dataloader/pull/318) [`588a8b6`](https://github.com/graphql/dataloader/commit/588a8b6c6391aad042b369f10dc440c7e0458312) Thanks [@boopathi](https://github.com/boopathi)! - Fix the propagation of sync throws in the batch function to the loader function instead of crashing the process wtih an uncaught exception.
* [#252](https://github.com/graphql/dataloader/pull/252) [`fae38f1`](https://github.com/graphql/dataloader/commit/fae38f14702e925d1e59051d7e5cb3a9a78bfde8) Thanks [@LinusU](https://github.com/LinusU)! - Fix types for priming cache with promise
- [#321](https://github.com/graphql/dataloader/pull/321) [`3cd3a43`](https://github.com/graphql/dataloader/commit/3cd3a430bdb4f9ef2f7f265a29e93e0255277885) Thanks [@thekevinbrown](https://github.com/thekevinbrown)! - Resolves an issue where the maxBatchSize parameter wouldn't be fully used on each batch sent to the backend loader.
## 2.1.0
### Minor Changes
- 28cf959: - Do not return void results from arrow functions https://github.com/graphql/dataloader/commit/3b0bae94e91453d9a432c02628745252abc5e011
- Fix typo in `loader.load()` error message https://github.com/graphql/dataloader/commit/249b2b966a8807c50e07746ff04acb8c48fa4357
- Fix typo in SQL example https://github.com/graphql/dataloader/commit/cae1a3d9bfa48e181a49fd443f43813b335dc120
- Fix typo in TypeScript declaration https://github.com/graphql/dataloader/commit/ef6d32f97cde16aba84d96dc806c4439eaf8efae
- Most of the browsers don't have `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
### Patch Changes
- 3135e9a: Fix typo in jsdoc comment; flip "objects are keys" to "keys are objects"
================================================
FILE: CONTRIBUTING.md
================================================
# Contributing to DataLoader
We want to make contributing to this project as easy and transparent as
possible.
## Code of Conduct
This project's code of conduct is described in the GraphQL Foundation's [`CODE_OF_CONDUCT.md`](https://github.com/graphql/foundation/blob/master/CODE-OF-CONDUCT.md)
## Pull Requests
We actively welcome your pull requests for documentation and code.
1. Fork the repo and create your branch from `master`.
2. If you've added code that should be tested, add tests with 100% coverage.
3. If you've changed APIs, update the documentation.
4. Ensure the test suite passes.
5. Make sure your code lints.
6. If you haven't already, complete the Contributor License Agreement ("CLA").
7. Run `yarn changeset` and describe the change you're proposing. Commit the file it creates in `.changeset` to the repo. [You can read more about changeset here.](https://github.com/changesets/changesets)
8. Open a Pull Request so we can review and incorporate your change.
## Releases
To release a new version:
1. Run `yarn changeset version` to bump the version of the package.
2. Run `yarn release` this will create a new release on GitHub and publish the package to NPM.
## Issues
We use GitHub issues to track public bugs. Please ensure your description is
clear and has sufficient instructions to be able to reproduce the issue.
## Coding Style
- 2 spaces for indentation rather than tabs
- 80 character line length
- See .eslintrc for the gory details.
## License
By contributing to DataLoader, you agree that your contributions will be
licensed under its MIT license.
================================================
FILE: LICENSE
================================================
MIT License
Copyright (c) GraphQL Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
================================================
FILE: README.md
================================================
# DataLoader
DataLoader is a generic utility to be used as part of your application's data
fetching layer to provide a simplified and consistent API over various remote
data sources such as databases or web services via batching and caching.
[](https://github.com/graphql/dataloader/actions/workflows/validation.yml)
[](https://coveralls.io/github/graphql/dataloader?branch=main)
A port of the "Loader" API originally developed by [@schrockn][] at Facebook in
2010 as a simplifying force to coalesce the sundry key-value store back-end
APIs which existed at the time. At Facebook, "Loader" became one of the
implementation details of the "Ent" framework, a privacy-aware data entity
loading and caching layer within web server product code. This ultimately became
the underpinning for Facebook's GraphQL server implementation and type
definitions.
DataLoader is a simplified version of this original idea implemented in
JavaScript for Node.js services. DataLoader is often used when implementing a
[graphql-js][] service, though it is also broadly useful in other situations.
This mechanism of batching and caching data requests is certainly not unique to
Node.js or JavaScript, it is also the primary motivation for
[Haxl](https://github.com/facebook/Haxl), Facebook's data loading library
for Haskell. More about how Haxl works can be read in this [blog post](https://code.facebook.com/posts/302060973291128/open-sourcing-haxl-a-library-for-haskell/).
DataLoader is provided so that it may be useful not just to build GraphQL
services for Node.js but also as a publicly available reference implementation
of this concept in the hopes that it can be ported to other languages. If you
port DataLoader to another language, please open an issue to include a link from
this repository.
## Getting Started
First, install DataLoader using npm.
```sh
npm install --save dataloader
```
To get started, create a `DataLoader`. Each `DataLoader` instance represents a
unique cache. Typically instances are created per request when used within a
web-server like [express][] if different users can see different things.
> Note: DataLoader assumes a JavaScript environment with global ES6 `Promise`
> and `Map` classes, available in all supported versions of Node.js.
## Batching
Batching is not an advanced feature, it's DataLoader's primary feature.
Create loaders by providing a batch loading function.
```js
const DataLoader = require('dataloader');
const userLoader = new DataLoader(keys => myBatchGetUsers(keys));
```
A batch loading function accepts an Array of keys, and returns a Promise which
resolves to an Array of values[<sup>\*</sup>](#batch-function).
Then load individual values from the loader. DataLoader will coalesce all
individual loads which occur within a single frame of execution (a single tick
of the event loop) and then call your batch function with all requested keys.
```js
const user = await userLoader.load(1);
const invitedBy = await userLoader.load(user.invitedByID);
console.log(`User 1 was invited by ${invitedBy}`);
// Elsewhere in your application
const user = await userLoader.load(2);
const lastInvited = await userLoader.load(user.lastInvitedID);
console.log(`User 2 last invited ${lastInvited}`);
```
A naive application may have issued four round-trips to a backend for the
required information, but with DataLoader this application will make at most
two.
DataLoader allows you to decouple unrelated parts of your application without
sacrificing the performance of batch data-loading. While the loader presents an
API that loads individual values, all concurrent requests will be coalesced and
presented to your batch loading function. This allows your application to safely
distribute data fetching requirements throughout your application and maintain
minimal outgoing data requests.
#### Batch Function
A batch loading function accepts an Array of keys, and returns a Promise which
resolves to an Array of values or Error instances. The loader itself is provided
as the `this` context.
```js
async function batchFunction(keys) {
const results = await db.fetchAllKeys(keys);
return keys.map(key => results[key] || new Error(`No result for ${key}`));
}
const loader = new DataLoader(batchFunction);
```
There are a few constraints this function must uphold:
- The Array of values must be the same length as the Array of keys.
- Each index in the Array of values must correspond to the same index in the Array of keys.
For example, if your batch function was provided the Array of keys: `[ 2, 9, 6, 1 ]`,
and loading from a back-end service returned the values:
```js
{ id: 9, name: 'Chicago' }
{ id: 1, name: 'New York' }
{ id: 2, name: 'San Francisco' }
```
Our back-end service returned results in a different order than we requested, likely
because it was more efficient for it to do so. Also, it omitted a result for key `6`,
which we can interpret as no value existing for that key.
To uphold the constraints of the batch function, it must return an Array of values
the same length as the Array of keys, and re-order them to ensure each index aligns
with the original keys `[ 2, 9, 6, 1 ]`:
```js
[
{ id: 2, name: 'San Francisco' },
{ id: 9, name: 'Chicago' },
null, // or perhaps `new Error()`
{ id: 1, name: 'New York' },
];
```
#### Batch Scheduling
By default DataLoader will coalesce all individual loads which occur within a
single frame of execution before calling your batch function with all requested
keys. This ensures no additional latency while capturing many related requests
into a single batch. In fact, this is the same behavior used in Facebook's
original PHP implementation in 2010. See `enqueuePostPromiseJob` in the
[source code][] for more details about how this works.
However sometimes this behavior is not desirable or optimal. Perhaps you expect
requests to be spread out over a few subsequent ticks because of an existing use
of `setTimeout`, or you just want manual control over dispatching regardless of
the run loop. DataLoader allows providing a custom batch scheduler to provide
these or any other behaviors.
A custom scheduler is provided as `batchScheduleFn` in options. It must be a
function which is passed a callback and is expected to call that callback in the
immediate future to execute the batch request.
As an example, here is a batch scheduler which collects all requests over a
100ms window of time (and as a consequence, adds 100ms of latency):
```js
const myLoader = new DataLoader(myBatchFn, {
batchScheduleFn: callback => setTimeout(callback, 100),
});
```
As another example, here is a manually dispatched batch scheduler:
```js
function createScheduler() {
let callbacks = [];
return {
schedule(callback) {
callbacks.push(callback);
},
dispatch() {
callbacks.forEach(callback => callback());
callbacks = [];
},
};
}
const { schedule, dispatch } = createScheduler();
const myLoader = new DataLoader(myBatchFn, { batchScheduleFn: schedule });
myLoader.load(1);
myLoader.load(2);
dispatch();
```
## Caching
DataLoader provides a memoization cache for all loads which occur in a single
request to your application. After `.load()` is called once with a given key,
the resulting value is cached to eliminate redundant loads.
#### Caching Per-Request
DataLoader caching _does not_ replace Redis, Memcache, or any other shared
application-level cache. DataLoader is first and foremost a data loading mechanism,
and its cache only serves the purpose of not repeatedly loading the same data in
the context of a single request to your Application. To do this, it maintains a
simple in-memory memoization cache (more accurately: `.load()` is a memoized function).
Avoid multiple requests from different users using the DataLoader instance, which
could result in cached data incorrectly appearing in each request. Typically,
DataLoader instances are created when a Request begins, and are not used once the
Request ends.
For example, when using with [express][]:
```js
function createLoaders(authToken) {
return {
users: new DataLoader(ids => genUsers(authToken, ids)),
};
}
const app = express();
app.get('/', function (req, res) {
const authToken = authenticateUser(req);
const loaders = createLoaders(authToken);
res.send(renderPage(req, loaders));
});
app.listen();
```
#### Caching and Batching
Subsequent calls to `.load()` with the same key will result in that key not
appearing in the keys provided to your batch function. _However_, the resulting
Promise will still wait on the current batch to complete. This way both cached
and uncached requests will resolve at the same time, allowing DataLoader
optimizations for subsequent dependent loads.
In the example below, User `1` happens to be cached. However, because User `1`
and `2` are loaded in the same tick, they will resolve at the same time. This
means both `user.bestFriendID` loads will also happen in the same tick which
results in two total requests (the same as if User `1` had not been cached).
```js
userLoader.prime(1, { bestFriend: 3 });
async function getBestFriend(userID) {
const user = await userLoader.load(userID);
return await userLoader.load(user.bestFriendID);
}
// In one part of your application
getBestFriend(1);
// Elsewhere
getBestFriend(2);
```
Without this optimization, if the cached User `1` resolved immediately, this
could result in three total requests since each `user.bestFriendID` load would
happen at different times.
#### Clearing Cache
In certain uncommon cases, clearing the request cache may be necessary.
The most common example when clearing the loader's cache is necessary is after
a mutation or update within the same request, when a cached value could be out of
date and future loads should not use any possibly cached value.
Here's a simple example using SQL UPDATE to illustrate.
```js
// Request begins...
const userLoader = new DataLoader(...);
// And a value happens to be loaded (and cached).
const user = await userLoader.load(4);
// A mutation occurs, invalidating what might be in cache.
await sqlRun('UPDATE users WHERE id=4 SET username="zuck"');
userLoader.clear(4);
// Later the value load is loaded again so the mutated data appears.
const user = await userLoader.load(4);
// Request completes.
```
#### Caching Errors
If a batch load fails (that is, a batch function throws or returns a rejected
Promise), then the requested values will not be cached. However if a batch
function returns an `Error` instance for an individual value, that `Error` will
be cached to avoid frequently loading the same `Error`.
In some circumstances you may wish to clear the cache for these individual Errors:
```js
try {
const user = await userLoader.load(1);
} catch (error) {
if (/* determine if the error should not be cached */) {
userLoader.clear(1);
}
throw error
}
```
#### Disabling Cache
In certain uncommon cases, a DataLoader which _does not_ cache may be desirable.
Calling `new DataLoader(myBatchFn, { cache: false })` will ensure that every
call to `.load()` will produce a _new_ Promise, and requested keys will not be
saved in memory.
However, when the memoization cache is disabled, your batch function will
receive an array of keys which may contain duplicates! Each key will be
associated with each call to `.load()`. Your batch loader should provide a value
for each instance of the requested key.
For example:
```js
const myLoader = new DataLoader(
keys => {
console.log(keys);
return someBatchLoadFn(keys);
},
{ cache: false },
);
myLoader.load('A');
myLoader.load('B');
myLoader.load('A');
// > [ 'A', 'B', 'A' ]
```
More complex cache behavior can be achieved by calling `.clear()` or `.clearAll()`
rather than disabling the cache completely. For example, this DataLoader will
provide unique keys to a batch function due to the memoization cache being
enabled, but will immediately clear its cache when the batch function is called
so later requests will load new values.
```js
const myLoader = new DataLoader(keys => {
myLoader.clearAll();
return someBatchLoadFn(keys);
});
```
#### Custom Cache
As mentioned above, DataLoader is intended to be used as a per-request cache.
Since requests are short-lived, DataLoader uses an infinitely growing [Map][] as
a memoization cache. This should not pose a problem as most requests are
short-lived and the entire cache can be discarded after the request completes.
However this memoization caching strategy isn't safe when using a long-lived
DataLoader, since it could consume too much memory. If using DataLoader in this
way, you can provide a custom Cache instance with whatever behavior you prefer,
as long as it follows the same API as [Map][].
The example below uses an LRU (least recently used) cache to limit total memory
to hold at most 100 cached values via the [lru_map][] npm package.
```js
import { LRUMap } from 'lru_map';
const myLoader = new DataLoader(someBatchLoadFn, {
cacheMap: new LRUMap(100),
});
```
More specifically, any object that implements the methods `get()`, `set()`,
`delete()` and `clear()` methods can be provided. This allows for custom Maps
which implement various [cache algorithms][] to be provided.
## API
#### class DataLoader
DataLoader creates a public API for loading data from a particular
data back-end with unique keys such as the `id` column of a SQL table or
document name in a MongoDB database, given a batch loading function.
Each `DataLoader` instance contains a unique memoized cache. Use caution when
used in long-lived applications or those which serve many users with different
access permissions and consider creating a new instance per web request.
##### `new DataLoader(batchLoadFn [, options])`
Create a new `DataLoader` given a batch loading function and options.
- _batchLoadFn_: A function which accepts an Array of keys, and returns a
Promise which resolves to an Array of values.
- _options_: An optional object of options:
| Option Key | Type | Default | Description |
| ----------------- | -------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `batch` | Boolean | `true` | Set to `false` to disable batching, invoking `batchLoadFn` with a single load key. This is equivalent to setting `maxBatchSize` to `1`. |
| `maxBatchSize` | Number | `Infinity` | Limits the number of items that get passed in to the `batchLoadFn`. May be set to `1` to disable batching. |
| `batchScheduleFn` | Function | See [Batch scheduling](#batch-scheduling) | A function to schedule the later execution of a batch. The function is expected to call the provided callback in the immediate future. |
| `cache` | Boolean | `true` | Set to `false` to disable memoization caching, creating a new Promise and new key in the `batchLoadFn` for every load of the same key. This is equivalent to setting `cacheMap` to `null`. |
| `cacheKeyFn` | Function | `key => key` | Produces cache key for a given load key. Useful when objects are keys and two objects should be considered equivalent. |
| `cacheMap` | Object | `new Map()` | Instance of [Map][] (or an object with a similar API) to be used as cache. May be set to `null` to disable caching. |
| `name` | String | `null` | The name given to this `DataLoader` instance. Useful for APM tools. |
##### `load(key)`
Loads a key, returning a `Promise` for the value represented by that key.
- _key_: A key value to load.
##### `loadMany(keys)`
Loads multiple keys, promising an array of values:
```js
const [a, b] = await myLoader.loadMany(['a', 'b']);
```
This is similar to the more verbose:
```js
const [a, b] = await Promise.all([myLoader.load('a'), myLoader.load('b')]);
```
However it is different in the case where any load fails. Where
Promise.all() would reject, loadMany() always resolves, however each result
is either a value or an Error instance.
```js
var [a, b, c] = await myLoader.loadMany(['a', 'b', 'badkey']);
// c instanceof Error
```
- _keys_: An array of key values to load.
##### `clear(key)`
Clears the value at `key` from the cache, if it exists. Returns itself for
method chaining.
- _key_: A key value to clear.
##### `clearAll()`
Clears the entire cache. To be used when some event results in unknown
invalidations across this particular `DataLoader`. Returns itself for
method chaining.
##### `prime(key, value)`
Primes the cache with the provided key and value. If the key already exists, no
change is made. (To forcefully prime the cache, clear the key first with
`loader.clear(key).prime(key, value)`.) Returns itself for method chaining.
To prime the cache with an error at a key, provide an Error instance.
## Using with GraphQL
DataLoader pairs nicely well with [GraphQL][graphql-js]. GraphQL fields are
designed to be stand-alone functions. Without a caching or batching mechanism,
it's easy for a naive GraphQL server to issue new database requests each time a
field is resolved.
Consider the following GraphQL request:
```
{
me {
name
bestFriend {
name
}
friends(first: 5) {
name
bestFriend {
name
}
}
}
}
```
Naively, if `me`, `bestFriend` and `friends` each need to request the backend,
there could be at most 13 database requests!
When using DataLoader, we could define the `User` type using the
[SQLite](examples/SQL.md) example with clearer code and at most 4 database requests,
and possibly fewer if there are cache hits.
```js
const UserType = new GraphQLObjectType({
name: 'User',
fields: () => ({
name: { type: GraphQLString },
bestFriend: {
type: UserType,
resolve: user => userLoader.load(user.bestFriendID),
},
friends: {
args: {
first: { type: GraphQLInt },
},
type: new GraphQLList(UserType),
resolve: async (user, { first }) => {
const rows = await queryLoader.load([
'SELECT toID FROM friends WHERE fromID=? LIMIT ?',
user.id,
first,
]);
return rows.map(row => userLoader.load(row.toID));
},
},
}),
});
```
## Common Patterns
### Creating a new DataLoader per request.
In many applications, a web server using DataLoader serves requests to many
different users with different access permissions. It may be dangerous to use
one cache across many users, and is encouraged to create a new DataLoader
per request:
```js
function createLoaders(authToken) {
return {
users: new DataLoader(ids => genUsers(authToken, ids)),
cdnUrls: new DataLoader(rawUrls => genCdnUrls(authToken, rawUrls)),
stories: new DataLoader(keys => genStories(authToken, keys)),
};
}
// When handling an incoming web request:
const loaders = createLoaders(request.query.authToken);
// Then, within application logic:
const user = await loaders.users.load(4);
const pic = await loaders.cdnUrls.load(user.rawPicUrl);
```
Creating an object where each key is a `DataLoader` is one common pattern which
provides a single value to pass around to code which needs to perform
data loading, such as part of the `rootValue` in a [graphql-js][] request.
### Loading by alternative keys.
Occasionally, some kind of value can be accessed in multiple ways. For example,
perhaps a "User" type can be loaded not only by an "id" but also by a "username"
value. If the same user is loaded by both keys, then it may be useful to fill
both caches when a user is loaded from either source:
```js
const userByIDLoader = new DataLoader(async ids => {
const users = await genUsersByID(ids);
for (let user of users) {
usernameLoader.prime(user.username, user);
}
return users;
});
const usernameLoader = new DataLoader(async names => {
const users = await genUsernames(names);
for (let user of users) {
userByIDLoader.prime(user.id, user);
}
return users;
});
```
### Freezing results to enforce immutability
Since DataLoader caches values, it's typically assumed these values will be
treated as if they were immutable. While DataLoader itself doesn't enforce
this, you can create a higher-order function to enforce immutability
with Object.freeze():
```js
function freezeResults(batchLoader) {
return keys => batchLoader(keys).then(values => values.map(Object.freeze));
}
const myLoader = new DataLoader(freezeResults(myBatchLoader));
```
### Batch functions which return Objects instead of Arrays
DataLoader expects batch functions which return an Array of the same length as
the provided keys. However this is not always a common return format from other
libraries. A DataLoader higher-order function can convert from one format to another. The example below converts a `{ key: value }` result to the format
DataLoader expects.
```js
function objResults(batchLoader) {
return keys =>
batchLoader(keys).then(objValues =>
keys.map(key => objValues[key] || new Error(`No value for ${key}`)),
);
}
const myLoader = new DataLoader(objResults(myBatchLoader));
```
## Common Back-ends
Looking to get started with a specific back-end? Try the [loaders in the examples directory](/examples).
## Other Implementations
Listed in alphabetical order
- Elixir
- [dataloader](https://github.com/absinthe-graphql/dataloader)
- Golang
- [Dataloader](https://github.com/nicksrandall/dataloader)
- Java
- [java-dataloader](https://github.com/graphql-java/java-dataloader)
- .Net
- [GraphQL .NET DataLoader](https://graphql-dotnet.github.io/docs/guides/dataloader/)
- [Green Donut](https://github.com/ChilliCream/graphql-platform?tab=readme-ov-file#green-donut)
- Perl
- [perl-DataLoader](https://github.com/richardjharris/perl-DataLoader)
- PHP
- [DataLoaderPHP](https://github.com/overblog/dataloader-php)
- Python
- [aiodataloader](https://github.com/syrusakbary/aiodataloader)
- ReasonML
- [bs-dataloader](https://github.com/ulrikstrid/bs-dataloader)
- Ruby
- [BatchLoader](https://github.com/exaspark/batch-loader)
- [Dataloader](https://github.com/sheerun/dataloader)
- [GraphQL Batch](https://github.com/Shopify/graphql-batch)
- Rust
- [Dataloader](https://github.com/cksac/dataloader-rs)
- Swift
- [SwiftDataLoader](https://github.com/kimdv/SwiftDataLoader)
- C++
- [cppdataloader](https://github.com/jafarlihi/cppdataloader)
## Video Source Code Walkthrough
**DataLoader Source Code Walkthrough (YouTube):**
A walkthrough of the DataLoader v1 source code. While the source has changed
since this video was made, it is still a good overview of the rationale of
DataLoader and how it works.
<a href="https://youtu.be/OQTnXNCDywA" target="_blank" alt="DataLoader Source Code Walkthrough"><img src="https://img.youtube.com/vi/OQTnXNCDywA/0.jpg" /></a>
[@schrockn]: https://github.com/schrockn
[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
[graphql-js]: https://github.com/graphql/graphql-js
[cache algorithms]: https://en.wikipedia.org/wiki/Cache_algorithms
[express]: http://expressjs.com/
[babel/polyfill]: https://babeljs.io/docs/usage/polyfill/
[lru_map]: https://github.com/rsms/js-lru
[source code]: https://github.com/graphql/dataloader/blob/main/src/index.js
# Contributing to this repo
This repository is managed by EasyCLA. Project participants must sign the free ([GraphQL Specification Membership agreement](https://preview-spec-membership.graphql.org) before making a contribution. You only need to do this one time, and it can be signed by [individual contributors](http://individual-spec-membership.graphql.org/) or their [employers](http://corporate-spec-membership.graphql.org/).
To initiate the signature process please open a PR against this repo. The EasyCLA bot will block the merge if we still need a membership agreement from you.
You can find [detailed information here](https://github.com/graphql/graphql-wg/tree/main/membership). If you have issues, please email [operations@graphql.org](mailto:operations@graphql.org).
If your company benefits from GraphQL and you would like to provide essential financial support for the systems and people that power our community, please also consider membership in the [GraphQL Foundation](https://foundation.graphql.org/join).
================================================
FILE: babel.config.js
================================================
module.exports = api => ({
presets: api.env('test')
? ['@babel/preset-flow']
: [['@babel/preset-env', { loose: true }], '@babel/preset-flow'],
});
================================================
FILE: examples/CouchDB.md
================================================
# Using DataLoader with CouchDB
CouchDB is a "NoSQL" document database which supports batch loading via the
[HTTP Bulk Document API](http://wiki.apache.org/couchdb/HTTP_Bulk_Document_API),
making it well suited for use with DataLoader.
This example uses the [nano][] CouchDB client which offers a `fetch` method
supporting the bulk document API.
```js
const DataLoader = require('dataloader');
const nano = require('nano');
const couch = nano('http://localhost:5984');
const userDB = couch.use('users');
const userLoader = new DataLoader(
keys =>
new Promise((resolve, reject) => {
userDB.fetch({ keys: keys }, (error, docs) => {
if (error) {
return reject(error);
}
resolve(
docs.rows.map(row => (row.error ? new Error(row.error) : row.doc)),
);
});
}),
);
// Usage
const promise1 = userLoader.load('8fce1902834ac6458e9886fa7f89c0ef');
const promise2 = userLoader.load('00a271787f89c0ef2e10e88a0c00048b');
const [user1, user2] = await Promise.all([promise1, promise2]);
console.log(user1, user2);
```
[nano]: https://github.com/dscape/nano
================================================
FILE: examples/GoogleDatastore.md
================================================
# Using DataLoader with Google Datastore
Google Datastore is a "NoSQL" document database which supports [batch operations](https://cloud.google.com/datastore/docs/concepts/entities#batch_operations),
making it well suited for use with DataLoader.
Here we build an example Google Datastore DataLoader using [@google-cloud/datastore](https://cloud.google.com/nodejs/docs/reference/datastore/1.3.x/Datastore).
```js
const Datastore = require('@google-cloud/datastore');
const datastore = new Datastore();
const datastoreLoader = new DataLoader(
async keys => {
const results = await datastore.get(keys);
// Sort resulting entities by the keys they were requested with.
const entities = results[0];
const entitiesByKey = {};
entities.forEach(entity => {
entitiesByKey[JSON.stringify(entity[datastore.KEY])] = entity;
});
return keys.map(key => entitiesByKey[JSON.stringify(key)] || null);
},
{
// Datastore complex keys need to be converted to a string for use as cache keys
cacheKeyFn: key => JSON.stringify(key),
},
);
```
================================================
FILE: examples/Knex.md
================================================
# Using DataLoader with Knex.js
This example demonstrates how to use **DataLoader** with SQL databases via
[Knex.js][knex], which is a SQL query builder and a client for popular
databases such as **PostgreSQL**, **MySQL**, **MariaDB** etc.
Similarly to the [SQL](./SQL.md) example, you can use "where in" clause to
fetch multiple records by the list of IDs with the only difference that you
don't have to write any SQL code by hand.
```js
const DataLoader = require('dataloader');
const db = require('./db'); // an instance of Knex client
// The list of data loaders
const loaders = {
user: new DataLoader(ids =>
db
.table('users')
.whereIn('id', ids)
.select()
.then(rows => ids.map(id => rows.find(x => x.id === id))),
),
story: new DataLoader(ids =>
db
.table('stories')
.whereIn('id', ids)
.select()
.then(rows => ids.map(id => rows.find(x => x.id === id))),
),
storiesByUserId: new DataLoader(ids =>
db
.table('stories')
.whereIn('author_id', ids)
.select()
.then(rows => ids.map(id => rows.filter(x => x.author_id === id))),
),
};
// Usage
const [user, stories] = await Promise.all([
loaders.user.load('1234'),
loaders.storiesByUserId.load('1234'),
]);
```
For a complete example visit [kriasoft/nodejs-api-starter][nsk].
[knex]: http://knexjs.org/
[nsk]: https://github.com/kriasoft/nodejs-api-starter#readme
================================================
FILE: examples/Redis.md
================================================
# Using DataLoader with Redis
Redis is a very simple key-value store which provides the batch load method
[MGET](http://redis.io/commands/mget) which makes it very well suited for use
with DataLoader.
Here we build an example Redis DataLoader using [node_redis][].
```js
const DataLoader = require('dataloader');
const redis = require('redis');
const client = redis.createClient();
const redisLoader = new DataLoader(
keys =>
new Promise((resolve, reject) => {
client.mget(keys, (error, results) => {
if (error) {
return reject(error);
}
resolve(
results.map((result, index) =>
result !== null ? result : new Error(`No key: ${keys[index]}`),
),
);
});
}),
);
```
[node_redis]: https://github.com/NodeRedis/node_redis
================================================
FILE: examples/RethinkDB.md
================================================
# RethinkDb
RethinkDb offers a batching method called `getAll` but there are a few caveats :
- Order of results is not guaranteed ([rethinkdb/rethinkdb#5187](https://github.com/rethinkdb/rethinkdb/issues/5187))
- Non-existent keys will not return an empty record
For example, against a table `example_table` with these records:
```js
[
{ id: 1, name: 'Document 1' },
{ id: 2, name: 'Document 2' },
];
```
A query `r.getAll(1, 2, 3)` could return:
```js
[
{ id: 2, name: 'Document 2' },
{ id: 1, name: 'Document 1' },
];
```
Because query keys and values are associated by position in the dataloader
cache, this naive implementation won't work (with the same table as above):
```js
const r = require('rethinkdb');
const db = await r.connect();
const exampleLoader = new DataLoader(async keys => {
const result = await db.table('example_table').getAll(...keys);
return result.toArray();
});
await exampleLoader.loadMany([1, 2, 3]); // Throws (values length !== keys length)
await exampleLoader.loadMany([1, 2]);
await exampleLoader.load(1); // {"id": 2, "name": "Document 2"}
```
A solution is to normalize results returned by `getAll` to match the structure
of supplied `keys`.
To achieve this efficiently, we first write an indexing function. This function
will return a `Map` indexing results.
Parameters:
- `results`: Array of RethinkDb results
- `indexField`: String indicating which field was used as index for this batch query
- `cacheKeyFn`: Optional function used to serialize non-scalar index field values
```js
function indexResults(results, indexField, cacheKeyFn = key => key) {
const indexedResults = new Map();
results.forEach(res => {
indexedResults.set(cacheKeyFn(res[indexField]), res);
});
return indexedResults;
}
```
Then, we can leverage our Map to normalize RethinkDb results with another
utility function which will produce a normalizing function.
```js
function normalizeRethinkDbResults(keys, indexField, cacheKeyFn = key => key) {
return results => {
const indexedResults = indexResults(results, indexField, cacheKeyFn);
return keys.map(
val =>
indexedResults.get(cacheKeyFn(val)) ||
new Error(`Key not found : ${val}`),
);
};
}
```
Full dataloader implementation:
```js
const r = require('rethinkdb');
const db = await r.connect();
const exampleLoader = new DataLoader(async keys => {
const results = await db.table('example_table').getAll(...keys);
return normalizeRethinkDbResults(res.toArray(), 'id');
});
// [{"id": 1, "name": "Document 1"}, {"id": 2, "name": "Document 2"}, Error];
await exampleLoader.loadMany([1, 2, 3]);
// {"id": 1, "name": "Document 1"}
await exampleLoader.load(1);
```
================================================
FILE: examples/SQL.md
================================================
# Using DataLoader with SQLite
While not a key-value store, SQL offers a natural batch mechanism with
`SELECT * WHERE IN` statements. While `DataLoader` is best suited for key-value
stores, it is still suited for SQL when queries remain simple. This example
requests the entire row at a given `id`, however your usage may differ.
```js
const DataLoader = require('dataloader');
const sqlite3 = require('sqlite3');
const db = new sqlite3.Database('./to/your/db.sql');
// Dispatch a WHERE-IN query, ensuring response has rows in correct order.
const userLoader = new DataLoader(
ids =>
new Promise((resolve, reject) => {
db.all(
'SELECT * FROM users WHERE id IN $ids',
{ $ids: ids },
(error, rows) => {
if (error) {
reject(error);
} else {
resolve(
ids.map(
id =>
rows.find(row => row.id === id) ||
new Error(`Row not found: ${id}`),
),
);
}
},
);
}),
);
// Usage
const promise1 = userLoader.load('1234');
const promise2 = userLoader.load('5678');
const [user1, user2] = await Promise.all([promise1, promise2]);
console.log(user1, user2);
```
[sqlite3]: https://github.com/mapbox/node-sqlite3
================================================
FILE: flow-typed/npm/jest_v24.x.x.js
================================================
// flow-typed signature: 27f8467378a99b6130bd20f54f31a644
// flow-typed version: 6cb9e99836/jest_v24.x.x/flow_>=v0.104.x
type JestMockFn<TArguments: $ReadOnlyArray<*>, TReturn> = {
(...args: TArguments): TReturn,
/**
* An object for introspecting mock calls
*/
mock: {
/**
* An array that represents all calls that have been made into this mock
* function. Each call is represented by an array of arguments that were
* passed during the call.
*/
calls: Array<TArguments>,
/**
* An array that contains all the object instances that have been
* instantiated from this mock function.
*/
instances: Array<TReturn>,
/**
* An array that contains all the object results that have been
* returned by this mock function call
*/
results: Array<{
isThrow: boolean,
value: TReturn,
...
}>,
...
},
/**
* Resets all information stored in the mockFn.mock.calls and
* mockFn.mock.instances arrays. Often this is useful when you want to clean
* up a mock's usage data between two assertions.
*/
mockClear(): void,
/**
* Resets all information stored in the mock. This is useful when you want to
* completely restore a mock back to its initial state.
*/
mockReset(): void,
/**
* Removes the mock and restores the initial implementation. This is useful
* when you want to mock functions in certain test cases and restore the
* original implementation in others. Beware that mockFn.mockRestore only
* works when mock was created with jest.spyOn. Thus you have to take care of
* restoration yourself when manually assigning jest.fn().
*/
mockRestore(): void,
/**
* Accepts a function that should be used as the implementation of the mock.
* The mock itself will still record all calls that go into and instances
* that come from itself -- the only difference is that the implementation
* will also be executed when the mock is called.
*/
mockImplementation(
fn: (...args: TArguments) => TReturn
): JestMockFn<TArguments, TReturn>,
/**
* Accepts a function that will be used as an implementation of the mock for
* one call to the mocked function. Can be chained so that multiple function
* calls produce different results.
*/
mockImplementationOnce(
fn: (...args: TArguments) => TReturn
): JestMockFn<TArguments, TReturn>,
/**
* Accepts a string to use in test result output in place of "jest.fn()" to
* indicate which mock function is being referenced.
*/
mockName(name: string): JestMockFn<TArguments, TReturn>,
/**
* Just a simple sugar function for returning `this`
*/
mockReturnThis(): void,
/**
* Accepts a value that will be returned whenever the mock function is called.
*/
mockReturnValue(value: TReturn): JestMockFn<TArguments, TReturn>,
/**
* Sugar for only returning a value once inside your mock
*/
mockReturnValueOnce(value: TReturn): JestMockFn<TArguments, TReturn>,
/**
* Sugar for jest.fn().mockImplementation(() => Promise.resolve(value))
*/
mockResolvedValue(value: TReturn): JestMockFn<TArguments, Promise<TReturn>>,
/**
* Sugar for jest.fn().mockImplementationOnce(() => Promise.resolve(value))
*/
mockResolvedValueOnce(
value: TReturn
): JestMockFn<TArguments, Promise<TReturn>>,
/**
* Sugar for jest.fn().mockImplementation(() => Promise.reject(value))
*/
mockRejectedValue(value: TReturn): JestMockFn<TArguments, Promise<any>>,
/**
* Sugar for jest.fn().mockImplementationOnce(() => Promise.reject(value))
*/
mockRejectedValueOnce(value: TReturn): JestMockFn<TArguments, Promise<any>>,
...
};
type JestAsymmetricEqualityType = { /**
* A custom Jasmine equality tester
*/
asymmetricMatch(value: mixed): boolean, ... };
type JestCallsType = {
allArgs(): mixed,
all(): mixed,
any(): boolean,
count(): number,
first(): mixed,
mostRecent(): mixed,
reset(): void,
...
};
type JestClockType = {
install(): void,
mockDate(date: Date): void,
tick(milliseconds?: number): void,
uninstall(): void,
...
};
type JestMatcherResult = {
message?: string | (() => string),
pass: boolean,
...
};
type JestMatcher = (
received: any,
...actual: Array<any>
) => JestMatcherResult | Promise<JestMatcherResult>;
type JestPromiseType = {
/**
* Use rejects to unwrap the reason of a rejected promise so any other
* matcher can be chained. If the promise is fulfilled the assertion fails.
*/
rejects: JestExpectType,
/**
* Use resolves to unwrap the value of a fulfilled promise so any other
* matcher can be chained. If the promise is rejected the assertion fails.
*/
resolves: JestExpectType,
...
};
/**
* Jest allows functions and classes to be used as test names in test() and
* describe()
*/
type JestTestName = string | Function;
/**
* Plugin: jest-styled-components
*/
type JestStyledComponentsMatcherValue =
| string
| JestAsymmetricEqualityType
| RegExp
| typeof undefined;
type JestStyledComponentsMatcherOptions = {
media?: string,
modifier?: string,
supports?: string,
...
};
type JestStyledComponentsMatchersType = { toHaveStyleRule(
property: string,
value: JestStyledComponentsMatcherValue,
options?: JestStyledComponentsMatcherOptions
): void, ... };
/**
* Plugin: jest-enzyme
*/
type EnzymeMatchersType = {
// 5.x
toBeEmpty(): void,
toBePresent(): void,
// 6.x
toBeChecked(): void,
toBeDisabled(): void,
toBeEmptyRender(): void,
toContainMatchingElement(selector: string): void,
toContainMatchingElements(n: number, selector: string): void,
toContainExactlyOneMatchingElement(selector: string): void,
toContainReact(element: React$Element<any>): void,
toExist(): void,
toHaveClassName(className: string): void,
toHaveHTML(html: string): void,
toHaveProp: ((propKey: string, propValue?: any) => void) &
((props: {...}) => void),
toHaveRef(refName: string): void,
toHaveState: ((stateKey: string, stateValue?: any) => void) &
((state: {...}) => void),
toHaveStyle: ((styleKey: string, styleValue?: any) => void) &
((style: {...}) => void),
toHaveTagName(tagName: string): void,
toHaveText(text: string): void,
toHaveValue(value: any): void,
toIncludeText(text: string): void,
toMatchElement(
element: React$Element<any>,
options?: {| ignoreProps?: boolean, verbose?: boolean |}
): void,
toMatchSelector(selector: string): void,
// 7.x
toHaveDisplayName(name: string): void,
...
};
// DOM testing library extensions (jest-dom)
// https://github.com/testing-library/jest-dom
type DomTestingLibraryType = {
/**
* @deprecated
*/
toBeInTheDOM(container?: HTMLElement): void,
toBeInTheDocument(): void,
toBeVisible(): void,
toBeEmpty(): void,
toBeDisabled(): void,
toBeEnabled(): void,
toBeInvalid(): void,
toBeRequired(): void,
toBeValid(): void,
toContainElement(element: HTMLElement | null): void,
toContainHTML(htmlText: string): void,
toHaveAttribute(attr: string, value?: any): void,
toHaveClass(...classNames: string[]): void,
toHaveFocus(): void,
toHaveFormValues(expectedValues: { [name: string]: any, ... }): void,
toHaveStyle(css: string): void,
toHaveTextContent(
text: string | RegExp,
options?: { normalizeWhitespace: boolean, ... }
): void,
toHaveValue(value?: string | string[] | number): void,
...
};
// Jest JQuery Matchers: https://github.com/unindented/custom-jquery-matchers
type JestJQueryMatchersType = {
toExist(): void,
toHaveLength(len: number): void,
toHaveId(id: string): void,
toHaveClass(className: string): void,
toHaveTag(tag: string): void,
toHaveAttr(key: string, val?: any): void,
toHaveProp(key: string, val?: any): void,
toHaveText(text: string | RegExp): void,
toHaveData(key: string, val?: any): void,
toHaveValue(val: any): void,
toHaveCss(css: { [key: string]: any, ... }): void,
toBeChecked(): void,
toBeDisabled(): void,
toBeEmpty(): void,
toBeHidden(): void,
toBeSelected(): void,
toBeVisible(): void,
toBeFocused(): void,
toBeInDom(): void,
toBeMatchedBy(sel: string): void,
toHaveDescendant(sel: string): void,
toHaveDescendantWithText(sel: string, text: string | RegExp): void,
...
};
// Jest Extended Matchers: https://github.com/jest-community/jest-extended
type JestExtendedMatchersType = {
/**
* Note: Currently unimplemented
* Passing assertion
*
* @param {String} message
*/
// pass(message: string): void;
/**
* Note: Currently unimplemented
* Failing assertion
*
* @param {String} message
*/
// fail(message: string): void;
/**
* Use .toBeEmpty when checking if a String '', Array [] or Object {} is empty.
*/
toBeEmpty(): void,
/**
* Use .toBeOneOf when checking if a value is a member of a given Array.
* @param {Array.<*>} members
*/
toBeOneOf(members: any[]): void,
/**
* Use `.toBeNil` when checking a value is `null` or `undefined`.
*/
toBeNil(): void,
/**
* Use `.toSatisfy` when you want to use a custom matcher by supplying a predicate function that returns a `Boolean`.
* @param {Function} predicate
*/
toSatisfy(predicate: (n: any) => boolean): void,
/**
* Use `.toBeArray` when checking if a value is an `Array`.
*/
toBeArray(): void,
/**
* Use `.toBeArrayOfSize` when checking if a value is an `Array` of size x.
* @param {Number} x
*/
toBeArrayOfSize(x: number): void,
/**
* Use `.toIncludeAllMembers` when checking if an `Array` contains all of the same members of a given set.
* @param {Array.<*>} members
*/
toIncludeAllMembers(members: any[]): void,
/**
* Use `.toIncludeAnyMembers` when checking if an `Array` contains any of the members of a given set.
* @param {Array.<*>} members
*/
toIncludeAnyMembers(members: any[]): void,
/**
* Use `.toSatisfyAll` when you want to use a custom matcher by supplying a predicate function that returns a `Boolean` for all values in an array.
* @param {Function} predicate
*/
toSatisfyAll(predicate: (n: any) => boolean): void,
/**
* Use `.toBeBoolean` when checking if a value is a `Boolean`.
*/
toBeBoolean(): void,
/**
* Use `.toBeTrue` when checking a value is equal (===) to `true`.
*/
toBeTrue(): void,
/**
* Use `.toBeFalse` when checking a value is equal (===) to `false`.
*/
toBeFalse(): void,
/**
* Use .toBeDate when checking if a value is a Date.
*/
toBeDate(): void,
/**
* Use `.toBeFunction` when checking if a value is a `Function`.
*/
toBeFunction(): void,
/**
* Use `.toHaveBeenCalledBefore` when checking if a `Mock` was called before another `Mock`.
*
* Note: Required Jest version >22
* Note: Your mock functions will have to be asynchronous to cause the timestamps inside of Jest to occur in a differentJS event loop, otherwise the mock timestamps will all be the same
*
* @param {Mock} mock
*/
toHaveBeenCalledBefore(mock: JestMockFn<any, any>): void,
/**
* Use `.toBeNumber` when checking if a value is a `Number`.
*/
toBeNumber(): void,
/**
* Use `.toBeNaN` when checking a value is `NaN`.
*/
toBeNaN(): void,
/**
* Use `.toBeFinite` when checking if a value is a `Number`, not `NaN` or `Infinity`.
*/
toBeFinite(): void,
/**
* Use `.toBePositive` when checking if a value is a positive `Number`.
*/
toBePositive(): void,
/**
* Use `.toBeNegative` when checking if a value is a negative `Number`.
*/
toBeNegative(): void,
/**
* Use `.toBeEven` when checking if a value is an even `Number`.
*/
toBeEven(): void,
/**
* Use `.toBeOdd` when checking if a value is an odd `Number`.
*/
toBeOdd(): void,
/**
* Use `.toBeWithin` when checking if a number is in between the given bounds of: start (inclusive) and end (exclusive).
*
* @param {Number} start
* @param {Number} end
*/
toBeWithin(start: number, end: number): void,
/**
* Use `.toBeObject` when checking if a value is an `Object`.
*/
toBeObject(): void,
/**
* Use `.toContainKey` when checking if an object contains the provided key.
*
* @param {String} key
*/
toContainKey(key: string): void,
/**
* Use `.toContainKeys` when checking if an object has all of the provided keys.
*
* @param {Array.<String>} keys
*/
toContainKeys(keys: string[]): void,
/**
* Use `.toContainAllKeys` when checking if an object only contains all of the provided keys.
*
* @param {Array.<String>} keys
*/
toContainAllKeys(keys: string[]): void,
/**
* Use `.toContainAnyKeys` when checking if an object contains at least one of the provided keys.
*
* @param {Array.<String>} keys
*/
toContainAnyKeys(keys: string[]): void,
/**
* Use `.toContainValue` when checking if an object contains the provided value.
*
* @param {*} value
*/
toContainValue(value: any): void,
/**
* Use `.toContainValues` when checking if an object contains all of the provided values.
*
* @param {Array.<*>} values
*/
toContainValues(values: any[]): void,
/**
* Use `.toContainAllValues` when checking if an object only contains all of the provided values.
*
* @param {Array.<*>} values
*/
toContainAllValues(values: any[]): void,
/**
* Use `.toContainAnyValues` when checking if an object contains at least one of the provided values.
*
* @param {Array.<*>} values
*/
toContainAnyValues(values: any[]): void,
/**
* Use `.toContainEntry` when checking if an object contains the provided entry.
*
* @param {Array.<String, String>} entry
*/
toContainEntry(entry: [string, string]): void,
/**
* Use `.toContainEntries` when checking if an object contains all of the provided entries.
*
* @param {Array.<Array.<String, String>>} entries
*/
toContainEntries(entries: [string, string][]): void,
/**
* Use `.toContainAllEntries` when checking if an object only contains all of the provided entries.
*
* @param {Array.<Array.<String, String>>} entries
*/
toContainAllEntries(entries: [string, string][]): void,
/**
* Use `.toContainAnyEntries` when checking if an object contains at least one of the provided entries.
*
* @param {Array.<Array.<String, String>>} entries
*/
toContainAnyEntries(entries: [string, string][]): void,
/**
* Use `.toBeExtensible` when checking if an object is extensible.
*/
toBeExtensible(): void,
/**
* Use `.toBeFrozen` when checking if an object is frozen.
*/
toBeFrozen(): void,
/**
* Use `.toBeSealed` when checking if an object is sealed.
*/
toBeSealed(): void,
/**
* Use `.toBeString` when checking if a value is a `String`.
*/
toBeString(): void,
/**
* Use `.toEqualCaseInsensitive` when checking if a string is equal (===) to another ignoring the casing of both strings.
*
* @param {String} string
*/
toEqualCaseInsensitive(string: string): void,
/**
* Use `.toStartWith` when checking if a `String` starts with a given `String` prefix.
*
* @param {String} prefix
*/
toStartWith(prefix: string): void,
/**
* Use `.toEndWith` when checking if a `String` ends with a given `String` suffix.
*
* @param {String} suffix
*/
toEndWith(suffix: string): void,
/**
* Use `.toInclude` when checking if a `String` includes the given `String` substring.
*
* @param {String} substring
*/
toInclude(substring: string): void,
/**
* Use `.toIncludeRepeated` when checking if a `String` includes the given `String` substring the correct number of times.
*
* @param {String} substring
* @param {Number} times
*/
toIncludeRepeated(substring: string, times: number): void,
/**
* Use `.toIncludeMultiple` when checking if a `String` includes all of the given substrings.
*
* @param {Array.<String>} substring
*/
toIncludeMultiple(substring: string[]): void,
...
};
interface JestExpectType {
not: JestExpectType &
EnzymeMatchersType &
DomTestingLibraryType &
JestJQueryMatchersType &
JestStyledComponentsMatchersType &
JestExtendedMatchersType;
/**
* If you have a mock function, you can use .lastCalledWith to test what
* arguments it was last called with.
*/
lastCalledWith(...args: Array<any>): void;
/**
* toBe just checks that a value is what you expect. It uses === to check
* strict equality.
*/
toBe(value: any): void;
/**
* Use .toBeCalledWith to ensure that a mock function was called with
* specific arguments.
*/
toBeCalledWith(...args: Array<any>): void;
/**
* Using exact equality with floating point numbers is a bad idea. Rounding
* means that intuitive things fail.
*/
toBeCloseTo(num: number, delta: any): void;
/**
* Use .toBeDefined to check that a variable is not undefined.
*/
toBeDefined(): void;
/**
* Use .toBeFalsy when you don't care what a value is, you just want to
* ensure a value is false in a boolean context.
*/
toBeFalsy(): void;
/**
* To compare floating point numbers, you can use toBeGreaterThan.
*/
toBeGreaterThan(number: number): void;
/**
* To compare floating point numbers, you can use toBeGreaterThanOrEqual.
*/
toBeGreaterThanOrEqual(number: number): void;
/**
* To compare floating point numbers, you can use toBeLessThan.
*/
toBeLessThan(number: number): void;
/**
* To compare floating point numbers, you can use toBeLessThanOrEqual.
*/
toBeLessThanOrEqual(number: number): void;
/**
* Use .toBeInstanceOf(Class) to check that an object is an instance of a
* class.
*/
toBeInstanceOf(cls: Class<*>): void;
/**
* .toBeNull() is the same as .toBe(null) but the error messages are a bit
* nicer.
*/
toBeNull(): void;
/**
* Use .toBeTruthy when you don't care what a value is, you just want to
* ensure a value is true in a boolean context.
*/
toBeTruthy(): void;
/**
* Use .toBeUndefined to check that a variable is undefined.
*/
toBeUndefined(): void;
/**
* Use .toContain when you want to check that an item is in a list. For
* testing the items in the list, this uses ===, a strict equality check.
*/
toContain(item: any): void;
/**
* Use .toContainEqual when you want to check that an item is in a list. For
* testing the items in the list, this matcher recursively checks the
* equality of all fields, rather than checking for object identity.
*/
toContainEqual(item: any): void;
/**
* Use .toEqual when you want to check that two objects have the same value.
* This matcher recursively checks the equality of all fields, rather than
* checking for object identity.
*/
toEqual(value: any): void;
/**
* Use .toHaveBeenCalled to ensure that a mock function got called.
*/
toHaveBeenCalled(): void;
toBeCalled(): void;
/**
* Use .toHaveBeenCalledTimes to ensure that a mock function got called exact
* number of times.
*/
toHaveBeenCalledTimes(number: number): void;
toBeCalledTimes(number: number): void;
/**
*
*/
toHaveBeenNthCalledWith(nthCall: number, ...args: Array<any>): void;
nthCalledWith(nthCall: number, ...args: Array<any>): void;
/**
*
*/
toHaveReturned(): void;
toReturn(): void;
/**
*
*/
toHaveReturnedTimes(number: number): void;
toReturnTimes(number: number): void;
/**
*
*/
toHaveReturnedWith(value: any): void;
toReturnWith(value: any): void;
/**
*
*/
toHaveLastReturnedWith(value: any): void;
lastReturnedWith(value: any): void;
/**
*
*/
toHaveNthReturnedWith(nthCall: number, value: any): void;
nthReturnedWith(nthCall: number, value: any): void;
/**
* Use .toHaveBeenCalledWith to ensure that a mock function was called with
* specific arguments.
*/
toHaveBeenCalledWith(...args: Array<any>): void;
toBeCalledWith(...args: Array<any>): void;
/**
* Use .toHaveBeenLastCalledWith to ensure that a mock function was last called
* with specific arguments.
*/
toHaveBeenLastCalledWith(...args: Array<any>): void;
lastCalledWith(...args: Array<any>): void;
/**
* Check that an object has a .length property and it is set to a certain
* numeric value.
*/
toHaveLength(number: number): void;
/**
*
*/
toHaveProperty(propPath: string | $ReadOnlyArray<string>, value?: any): void;
/**
* Use .toMatch to check that a string matches a regular expression or string.
*/
toMatch(regexpOrString: RegExp | string): void;
/**
* Use .toMatchObject to check that a javascript object matches a subset of the properties of an object.
*/
toMatchObject(object: Object | Array<Object>): void;
/**
* Use .toStrictEqual to check that a javascript object matches a subset of the properties of an object.
*/
toStrictEqual(value: any): void;
/**
* This ensures that an Object matches the most recent snapshot.
*/
toMatchSnapshot(propertyMatchers?: any, name?: string): void;
/**
* This ensures that an Object matches the most recent snapshot.
*/
toMatchSnapshot(name: string): void;
toMatchInlineSnapshot(snapshot?: string): void;
toMatchInlineSnapshot(propertyMatchers?: any, snapshot?: string): void;
/**
* Use .toThrow to test that a function throws when it is called.
* If you want to test that a specific error gets thrown, you can provide an
* argument to toThrow. The argument can be a string for the error message,
* a class for the error, or a regex that should match the error.
*
* Alias: .toThrowError
*/
toThrow(message?: string | Error | Class<Error> | RegExp): void;
toThrowError(message?: string | Error | Class<Error> | RegExp): void;
/**
* Use .toThrowErrorMatchingSnapshot to test that a function throws a error
* matching the most recent snapshot when it is called.
*/
toThrowErrorMatchingSnapshot(): void;
toThrowErrorMatchingInlineSnapshot(snapshot?: string): void;
}
type JestObjectType = {
/**
* Disables automatic mocking in the module loader.
*
* After this method is called, all `require()`s will return the real
* versions of each module (rather than a mocked version).
*/
disableAutomock(): JestObjectType,
/**
* An un-hoisted version of disableAutomock
*/
autoMockOff(): JestObjectType,
/**
* Enables automatic mocking in the module loader.
*/
enableAutomock(): JestObjectType,
/**
* An un-hoisted version of enableAutomock
*/
autoMockOn(): JestObjectType,
/**
* Clears the mock.calls and mock.instances properties of all mocks.
* Equivalent to calling .mockClear() on every mocked function.
*/
clearAllMocks(): JestObjectType,
/**
* Resets the state of all mocks. Equivalent to calling .mockReset() on every
* mocked function.
*/
resetAllMocks(): JestObjectType,
/**
* Restores all mocks back to their original value.
*/
restoreAllMocks(): JestObjectType,
/**
* Removes any pending timers from the timer system.
*/
clearAllTimers(): void,
/**
* Returns the number of fake timers still left to run.
*/
getTimerCount(): number,
/**
* The same as `mock` but not moved to the top of the expectation by
* babel-jest.
*/
doMock(moduleName: string, moduleFactory?: any): JestObjectType,
/**
* The same as `unmock` but not moved to the top of the expectation by
* babel-jest.
*/
dontMock(moduleName: string): JestObjectType,
/**
* Returns a new, unused mock function. Optionally takes a mock
* implementation.
*/
fn<TArguments: $ReadOnlyArray<*>, TReturn>(
implementation?: (...args: TArguments) => TReturn
): JestMockFn<TArguments, TReturn>,
/**
* Determines if the given function is a mocked function.
*/
isMockFunction(fn: Function): boolean,
/**
* Given the name of a module, use the automatic mocking system to generate a
* mocked version of the module for you.
*/
genMockFromModule(moduleName: string): any,
/**
* Mocks a module with an auto-mocked version when it is being required.
*
* The second argument can be used to specify an explicit module factory that
* is being run instead of using Jest's automocking feature.
*
* The third argument can be used to create virtual mocks -- mocks of modules
* that don't exist anywhere in the system.
*/
mock(
moduleName: string,
moduleFactory?: any,
options?: Object
): JestObjectType,
/**
* Returns the actual module instead of a mock, bypassing all checks on
* whether the module should receive a mock implementation or not.
*/
requireActual(moduleName: string): any,
/**
* Returns a mock module instead of the actual module, bypassing all checks
* on whether the module should be required normally or not.
*/
requireMock(moduleName: string): any,
/**
* Resets the module registry - the cache of all required modules. This is
* useful to isolate modules where local state might conflict between tests.
*/
resetModules(): JestObjectType,
/**
* Creates a sandbox registry for the modules that are loaded inside the
* callback function. This is useful to isolate specific modules for every
* test so that local module state doesn't conflict between tests.
*/
isolateModules(fn: () => void): JestObjectType,
/**
* Exhausts the micro-task queue (usually interfaced in node via
* process.nextTick).
*/
runAllTicks(): void,
/**
* Exhausts the macro-task queue (i.e., all tasks queued by setTimeout(),
* setInterval(), and setImmediate()).
*/
runAllTimers(): void,
/**
* Exhausts all tasks queued by setImmediate().
*/
runAllImmediates(): void,
/**
* Executes only the macro task queue (i.e. all tasks queued by setTimeout()
* or setInterval() and setImmediate()).
*/
advanceTimersByTime(msToRun: number): void,
/**
* Executes only the macro task queue (i.e. all tasks queued by setTimeout()
* or setInterval() and setImmediate()).
*
* Renamed to `advanceTimersByTime`.
*/
runTimersToTime(msToRun: number): void,
/**
* Executes only the macro-tasks that are currently pending (i.e., only the
* tasks that have been queued by setTimeout() or setInterval() up to this
* point)
*/
runOnlyPendingTimers(): void,
/**
* Explicitly supplies the mock object that the module system should return
* for the specified module. Note: It is recommended to use jest.mock()
* instead.
*/
setMock(moduleName: string, moduleExports: any): JestObjectType,
/**
* Indicates that the module system should never return a mocked version of
* the specified module from require() (e.g. that it should always return the
* real module).
*/
unmock(moduleName: string): JestObjectType,
/**
* Instructs Jest to use fake versions of the standard timer functions
* (setTimeout, setInterval, clearTimeout, clearInterval, nextTick,
* setImmediate and clearImmediate).
*/
useFakeTimers(): JestObjectType,
/**
* Instructs Jest to use the real versions of the standard timer functions.
*/
useRealTimers(): JestObjectType,
/**
* Creates a mock function similar to jest.fn but also tracks calls to
* object[methodName].
*/
spyOn(
object: Object,
methodName: string,
accessType?: 'get' | 'set'
): JestMockFn<any, any>,
/**
* Set the default timeout interval for tests and before/after hooks in milliseconds.
* Note: The default timeout interval is 5 seconds if this method is not called.
*/
setTimeout(timeout: number): JestObjectType,
...
};
type JestSpyType = { calls: JestCallsType, ... };
type JestDoneFn = {|
(): void,
fail: (error: Error) => void,
|};
/** Runs this function after every test inside this context */
declare function afterEach(
fn: (done: JestDoneFn) => ?Promise<mixed>,
timeout?: number
): void;
/** Runs this function before every test inside this context */
declare function beforeEach(
fn: (done: JestDoneFn) => ?Promise<mixed>,
timeout?: number
): void;
/** Runs this function after all tests have finished inside this context */
declare function afterAll(
fn: (done: JestDoneFn) => ?Promise<mixed>,
timeout?: number
): void;
/** Runs this function before any tests have started inside this context */
declare function beforeAll(
fn: (done: JestDoneFn) => ?Promise<mixed>,
timeout?: number
): void;
/** A context for grouping tests together */
declare var describe: {
/**
* Creates a block that groups together several related tests in one "test suite"
*/
(name: JestTestName, fn: () => void): void,
/**
* Only run this describe block
*/
only(name: JestTestName, fn: () => void): void,
/**
* Skip running this describe block
*/
skip(name: JestTestName, fn: () => void): void,
/**
* each runs this test against array of argument arrays per each run
*
* @param {table} table of Test
*/
each(
...table: Array<Array<mixed> | mixed> | [Array<string>, string]
): (
name: JestTestName,
fn?: (...args: Array<any>) => ?Promise<mixed>,
timeout?: number
) => void,
...
};
/** An individual test unit */
declare var it: {
/**
* An individual test unit
*
* @param {JestTestName} Name of Test
* @param {Function} Test
* @param {number} Timeout for the test, in milliseconds.
*/
(
name: JestTestName,
fn?: (done: JestDoneFn) => ?Promise<mixed>,
timeout?: number
): void,
/**
* Only run this test
*
* @param {JestTestName} Name of Test
* @param {Function} Test
* @param {number} Timeout for the test, in milliseconds.
*/
only: {|
(
name: JestTestName,
fn?: (done: JestDoneFn) => ?Promise<mixed>,
timeout?: number
): void,
each(
...table: Array<Array<mixed> | mixed> | [Array<string>, string]
): (
name: JestTestName,
fn?: (...args: Array<any>) => ?Promise<mixed>,
timeout?: number
) => void
|},
/**
* Skip running this test
*
* @param {JestTestName} Name of Test
* @param {Function} Test
* @param {number} Timeout for the test, in milliseconds.
*/
skip(
name: JestTestName,
fn?: (done: JestDoneFn) => ?Promise<mixed>,
timeout?: number
): void,
/**
* Highlight planned tests in the summary output
*
* @param {String} Name of Test to do
*/
todo(name: string): void,
/**
* Run the test concurrently
*
* @param {JestTestName} Name of Test
* @param {Function} Test
* @param {number} Timeout for the test, in milliseconds.
*/
concurrent(
name: JestTestName,
fn?: (done: JestDoneFn) => ?Promise<mixed>,
timeout?: number
): void,
/**
* each runs this test against array of argument arrays per each run
*
* @param {table} table of Test
*/
each(
...table: Array<Array<mixed> | mixed> | [Array<string>, string]
): (
name: JestTestName,
fn?: (...args: Array<any>) => ?Promise<mixed>,
timeout?: number
) => void,
...
};
declare function fit(
name: JestTestName,
fn: (done: JestDoneFn) => ?Promise<mixed>,
timeout?: number
): void;
/** An individual test unit */
declare var test: typeof it;
/** A disabled group of tests */
declare var xdescribe: typeof describe;
/** A focused group of tests */
declare var fdescribe: typeof describe;
/** A disabled individual test */
declare var xit: typeof it;
/** A disabled individual test */
declare var xtest: typeof it;
type JestPrettyFormatColors = {
comment: {
close: string,
open: string,
...
},
content: {
close: string,
open: string,
...
},
prop: {
close: string,
open: string,
...
},
tag: {
close: string,
open: string,
...
},
value: {
close: string,
open: string,
...
},
...
};
type JestPrettyFormatIndent = string => string;
type JestPrettyFormatRefs = Array<any>;
type JestPrettyFormatPrint = any => string;
type JestPrettyFormatStringOrNull = string | null;
type JestPrettyFormatOptions = {|
callToJSON: boolean,
edgeSpacing: string,
escapeRegex: boolean,
highlight: boolean,
indent: number,
maxDepth: number,
min: boolean,
plugins: JestPrettyFormatPlugins,
printFunctionName: boolean,
spacing: string,
theme: {|
comment: string,
content: string,
prop: string,
tag: string,
value: string,
|},
|};
type JestPrettyFormatPlugin = {
print: (
val: any,
serialize: JestPrettyFormatPrint,
indent: JestPrettyFormatIndent,
opts: JestPrettyFormatOptions,
colors: JestPrettyFormatColors
) => string,
test: any => boolean,
...
};
type JestPrettyFormatPlugins = Array<JestPrettyFormatPlugin>;
/** The expect function is used every time you want to test a value */
declare var expect: {
/** The object that you want to make assertions against */
(
value: any
): JestExpectType &
JestPromiseType &
EnzymeMatchersType &
DomTestingLibraryType &
JestJQueryMatchersType &
JestStyledComponentsMatchersType &
JestExtendedMatchersType,
/** Add additional Jasmine matchers to Jest's roster */
extend(matchers: { [name: string]: JestMatcher, ... }): void,
/** Add a module that formats application-specific data structures. */
addSnapshotSerializer(pluginModule: JestPrettyFormatPlugin): void,
assertions(expectedAssertions: number): void,
hasAssertions(): void,
any(value: mixed): JestAsymmetricEqualityType,
anything(): any,
arrayContaining(value: Array<mixed>): Array<mixed>,
objectContaining(value: Object): Object,
/** Matches any received string that contains the exact expected string. */
stringContaining(value: string): string,
stringMatching(value: string | RegExp): string,
not: {
arrayContaining: (value: $ReadOnlyArray<mixed>) => Array<mixed>,
objectContaining: (value: {...}) => Object,
stringContaining: (value: string) => string,
stringMatching: (value: string | RegExp) => string,
...
},
...
};
// TODO handle return type
// http://jasmine.github.io/2.4/introduction.html#section-Spies
declare function spyOn(value: mixed, method: string): Object;
/** Holds all functions related to manipulating test runner */
declare var jest: JestObjectType;
/**
* The global Jasmine object, this is generally not exposed as the public API,
* using features inside here could break in later versions of Jest.
*/
declare var jasmine: {
DEFAULT_TIMEOUT_INTERVAL: number,
any(value: mixed): JestAsymmetricEqualityType,
anything(): any,
arrayContaining(value: Array<mixed>): Array<mixed>,
clock(): JestClockType,
createSpy(name: string): JestSpyType,
createSpyObj(
baseName: string,
methodNames: Array<string>
): { [methodName: string]: JestSpyType, ... },
objectContaining(value: Object): Object,
stringMatching(value: string): string,
...
};
================================================
FILE: package.json
================================================
{
"name": "dataloader",
"version": "2.2.3",
"description": "A data loading utility to reduce requests to a backend via batching and caching.",
"contributors": [
"Lee Byron <lee@leebyron.com> (http://leebyron.com/)",
"Daniel Schafer <dschafer@fb.com>",
"Nicholas Schrock <schrockn@fb.com>"
],
"license": "MIT",
"homepage": "https://github.com/graphql/dataloader",
"bugs": {
"url": "https://github.com/graphql/dataloader/issues"
},
"repository": {
"type": "git",
"url": "http://github.com/graphql/dataloader.git"
},
"main": "index.js",
"typings": "index.d.ts",
"scripts": {
"test": "npm run lint && npm run check && npm run testonly",
"test:ci": "npm run lint && npm run check && npm run testonly -- --coverage",
"lint": "eslint .",
"check": "flow check --max-warnings 0",
"build": "babel src --ignore src/__tests__ --out-dir dist/ ; cp src/index.js dist/index.js.flow ; cp src/index.d.ts dist/",
"watch": "babel resources/watch.js | node",
"testonly": "jest src",
"prerelease": ". ./resources/prepublish.sh",
"release": "changeset publish"
},
"files": [
"index.js",
"index.js.flow",
"index.d.ts",
"README.md",
"LICENSE",
"PATENTS"
],
"devDependencies": {
"@babel/cli": "7.7.0",
"@babel/core": "7.7.2",
"@babel/node": "7.7.0",
"@babel/preset-env": "7.7.1",
"@babel/preset-flow": "7.0.0",
"@changesets/changelog-github": "0.4.6",
"@changesets/cli": "2.24.3",
"babel-eslint": "10.0.3",
"eslint": "6.6.0",
"eslint-plugin-prettier": "^3.4.1",
"flow-bin": "0.112.0",
"jest": "24.9.0",
"prettier": "^2.8.3",
"sane": "4.1.0"
},
"publishConfig": {
"access": "public"
},
"prettier": {
"arrowParens": "avoid",
"singleQuote": true,
"trailingComma": "all",
"overrides": [
{
"files": "src/**/*.js",
"options": {
"parser": "babel-flow"
}
}
]
}
}
================================================
FILE: renovate.json
================================================
{
"$schema": "https://docs.renovatebot.com/renovate-schema.json",
"extends": [
"github>the-guild-org/shared-config:renovate",
":preserveSemverRanges"
],
"packageRules": []
}
================================================
FILE: resources/prepublish.sh
================================================
# Remove existing build artifacts
rm -rf dist;
# Build before publishing
npm run build;
# When Travis CI publishes to NPM, the published files are available in the root
# directory, which produces a cleaner distribution.
#
cp dist/* .
# Ensure a vanilla package.json before deploying so other tools do not interpret
# The built output as requiring any further transformation.
node -e "var package = require('./package.json'); \
delete package.scripts; \
delete package.devDependencies; \
delete package.publishConfig; \
require('fs').writeFileSync('dist/package.json', JSON.stringify(package, null, 2));"
================================================
FILE: resources/watch.js
================================================
/* eslint-disable no-console */
import sane from 'sane';
import { resolve as resolvePath } from 'path';
import { spawn } from 'child_process';
import flowBinPath from 'flow-bin';
process.env.PATH += ':./node_modules/.bin';
var cmd = resolvePath(__dirname);
var srcDir = resolvePath(cmd, './src');
function exec(command, options) {
return new Promise((resolve, reject) => {
var child = spawn(command, options, {
cmd,
env: process.env,
stdio: 'inherit',
});
child.on('exit', code => {
if (code === 0) {
resolve(true);
} else {
reject(new Error('Error code: ' + code));
}
});
});
}
var flowServer = spawn(flowBinPath, ['server'], {
cmd,
env: process.env,
});
var watcher = sane(srcDir, { glob: ['**/*.js'] })
.on('ready', startWatch)
.on('add', changeFile)
.on('delete', deleteFile)
.on('change', changeFile);
process.on('SIGINT', () => {
watcher.close();
flowServer.kill();
console.log(CLEARLINE + yellow(invert('stopped watching')));
process.exit();
});
var isChecking;
var needsCheck;
var toCheck = {};
var timeout;
function startWatch() {
process.stdout.write(CLEARSCREEN + green(invert('watching...')));
}
function changeFile(filepath, root, stat) {
if (!stat.isDirectory()) {
toCheck[filepath] = true;
debouncedCheck();
}
}
function deleteFile(filepath) {
delete toCheck[filepath];
debouncedCheck();
}
function debouncedCheck() {
needsCheck = true;
clearTimeout(timeout);
timeout = setTimeout(guardedCheck, 250);
}
function guardedCheck() {
if (isChecking || !needsCheck) {
return;
}
isChecking = true;
var filepaths = Object.keys(toCheck);
toCheck = {};
needsCheck = false;
checkFiles(filepaths).then(() => {
isChecking = false;
process.nextTick(guardedCheck);
});
}
function checkFiles(filepaths) {
console.log('\u001b[2J');
return parseFiles(filepaths)
.then(() => runTests(filepaths))
.then(testSuccess =>
lintFiles(filepaths).then(lintSuccess =>
typecheckStatus().then(
typecheckSuccess => testSuccess && lintSuccess && typecheckSuccess,
),
),
)
.catch(() => false)
.then(success => {
process.stdout.write(
'\n' + (success ? '' : '\x07') + green(invert('watching...')),
);
});
}
// Checking steps
function parseFiles(filepaths) {
console.log('Checking Syntax');
return Promise.all(
filepaths.map(filepath => {
if (isJS(filepath) && !isTest(filepath)) {
return exec('babel', [
'--optional',
'runtime',
'--out-file',
'/dev/null',
srcPath(filepath),
]);
}
}),
);
}
function runTests(filepaths) {
console.log('\nRunning Tests');
return exec(
'jest',
allTests(filepaths) ? filepaths.map(srcPath) : ['src'],
).catch(() => false);
}
function lintFiles(filepaths) {
console.log('Linting Code\n');
return filepaths.reduce(
(prev, filepath) =>
prev.then(prevSuccess => {
if (isJS(filepath)) {
process.stdout.write(' ' + filepath + ' ...');
return exec('eslint', [srcPath(filepath)])
.catch(() => false)
.then(success => {
console.log(
CLEARLINE + ' ' + (success ? CHECK : X) + ' ' + filepath,
);
return prevSuccess && success;
});
}
return prevSuccess;
}),
Promise.resolve(true),
);
}
function typecheckStatus() {
console.log('\nType Checking\n');
return exec(flowBinPath, ['status']).catch(() => false);
}
// Filepath
function srcPath(filepath) {
return resolvePath(srcDir, filepath);
}
// Predicates
function isJS(filepath) {
return filepath.indexOf('.js') === filepath.length - 3;
}
function allTests(filepaths) {
return filepaths.length > 0 && filepaths.every(isTest);
}
function isTest(filepath) {
return isJS(filepath) && filepath.indexOf('__tests__/') !== -1;
}
// Print helpers
var CLEARSCREEN = '\u001b[2J';
var CLEARLINE = '\r\x1B[K';
var CHECK = green('\u2713');
var X = red('\u2718');
function invert(str) {
return `\u001b[7m ${str} \u001b[27m`;
}
function red(str) {
return `\x1B[K\u001b[1m\u001b[31m${str}\u001b[39m\u001b[22m`;
}
function green(str) {
return `\x1B[K\u001b[1m\u001b[32m${str}\u001b[39m\u001b[22m`;
}
function yellow(str) {
return `\x1B[K\u001b[1m\u001b[33m${str}\u001b[39m\u001b[22m`;
}
================================================
FILE: src/__tests__/abuse.test.js
================================================
/**
* Copyright (c) 2019-present, GraphQL Foundation
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @flow
*/
const DataLoader = require('..');
describe('Provides descriptive error messages for API abuse', () => {
it('Loader creation requires a function', () => {
expect(() => {
// $FlowExpectError
new DataLoader(); // eslint-disable-line no-new
}).toThrow(
'DataLoader must be constructed with a function which accepts ' +
'Array<key> and returns Promise<Array<value>>, but got: undefined.',
);
expect(() => {
// $FlowExpectError
new DataLoader({}); // eslint-disable-line no-new
}).toThrow(
'DataLoader must be constructed with a function which accepts ' +
'Array<key> and returns Promise<Array<value>>, but got: [object Object].',
);
});
it('Load function requires an key', () => {
const idLoader = new DataLoader<number, number>(async keys => keys);
expect(() => {
// $FlowExpectError
idLoader.load();
}).toThrow(
'The loader.load() function must be called with a value, ' +
'but got: undefined.',
);
expect(() => {
// $FlowExpectError
idLoader.load(null);
}).toThrow(
'The loader.load() function must be called with a value, ' +
'but got: null.',
);
// Falsey values like the number 0 is acceptable
expect(() => {
idLoader.load(0);
}).not.toThrow();
});
it('LoadMany function requires a list of key', () => {
const idLoader = new DataLoader<number, number>(async keys => keys);
expect(() => {
// $FlowExpectError
idLoader.loadMany();
}).toThrow(
'The loader.loadMany() function must be called with Array<key> ' +
'but got: undefined.',
);
expect(() => {
// $FlowExpectError
idLoader.loadMany(1, 2, 3);
}).toThrow(
'The loader.loadMany() function must be called with Array<key> ' +
'but got: 1.',
);
// Empty array is acceptable
expect(() => {
idLoader.loadMany([]);
}).not.toThrow();
});
it('Batch function must return a Promise, not null', async () => {
// $FlowExpectError
const badLoader = new DataLoader<number, number>(() => null);
let caughtError;
try {
await badLoader.load(1);
} catch (error) {
caughtError = error;
}
expect(caughtError).toBeInstanceOf(Error);
expect((caughtError: any).message).toBe(
'DataLoader must be constructed with a function which accepts ' +
'Array<key> and returns Promise<Array<value>>, but the function did ' +
'not return a Promise: null.',
);
});
it('Batch function must return a Promise, not error synchronously', async () => {
const badLoader = new DataLoader<number, number>(() => {
throw new Error('Mock Synchronous Error');
});
let caughtError;
try {
await badLoader.load(1);
} catch (error) {
caughtError = error;
}
expect(caughtError).toBeInstanceOf(Error);
expect((caughtError: any).message).toBe(
'DataLoader must be constructed with a function which accepts ' +
'Array<key> and returns Promise<Array<value>>, but the function ' +
'errored synchronously: Error: Mock Synchronous Error.',
);
});
it('Batch function must return a Promise, not a value', async () => {
// Note: this is returning the keys directly, rather than a promise to keys.
// $FlowExpectError
const badLoader = new DataLoader<number, number>(keys => keys);
let caughtError;
try {
await badLoader.load(1);
} catch (error) {
caughtError = error;
}
expect(caughtError).toBeInstanceOf(Error);
expect((caughtError: any).message).toBe(
'DataLoader must be constructed with a function which accepts ' +
'Array<key> and returns Promise<Array<value>>, but the function did ' +
'not return a Promise: 1.',
);
});
it('Batch function must return a Promise of an Array, not null', async () => {
// Note: this resolves to undefined
// $FlowExpectError
const badLoader = new DataLoader<number, number>(async () => null);
let caughtError;
try {
await badLoader.load(1);
} catch (error) {
caughtError = error;
}
expect(caughtError).toBeInstanceOf(Error);
expect((caughtError: any).message).toBe(
'DataLoader must be constructed with a function which accepts ' +
'Array<key> and returns Promise<Array<value>>, but the function did ' +
'not return a Promise of an Array: null.',
);
});
it('Batch function must promise an Array of correct length', async () => {
// Note: this resolves to empty array
const badLoader = new DataLoader<number, number>(async () => []);
let caughtError;
try {
await badLoader.load(1);
} catch (error) {
caughtError = error;
}
expect(caughtError).toBeInstanceOf(Error);
expect((caughtError: any).message).toBe(
'DataLoader must be constructed with a function which accepts ' +
'Array<key> and returns Promise<Array<value>>, but the function did ' +
'not return a Promise of an Array of the same length as the Array ' +
'of keys.' +
'\n\nKeys:\n1' +
'\n\nValues:\n',
);
});
it('Cache should have get, set, delete, and clear methods', async () => {
class IncompleteMap {
get() {}
}
expect(() => {
// $FlowExpectError
const incompleteMap = new IncompleteMap();
const options = { cacheMap: incompleteMap };
new DataLoader(async keys => keys, options); // eslint-disable-line no-new
}).toThrow('Custom cacheMap missing methods: set, delete, clear');
});
it('Requires a number for maxBatchSize', () => {
expect(
() =>
// $FlowExpectError
new DataLoader(async keys => keys, { maxBatchSize: null }),
).toThrow('maxBatchSize must be a positive number: null');
});
it('Requires a positive number for maxBatchSize', () => {
expect(
() => new DataLoader(async keys => keys, { maxBatchSize: 0 }),
).toThrow('maxBatchSize must be a positive number: 0');
});
it('Requires a function for cacheKeyFn', () => {
expect(
() =>
// $FlowExpectError
new DataLoader(async keys => keys, { cacheKeyFn: null }),
).toThrow('cacheKeyFn must be a function: null');
});
it('Requires a function for batchScheduleFn', () => {
expect(
() =>
// $FlowExpectError
new DataLoader(async keys => keys, { batchScheduleFn: null }),
).toThrow('batchScheduleFn must be a function: null');
});
});
================================================
FILE: src/__tests__/browser.test.js
================================================
/**
* Copyright (c) 2019-present, GraphQL Foundation
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @flow
*/
// Mock out process.nextTick as not existing for this test before requiring.
process.nextTick = (null: any);
const DataLoader = require('..');
describe('Browser support', () => {
it('batches multiple requests without process.nextTick', async () => {
const loadCalls = [];
const identityLoader = new DataLoader<number, number>(async keys => {
loadCalls.push(keys);
return keys;
});
const promise1 = identityLoader.load(1);
const promise2 = identityLoader.load(2);
const [value1, value2] = await Promise.all([promise1, promise2]);
expect(value1).toBe(1);
expect(value2).toBe(2);
expect(loadCalls).toEqual([[1, 2]]);
});
});
================================================
FILE: src/__tests__/dataloader.test.js
================================================
/**
* Copyright (c) 2019-present, GraphQL Foundation
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @flow
*/
import type { Options } from '..';
const DataLoader = require('..');
function idLoader<K, C = K>(
options?: Options<K, K, C>,
): [DataLoader<K, K, C>, Array<$ReadOnlyArray<K>>] {
const loadCalls = [];
const identityLoader = new DataLoader(keys => {
loadCalls.push(keys);
return Promise.resolve(keys);
}, options);
return [identityLoader, loadCalls];
}
describe('Primary API', () => {
it('builds a really really simple data loader', async () => {
const identityLoader = new DataLoader<number, number>(async keys => keys);
const promise1 = identityLoader.load(1);
expect(promise1).toBeInstanceOf(Promise);
const value1 = await promise1;
expect(value1).toBe(1);
});
it('references the loader as "this" in the batch function', async () => {
let that;
const loader = new DataLoader<number, number>(async function (keys) {
that = this;
return keys;
});
// Trigger the batch function
await loader.load(1);
expect(that).toBe(loader);
});
it('references the loader as "this" in the cache key function', async () => {
let that;
const loader = new DataLoader<number, number>(async keys => keys, {
cacheKeyFn(key) {
that = this;
return key;
},
});
// Trigger the cache key function
await loader.load(1);
expect(that).toBe(loader);
});
it('supports loading multiple keys in one call', async () => {
const identityLoader = new DataLoader<number, number>(async keys => keys);
const promiseAll = identityLoader.loadMany([1, 2]);
expect(promiseAll).toBeInstanceOf(Promise);
const values = await promiseAll;
expect(values).toEqual([1, 2]);
const promiseEmpty = identityLoader.loadMany([]);
expect(promiseEmpty).toBeInstanceOf(Promise);
const empty = await promiseEmpty;
expect(empty).toEqual([]);
});
it('supports loading multiple keys in one call with errors', async () => {
const identityLoader = new DataLoader(keys =>
Promise.resolve(
keys.map(key => (key === 'bad' ? new Error('Bad Key') : key)),
),
);
const promiseAll = identityLoader.loadMany(['a', 'b', 'bad']);
expect(promiseAll).toBeInstanceOf(Promise);
const values = await promiseAll;
expect(values).toEqual(['a', 'b', new Error('Bad Key')]);
});
it('batches multiple requests', async () => {
const [identityLoader, loadCalls] = idLoader<number>();
const promise1 = identityLoader.load(1);
const promise2 = identityLoader.load(2);
const [value1, value2] = await Promise.all([promise1, promise2]);
expect(value1).toBe(1);
expect(value2).toBe(2);
expect(loadCalls).toEqual([[1, 2]]);
});
it('batches multiple requests with max batch sizes', async () => {
const [identityLoader, loadCalls] = idLoader<number>({ maxBatchSize: 2 });
const promise1 = identityLoader.load(1);
const promise2 = identityLoader.load(2);
const promise3 = identityLoader.load(3);
const [value1, value2, value3] = await Promise.all([
promise1,
promise2,
promise3,
]);
expect(value1).toBe(1);
expect(value2).toBe(2);
expect(value3).toBe(3);
expect(loadCalls).toEqual([[1, 2], [3]]);
});
it('applies maxBatchSize correctly with duplicate keys', async () => {
const [identityLoader, loadCalls] = idLoader<string>({
maxBatchSize: 3,
batchScheduleFn: callback => {
setTimeout(callback, 100);
},
});
const values = ['a', 'b', 'a', 'a', 'a', 'b', 'c'];
const results = await Promise.all(
values.map(value => identityLoader.load(value)),
);
expect(results).toEqual(values);
expect(loadCalls).toEqual([['a', 'b', 'c']]);
});
it('batches cached requests', async () => {
const loadCalls = [];
let resolveBatch = () => {};
const identityLoader = new DataLoader<number, number>(keys => {
loadCalls.push(keys);
return new Promise(resolve => {
resolveBatch = () => resolve(keys);
});
});
identityLoader.prime(1, 1);
const promise1 = identityLoader.load(1);
const promise2 = identityLoader.load(2);
// Track when each resolves.
let promise1Resolved = false;
let promise2Resolved = false;
promise1.then(() => {
promise1Resolved = true;
});
promise2.then(() => {
promise2Resolved = true;
});
// Move to next macro-task (tick)
await new Promise(setImmediate);
expect(promise1Resolved).toBe(false);
expect(promise2Resolved).toBe(false);
resolveBatch();
// Move to next macro-task (tick)
await new Promise(setImmediate);
expect(promise1Resolved).toBe(true);
expect(promise2Resolved).toBe(true);
const [value1, value2] = await Promise.all([promise1, promise2]);
expect(value1).toBe(1);
expect(value2).toBe(2);
expect(loadCalls).toEqual([[2]]);
});
it('max batch size respects cached results', async () => {
const loadCalls = [];
let resolveBatch = () => {};
const identityLoader = new DataLoader<number, number>(
keys => {
loadCalls.push(keys);
return new Promise(resolve => {
resolveBatch = () => resolve(keys);
});
},
{ maxBatchSize: 1 },
);
identityLoader.prime(1, 1);
const promise1 = identityLoader.load(1);
const promise2 = identityLoader.load(2);
// Track when each resolves.
let promise1Resolved = false;
let promise2Resolved = false;
promise1.then(() => {
promise1Resolved = true;
});
promise2.then(() => {
promise2Resolved = true;
});
// Move to next macro-task (tick)
await new Promise(setImmediate);
// Promise 1 resolves first since max batch size is 1,
// but it still hasn't resolved yet.
expect(promise1Resolved).toBe(false);
expect(promise2Resolved).toBe(false);
resolveBatch();
// Move to next macro-task (tick)
await new Promise(setImmediate);
expect(promise1Resolved).toBe(true);
expect(promise2Resolved).toBe(true);
const [value1, value2] = await Promise.all([promise1, promise2]);
expect(value1).toBe(1);
expect(value2).toBe(2);
expect(loadCalls).toEqual([[2]]);
});
it('coalesces identical requests', async () => {
const [identityLoader, loadCalls] = idLoader<number>();
const promise1a = identityLoader.load(1);
const promise1b = identityLoader.load(1);
const [value1a, value1b] = await Promise.all([promise1a, promise1b]);
expect(value1a).toBe(1);
expect(value1b).toBe(1);
expect(loadCalls).toEqual([[1]]);
});
it('coalesces identical requests across sized batches', async () => {
const [identityLoader, loadCalls] = idLoader<number>({ maxBatchSize: 2 });
const promise1a = identityLoader.load(1);
const promise2 = identityLoader.load(2);
const promise1b = identityLoader.load(1);
const promise3 = identityLoader.load(3);
const [value1a, value2, value1b, value3] = await Promise.all([
promise1a,
promise2,
promise1b,
promise3,
]);
expect(value1a).toBe(1);
expect(value2).toBe(2);
expect(value1b).toBe(1);
expect(value3).toBe(3);
expect(loadCalls).toEqual([[1, 2], [3]]);
});
it('caches repeated requests', async () => {
const [identityLoader, loadCalls] = idLoader<string>();
const [a, b] = await Promise.all([
identityLoader.load('A'),
identityLoader.load('B'),
]);
expect(a).toBe('A');
expect(b).toBe('B');
expect(loadCalls).toEqual([['A', 'B']]);
const [a2, c] = await Promise.all([
identityLoader.load('A'),
identityLoader.load('C'),
]);
expect(a2).toBe('A');
expect(c).toBe('C');
expect(loadCalls).toEqual([['A', 'B'], ['C']]);
const [a3, b2, c2] = await Promise.all([
identityLoader.load('A'),
identityLoader.load('B'),
identityLoader.load('C'),
]);
expect(a3).toBe('A');
expect(b2).toBe('B');
expect(c2).toBe('C');
expect(loadCalls).toEqual([['A', 'B'], ['C']]);
});
it('clears single value in loader', async () => {
const [identityLoader, loadCalls] = idLoader<string>();
const [a, b] = await Promise.all([
identityLoader.load('A'),
identityLoader.load('B'),
]);
expect(a).toBe('A');
expect(b).toBe('B');
expect(loadCalls).toEqual([['A', 'B']]);
identityLoader.clear('A');
const [a2, b2] = await Promise.all([
identityLoader.load('A'),
identityLoader.load('B'),
]);
expect(a2).toBe('A');
expect(b2).toBe('B');
expect(loadCalls).toEqual([['A', 'B'], ['A']]);
});
it('clears all values in loader', async () => {
const [identityLoader, loadCalls] = idLoader<string>();
const [a, b] = await Promise.all([
identityLoader.load('A'),
identityLoader.load('B'),
]);
expect(a).toBe('A');
expect(b).toBe('B');
expect(loadCalls).toEqual([['A', 'B']]);
identityLoader.clearAll();
const [a2, b2] = await Promise.all([
identityLoader.load('A'),
identityLoader.load('B'),
]);
expect(a2).toBe('A');
expect(b2).toBe('B');
expect(loadCalls).toEqual([
['A', 'B'],
['A', 'B'],
]);
});
it('allows priming the cache', async () => {
const [identityLoader, loadCalls] = idLoader<string>();
identityLoader.prime('A', 'A');
const [a, b] = await Promise.all([
identityLoader.load('A'),
identityLoader.load('B'),
]);
expect(a).toBe('A');
expect(b).toBe('B');
expect(loadCalls).toEqual([['B']]);
});
it('does not prime keys that already exist', async () => {
const [identityLoader, loadCalls] = idLoader<string>();
identityLoader.prime('A', 'X');
const a1 = await identityLoader.load('A');
const b1 = await identityLoader.load('B');
expect(a1).toBe('X');
expect(b1).toBe('B');
identityLoader.prime('A', 'Y');
identityLoader.prime('B', 'Y');
const a2 = await identityLoader.load('A');
const b2 = await identityLoader.load('B');
expect(a2).toBe('X');
expect(b2).toBe('B');
expect(loadCalls).toEqual([['B']]);
});
it('allows forcefully priming the cache', async () => {
const [identityLoader, loadCalls] = idLoader<string>();
identityLoader.prime('A', 'X');
const a1 = await identityLoader.load('A');
const b1 = await identityLoader.load('B');
expect(a1).toBe('X');
expect(b1).toBe('B');
identityLoader.clear('A').prime('A', 'Y');
identityLoader.clear('B').prime('B', 'Y');
const a2 = await identityLoader.load('A');
const b2 = await identityLoader.load('B');
expect(a2).toBe('Y');
expect(b2).toBe('Y');
expect(loadCalls).toEqual([['B']]);
});
it('allows priming the cache with a promise', async () => {
const [identityLoader, loadCalls] = idLoader<string>();
identityLoader.prime('A', Promise.resolve('A'));
const [a, b] = await Promise.all([
identityLoader.load('A'),
identityLoader.load('B'),
]);
expect(a).toBe('A');
expect(b).toBe('B');
expect(loadCalls).toEqual([['B']]);
});
it('allows giving the loader a name', () => {
expect(new DataLoader(() => Promise.resolve([])).name).toBeNull();
expect(new DataLoader(() => Promise.resolve([]), {}).name).toBeNull();
expect(
new DataLoader(() => Promise.resolve([]), { name: 'Some name' }).name,
).toBe('Some name');
});
});
describe('Represents Errors', () => {
it('Resolves to error to indicate failure', async () => {
const loadCalls = [];
const evenLoader = new DataLoader(keys => {
loadCalls.push(keys);
return Promise.resolve(
keys.map(key => (key % 2 === 0 ? key : new Error(`Odd: ${key}`))),
);
});
let caughtError;
try {
await evenLoader.load(1);
} catch (error) {
caughtError = error;
}
expect(caughtError).toBeInstanceOf(Error);
expect((caughtError: any).message).toBe('Odd: 1');
const value2 = await evenLoader.load(2);
expect(value2).toBe(2);
expect(loadCalls).toEqual([[1], [2]]);
});
it('Can represent failures and successes simultaneously', async () => {
const loadCalls = [];
const evenLoader = new DataLoader(keys => {
loadCalls.push(keys);
return Promise.resolve(
keys.map(key => (key % 2 === 0 ? key : new Error(`Odd: ${key}`))),
);
});
const promise1 = evenLoader.load(1);
const promise2 = evenLoader.load(2);
let caughtError;
try {
await promise1;
} catch (error) {
caughtError = error;
}
expect(caughtError).toBeInstanceOf(Error);
expect((caughtError: any).message).toBe('Odd: 1');
expect(await promise2).toBe(2);
expect(loadCalls).toEqual([[1, 2]]);
});
it('Caches failed fetches', async () => {
const loadCalls = [];
const errorLoader = new DataLoader(keys => {
loadCalls.push(keys);
return Promise.resolve(keys.map(key => new Error(`Error: ${key}`)));
});
let caughtErrorA;
try {
await errorLoader.load(1);
} catch (error) {
caughtErrorA = error;
}
expect(caughtErrorA).toBeInstanceOf(Error);
expect((caughtErrorA: any).message).toBe('Error: 1');
let caughtErrorB;
try {
await errorLoader.load(1);
} catch (error) {
caughtErrorB = error;
}
expect(caughtErrorB).toBeInstanceOf(Error);
expect((caughtErrorB: any).message).toBe('Error: 1');
expect(loadCalls).toEqual([[1]]);
});
it('Handles priming the cache with an error', async () => {
const [identityLoader, loadCalls] = idLoader<number>();
identityLoader.prime(1, new Error('Error: 1'));
// Wait a bit.
await new Promise(setImmediate);
let caughtErrorA;
try {
await identityLoader.load(1);
} catch (error) {
caughtErrorA = error;
}
expect(caughtErrorA).toBeInstanceOf(Error);
expect((caughtErrorA: any).message).toBe('Error: 1');
expect(loadCalls).toEqual([]);
});
it('Can clear values from cache after errors', async () => {
const loadCalls = [];
const errorLoader = new DataLoader(keys => {
loadCalls.push(keys);
return Promise.resolve(keys.map(key => new Error(`Error: ${key}`)));
});
let caughtErrorA;
try {
await errorLoader.load(1).catch(error => {
// Presumably determine if this error is transient, and only clear the
// cache in that case.
errorLoader.clear(1);
throw error;
});
} catch (error) {
caughtErrorA = error;
}
expect(caughtErrorA).toBeInstanceOf(Error);
expect((caughtErrorA: any).message).toBe('Error: 1');
let caughtErrorB;
try {
await errorLoader.load(1).catch(error => {
// Again, only do this if you can determine the error is transient.
errorLoader.clear(1);
throw error;
});
} catch (error) {
caughtErrorB = error;
}
expect(caughtErrorB).toBeInstanceOf(Error);
expect((caughtErrorB: any).message).toBe('Error: 1');
expect(loadCalls).toEqual([[1], [1]]);
});
it('Propagates error to all loads', async () => {
const loadCalls = [];
const failLoader = new DataLoader(keys => {
loadCalls.push(keys);
return Promise.reject(new Error('I am a terrible loader'));
});
const promise1 = failLoader.load(1);
const promise2 = failLoader.load(2);
let caughtErrorA;
try {
await promise1;
} catch (error) {
caughtErrorA = error;
}
expect(caughtErrorA).toBeInstanceOf(Error);
expect((caughtErrorA: any).message).toBe('I am a terrible loader');
let caughtErrorB;
try {
await promise2;
} catch (error) {
caughtErrorB = error;
}
expect(caughtErrorB).toBe(caughtErrorA);
expect(loadCalls).toEqual([[1, 2]]);
});
});
describe('Accepts any kind of key', () => {
it('Accepts objects as keys', async () => {
const [identityLoader, loadCalls] = idLoader<{}>();
const keyA = {};
const keyB = {};
// Fetches as expected
const [valueA, valueB] = await Promise.all([
identityLoader.load(keyA),
identityLoader.load(keyB),
]);
expect(valueA).toBe(keyA);
expect(valueB).toBe(keyB);
expect(loadCalls).toHaveLength(1);
expect(loadCalls[0]).toHaveLength(2);
expect(loadCalls[0][0]).toBe(keyA);
expect(loadCalls[0][1]).toBe(keyB);
// Caching
identityLoader.clear(keyA);
const [valueA2, valueB2] = await Promise.all([
identityLoader.load(keyA),
identityLoader.load(keyB),
]);
expect(valueA2).toBe(keyA);
expect(valueB2).toBe(keyB);
expect(loadCalls).toHaveLength(2);
expect(loadCalls[1]).toHaveLength(1);
expect(loadCalls[1][0]).toBe(keyA);
});
});
describe('Accepts options', () => {
// Note: mirrors 'batches multiple requests' above.
it('May disable batching', async () => {
const [identityLoader, loadCalls] = idLoader<number>({ batch: false });
const promise1 = identityLoader.load(1);
const promise2 = identityLoader.load(2);
const [value1, value2] = await Promise.all([promise1, promise2]);
expect(value1).toBe(1);
expect(value2).toBe(2);
expect(loadCalls).toEqual([[1], [2]]);
});
// Note: mirror's 'caches repeated requests' above.
it('May disable caching', async () => {
const [identityLoader, loadCalls] = idLoader<string>({ cache: false });
const [a, b] = await Promise.all([
identityLoader.load('A'),
identityLoader.load('B'),
]);
expect(a).toBe('A');
expect(b).toBe('B');
expect(loadCalls).toEqual([['A', 'B']]);
const [a2, c] = await Promise.all([
identityLoader.load('A'),
identityLoader.load('C'),
]);
expect(a2).toBe('A');
expect(c).toBe('C');
expect(loadCalls).toEqual([
['A', 'B'],
['A', 'C'],
]);
const [a3, b2, c2] = await Promise.all([
identityLoader.load('A'),
identityLoader.load('B'),
identityLoader.load('C'),
]);
expect(a3).toBe('A');
expect(b2).toBe('B');
expect(c2).toBe('C');
expect(loadCalls).toEqual([
['A', 'B'],
['A', 'C'],
['A', 'B', 'C'],
]);
});
it('Keys are repeated in batch when cache disabled', async () => {
const [identityLoader, loadCalls] = idLoader<string>({ cache: false });
const [values1, values2, values3, values4] = await Promise.all([
identityLoader.load('A'),
identityLoader.load('C'),
identityLoader.load('D'),
identityLoader.loadMany(['C', 'D', 'A', 'A', 'B']),
]);
expect(values1).toBe('A');
expect(values2).toBe('C');
expect(values3).toBe('D');
expect(values4).toEqual(['C', 'D', 'A', 'A', 'B']);
expect(loadCalls).toEqual([['A', 'C', 'D', 'C', 'D', 'A', 'A', 'B']]);
});
it('cacheMap may be set to null to disable cache', async () => {
const [identityLoader, loadCalls] = idLoader<string>({ cacheMap: null });
await identityLoader.load('A');
await identityLoader.load('A');
expect(loadCalls).toEqual([['A'], ['A']]);
});
it('Does not interact with a cache when cache is disabled', () => {
const promiseX = Promise.resolve('X');
const cacheMap = new Map([['X', promiseX]]);
const [identityLoader] = idLoader<string>({ cache: false, cacheMap });
identityLoader.prime('A', 'A');
expect(cacheMap.get('A')).toBe(undefined);
identityLoader.clear('X');
expect(cacheMap.get('X')).toBe(promiseX);
identityLoader.clearAll();
expect(cacheMap.get('X')).toBe(promiseX);
});
it('Does not call cacheKeyFn when cache is disabled', async () => {
const cacheKeyFnCalls = [];
const [identityLoader] = idLoader<string>({
cache: false,
cacheKeyFn: key => {
cacheKeyFnCalls.push(key);
return key;
},
});
await identityLoader.load('A');
expect(cacheKeyFnCalls).toEqual([]);
});
it('Complex cache behavior via clearAll()', async () => {
// This loader clears its cache as soon as a batch function is dispatched.
const loadCalls = [];
const identityLoader = new DataLoader<string, string>(keys => {
identityLoader.clearAll();
loadCalls.push(keys);
return Promise.resolve(keys);
});
const values1 = await Promise.all([
identityLoader.load('A'),
identityLoader.load('B'),
identityLoader.load('A'),
]);
expect(values1).toEqual(['A', 'B', 'A']);
const values2 = await Promise.all([
identityLoader.load('A'),
identityLoader.load('B'),
identityLoader.load('A'),
]);
expect(values2).toEqual(['A', 'B', 'A']);
expect(loadCalls).toEqual([
['A', 'B'],
['A', 'B'],
]);
});
describe('Accepts object key in custom cacheKey function', () => {
function cacheKey(key: { [string]: any }): string {
return Object.keys(key)
.sort()
.map(k => k + ':' + key[k])
.join();
}
type Obj = { [string]: number };
it('Accepts objects with a complex key', async () => {
const identityLoadCalls = [];
const identityLoader = new DataLoader<Obj, Obj, string>(
keys => {
identityLoadCalls.push(keys);
return Promise.resolve(keys);
},
{ cacheKeyFn: cacheKey },
);
const key1 = { id: 123 };
const key2 = { id: 123 };
const value1 = await identityLoader.load(key1);
const value2 = await identityLoader.load(key2);
expect(identityLoadCalls).toEqual([[key1]]);
expect(value1).toBe(key1);
expect(value2).toBe(key1);
});
it('Clears objects with complex key', async () => {
const identityLoadCalls = [];
const identityLoader = new DataLoader<Obj, Obj, string>(
keys => {
identityLoadCalls.push(keys);
return Promise.resolve(keys);
},
{ cacheKeyFn: cacheKey },
);
const key1 = { id: 123 };
const key2 = { id: 123 };
const value1 = await identityLoader.load(key1);
identityLoader.clear(key2); // clear equivalent object key
const value2 = await identityLoader.load(key1);
expect(identityLoadCalls).toEqual([[key1], [key1]]);
expect(value1).toBe(key1);
expect(value2).toBe(key1);
});
it('Accepts objects with different order of keys', async () => {
const identityLoadCalls = [];
const identityLoader = new DataLoader<Obj, Obj, string>(
keys => {
identityLoadCalls.push(keys);
return Promise.resolve(keys);
},
{ cacheKeyFn: cacheKey },
);
// Fetches as expected
const keyA = { a: 123, b: 321 };
const keyB = { b: 321, a: 123 };
const [valueA, valueB] = await Promise.all([
identityLoader.load(keyA),
identityLoader.load(keyB),
]);
expect(valueA).toBe(keyA);
expect(valueB).toBe(valueA);
expect(identityLoadCalls).toHaveLength(1);
expect(identityLoadCalls[0]).toHaveLength(1);
expect(identityLoadCalls[0][0]).toBe(keyA);
});
it('Allows priming the cache with an object key', async () => {
const [identityLoader, loadCalls] = idLoader<Obj, string>({
cacheKeyFn: cacheKey,
});
const key1 = { id: 123 };
const key2 = { id: 123 };
identityLoader.prime(key1, key1);
const value1 = await identityLoader.load(key1);
const value2 = await identityLoader.load(key2);
expect(loadCalls).toEqual([]);
expect(value1).toBe(key1);
expect(value2).toBe(key1);
});
});
describe('Accepts custom cacheMap instance', () => {
class SimpleMap {
stash: Object;
constructor() {
this.stash = {};
}
get(key) {
return this.stash[key];
}
set(key, value) {
this.stash[key] = value;
}
delete(key) {
delete this.stash[key];
}
clear() {
this.stash = {};
}
}
it('Accepts a custom cache map implementation', async () => {
const aCustomMap = new SimpleMap();
const identityLoadCalls = [];
const identityLoader = new DataLoader<string, string>(
keys => {
identityLoadCalls.push(keys);
return Promise.resolve(keys);
},
{ cacheMap: aCustomMap },
);
// Fetches as expected
const [valueA, valueB1] = await Promise.all([
identityLoader.load('a'),
identityLoader.load('b'),
]);
expect(valueA).toBe('a');
expect(valueB1).toBe('b');
expect(identityLoadCalls).toEqual([['a', 'b']]);
expect(Object.keys(aCustomMap.stash)).toEqual(['a', 'b']);
const [valueC, valueB2] = await Promise.all([
identityLoader.load('c'),
identityLoader.load('b'),
]);
expect(valueC).toBe('c');
expect(valueB2).toBe('b');
expect(identityLoadCalls).toEqual([['a', 'b'], ['c']]);
expect(Object.keys(aCustomMap.stash)).toEqual(['a', 'b', 'c']);
// Supports clear
identityLoader.clear('b');
const valueB3 = await identityLoader.load('b');
expect(valueB3).toBe('b');
expect(identityLoadCalls).toEqual([['a', 'b'], ['c'], ['b']]);
expect(Object.keys(aCustomMap.stash)).toEqual(['a', 'c', 'b']);
// Supports clear all
identityLoader.clearAll();
expect(Object.keys(aCustomMap.stash)).toEqual([]);
});
});
});
describe('It allows custom schedulers', () => {
it('Supports manual dispatch', () => {
function createScheduler() {
let callbacks = [];
return {
schedule(callback) {
callbacks.push(callback);
},
dispatch() {
callbacks.forEach(callback => callback());
callbacks = [];
},
};
}
const { schedule, dispatch } = createScheduler();
const [identityLoader, loadCalls] = idLoader<string>({
batchScheduleFn: schedule,
});
identityLoader.load('A');
identityLoader.load('B');
dispatch();
identityLoader.load('A');
identityLoader.load('C');
dispatch();
// Note: never dispatched!
identityLoader.load('D');
expect(loadCalls).toEqual([['A', 'B'], ['C']]);
});
it('Custom batch scheduler is provided loader as this context', () => {
let that;
function batchScheduleFn(callback) {
that = this;
callback();
}
const [identityLoader] = idLoader<string>({ batchScheduleFn });
identityLoader.load('A');
expect(that).toBe(identityLoader);
});
});
describe('It is resilient to job queue ordering', () => {
it('batches loads occuring within promises', async () => {
const [identityLoader, loadCalls] = idLoader<string>();
await Promise.all([
identityLoader.load('A'),
Promise.resolve()
.then(() => Promise.resolve())
.then(() => {
identityLoader.load('B');
Promise.resolve()
.then(() => Promise.resolve())
.then(() => {
identityLoader.load('C');
Promise.resolve()
.then(() => Promise.resolve())
.then(() => {
identityLoader.load('D');
});
});
}),
]);
expect(loadCalls).toEqual([['A', 'B', 'C', 'D']]);
});
it('can call a loader from a loader', async () => {
const deepLoadCalls = [];
const deepLoader = new DataLoader<
$ReadOnlyArray<string>,
$ReadOnlyArray<string>,
>(keys => {
deepLoadCalls.push(keys);
return Promise.resolve(keys);
});
const aLoadCalls = [];
const aLoader = new DataLoader<string, string>(keys => {
aLoadCalls.push(keys);
return deepLoader.load(keys);
});
const bLoadCalls = [];
const bLoader = new DataLoader<string, string>(keys => {
bLoadCalls.push(keys);
return deepLoader.load(keys);
});
const [a1, b1, a2, b2] = await Promise.all([
aLoader.load('A1'),
bLoader.load('B1'),
aLoader.load('A2'),
bLoader.load('B2'),
]);
expect(a1).toBe('A1');
expect(b1).toBe('B1');
expect(a2).toBe('A2');
expect(b2).toBe('B2');
expect(aLoadCalls).toEqual([['A1', 'A2']]);
expect(bLoadCalls).toEqual([['B1', 'B2']]);
expect(deepLoadCalls).toEqual([
[
['A1', 'A2'],
['B1', 'B2'],
],
]);
});
});
================================================
FILE: src/__tests__/oldbrowser.test.js
================================================
/**
* Copyright (c) 2019-present, GraphQL Foundation
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @flow
*/
// Mock out process.nextTick and setImmediate as not existing for this test
// before requiring.
process.nextTick = (null: any);
global.setImmediate = (null: any);
const DataLoader = require('..');
describe('Old browser support', () => {
it('batches multiple requests without setImmediate', async () => {
const loadCalls = [];
const identityLoader = new DataLoader<number, number>(async keys => {
loadCalls.push(keys);
return keys;
});
const promise1 = identityLoader.load(1);
const promise2 = identityLoader.load(2);
const [value1, value2] = await Promise.all([promise1, promise2]);
expect(value1).toBe(1);
expect(value2).toBe(2);
expect(loadCalls).toEqual([[1, 2]]);
});
});
================================================
FILE: src/__tests__/unhandled.test.js
================================================
/**
* Copyright (c) 2019-present, GraphQL Foundation
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @flow
*/
const DataLoader = require('..');
describe('Unhandled rejections', () => {
it('Not catching a primed error is an unhandled rejection', async () => {
let hadUnhandledRejection = false;
// Override Jest's unhandled detection
global.jasmine.process.removeAllListeners('unhandledRejection');
global.jasmine.process.on('unhandledRejection', () => {
hadUnhandledRejection = true;
});
const identityLoader = new DataLoader<number, number>(async keys => keys);
identityLoader.prime(1, new Error('Error: 1'));
// Ignore result.
identityLoader.load(1);
await new Promise(resolve => setTimeout(resolve, 10));
expect(hadUnhandledRejection).toBe(true);
});
});
gitextract_vqab7clx/
├── .changeset/
│ ├── README.md
│ └── config.json
├── .eslintignore
├── .eslintrc
├── .flowconfig
├── .github/
│ ├── ISSUE_TEMPLATE/
│ │ ├── bug-report.md
│ │ ├── feature-request.md
│ │ └── question.md
│ └── workflows/
│ └── validation.yml
├── .gitignore
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── babel.config.js
├── examples/
│ ├── CouchDB.md
│ ├── GoogleDatastore.md
│ ├── Knex.md
│ ├── Redis.md
│ ├── RethinkDB.md
│ └── SQL.md
├── flow-typed/
│ └── npm/
│ └── jest_v24.x.x.js
├── package.json
├── renovate.json
├── resources/
│ ├── prepublish.sh
│ └── watch.js
└── src/
└── __tests__/
├── abuse.test.js
├── browser.test.js
├── dataloader.test.js
├── oldbrowser.test.js
└── unhandled.test.js
SYMBOL INDEX (31 symbols across 3 files)
FILE: resources/watch.js
function exec (line 12) | function exec(command, options) {
function startWatch (line 52) | function startWatch() {
function changeFile (line 56) | function changeFile(filepath, root, stat) {
function deleteFile (line 63) | function deleteFile(filepath) {
function debouncedCheck (line 68) | function debouncedCheck() {
function guardedCheck (line 74) | function guardedCheck() {
function checkFiles (line 88) | function checkFiles(filepaths) {
function parseFiles (line 110) | function parseFiles(filepaths) {
function runTests (line 128) | function runTests(filepaths) {
function lintFiles (line 137) | function lintFiles(filepaths) {
function typecheckStatus (line 160) | function typecheckStatus() {
function srcPath (line 167) | function srcPath(filepath) {
function isJS (line 173) | function isJS(filepath) {
function allTests (line 177) | function allTests(filepaths) {
function isTest (line 181) | function isTest(filepath) {
function invert (line 192) | function invert(str) {
function red (line 196) | function red(str) {
function green (line 200) | function green(str) {
function yellow (line 204) | function yellow(str) {
FILE: src/__tests__/abuse.test.js
class IncompleteMap (line 178) | class IncompleteMap {
method get (line 179) | get() {}
FILE: src/__tests__/dataloader.test.js
method cacheKeyFn (line 51) | cacheKeyFn(key) {
function cacheKey (line 799) | function cacheKey(key: { [string]: any }): string {
class SimpleMap (line 899) | class SimpleMap {
method constructor (line 902) | constructor() {
method get (line 905) | get(key) {
method set (line 908) | set(key, value) {
method delete (line 911) | delete(key) {
method clear (line 914) | clear() {
function createScheduler (line 974) | function createScheduler() {
function batchScheduleFn (line 1006) | function batchScheduleFn(callback) {
Condensed preview — 31 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (135K chars).
[
{
"path": ".changeset/README.md",
"chars": 510,
"preview": "# Changesets\n\nHello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that wo"
},
{
"path": ".changeset/config.json",
"chars": 322,
"preview": "{\n \"$schema\": \"https://unpkg.com/@changesets/config@2.1.0/schema.json\",\n \"changelog\": [\n \"@changesets/changelog-git"
},
{
"path": ".eslintignore",
"chars": 18,
"preview": "dist/\nflow-typed/\n"
},
{
"path": ".eslintrc",
"chars": 4639,
"preview": "{\n \"globals\": {\n \"$ReadOnlyArray\": true\n },\n\n \"parser\": \"babel-eslint\",\n\n \"plugins\": [\"prettier\"],\n\n \"env\": {\n "
},
{
"path": ".flowconfig",
"chars": 191,
"preview": "[ignore]\n.*/lib/.*\n.*/dist/.*\n.*/coverage/.*\n.*/resources/.*\n.*/node_modules/y18n/test/.*\n\n[include]\n\n[libs]\n\n[options]\n"
},
{
"path": ".github/ISSUE_TEMPLATE/bug-report.md",
"chars": 771,
"preview": "---\nname: Bug report\nabout: Create a report to help us improve\ntitle: \"[BUG]\"\nlabels: bug\n---\n\n<!-- Before filing a bug,"
},
{
"path": ".github/ISSUE_TEMPLATE/feature-request.md",
"chars": 610,
"preview": "---\nname: Feature request\nabout: Suggest an idea for this project\ntitle: \"[REQUEST]\"\nlabels: enhancement\n---\n\n## What pr"
},
{
"path": ".github/ISSUE_TEMPLATE/question.md",
"chars": 486,
"preview": "---\nname: Question\nabout: Not a bug or feature request?\ntitle: \"[QUESTION]\"\nlabels: help wanted\n---\n\n<!-- \n\nPlease consi"
},
{
"path": ".github/workflows/validation.yml",
"chars": 789,
"preview": "name: Flow check, Lint and Tests \n\non: push\n\njobs:\n validation:\n name: Testing on Node ${{ matrix.node-version }}\n "
},
{
"path": ".gitignore",
"chars": 158,
"preview": "*.swp\n*~\n*.iml\n.*.haste_cache.*\n.DS_Store\n.idea\nnpm-debug.log\n\nnode_modules\ncoverage\ndist\n\n# Generated with release scri"
},
{
"path": "CHANGELOG.md",
"chars": 3189,
"preview": "# dataloader\n\n## 2.2.3\n\n### Patch Changes\n\n- [#342](https://github.com/graphql/dataloader/pull/342) [`38fedd4`](https://"
},
{
"path": "CONTRIBUTING.md",
"chars": 1598,
"preview": "# Contributing to DataLoader\n\nWe want to make contributing to this project as easy and transparent as\npossible.\n\n## Code"
},
{
"path": "LICENSE",
"chars": 1072,
"preview": "MIT License\n\nCopyright (c) GraphQL Contributors\n\nPermission is hereby granted, free of charge, to any person obtaining a"
},
{
"path": "README.md",
"chars": 25490,
"preview": "# DataLoader\n\nDataLoader is a generic utility to be used as part of your application's data\nfetching layer to provide a "
},
{
"path": "babel.config.js",
"chars": 157,
"preview": "module.exports = api => ({\n presets: api.env('test')\n ? ['@babel/preset-flow']\n : [['@babel/preset-env', { loose:"
},
{
"path": "examples/CouchDB.md",
"chars": 1123,
"preview": "# Using DataLoader with CouchDB\n\nCouchDB is a \"NoSQL\" document database which supports batch loading via the\n[HTTP Bulk "
},
{
"path": "examples/GoogleDatastore.md",
"chars": 1076,
"preview": "# Using DataLoader with Google Datastore\n\nGoogle Datastore is a \"NoSQL\" document database which supports [batch operatio"
},
{
"path": "examples/Knex.md",
"chars": 1427,
"preview": "# Using DataLoader with Knex.js\n\nThis example demonstrates how to use **DataLoader** with SQL databases via\n[Knex.js][kn"
},
{
"path": "examples/Redis.md",
"chars": 819,
"preview": "# Using DataLoader with Redis\n\nRedis is a very simple key-value store which provides the batch load method\n[MGET](http:/"
},
{
"path": "examples/RethinkDB.md",
"chars": 2711,
"preview": "# RethinkDb\n\nRethinkDb offers a batching method called `getAll` but there are a few caveats :\n\n- Order of results is not"
},
{
"path": "examples/SQL.md",
"chars": 1298,
"preview": "# Using DataLoader with SQLite\n\nWhile not a key-value store, SQL offers a natural batch mechanism with\n`SELECT * WHERE I"
},
{
"path": "flow-typed/npm/jest_v24.x.x.js",
"chars": 34126,
"preview": "// flow-typed signature: 27f8467378a99b6130bd20f54f31a644\n// flow-typed version: 6cb9e99836/jest_v24.x.x/flow_>=v0.104.x"
},
{
"path": "package.json",
"chars": 1986,
"preview": "{\n \"name\": \"dataloader\",\n \"version\": \"2.2.3\",\n \"description\": \"A data loading utility to reduce requests to a backend"
},
{
"path": "renovate.json",
"chars": 190,
"preview": "{\n \"$schema\": \"https://docs.renovatebot.com/renovate-schema.json\",\n \"extends\": [\n \"github>the-guild-org/shared-conf"
},
{
"path": "resources/prepublish.sh",
"chars": 616,
"preview": "# Remove existing build artifacts\nrm -rf dist;\n\n# Build before publishing\nnpm run build;\n\n# When Travis CI publishes to "
},
{
"path": "resources/watch.js",
"chars": 4471,
"preview": "/* eslint-disable no-console */\nimport sane from 'sane';\nimport { resolve as resolvePath } from 'path';\nimport { spawn }"
},
{
"path": "src/__tests__/abuse.test.js",
"chars": 6762,
"preview": "/**\n * Copyright (c) 2019-present, GraphQL Foundation\n *\n * This source code is licensed under the MIT license found in "
},
{
"path": "src/__tests__/browser.test.js",
"chars": 878,
"preview": "/**\n * Copyright (c) 2019-present, GraphQL Foundation\n *\n * This source code is licensed under the MIT license found in "
},
{
"path": "src/__tests__/dataloader.test.js",
"chars": 28718,
"preview": "/**\n * Copyright (c) 2019-present, GraphQL Foundation\n *\n * This source code is licensed under the MIT license found in "
},
{
"path": "src/__tests__/oldbrowser.test.js",
"chars": 933,
"preview": "/**\n * Copyright (c) 2019-present, GraphQL Foundation\n *\n * This source code is licensed under the MIT license found in "
},
{
"path": "src/__tests__/unhandled.test.js",
"chars": 907,
"preview": "/**\n * Copyright (c) 2019-present, GraphQL Foundation\n *\n * This source code is licensed under the MIT license found in "
}
]
About this extraction
This page contains the full source code of the graphql/dataloader GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 31 files (125.0 KB), approximately 33.5k tokens, and a symbol index with 31 extracted functions, classes, methods, constants, and types. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.