{"id":13727330,"url":"https://github.com/Yelp/dataloader-codegen","last_synced_at":"2025-05-07T22:31:05.473Z","repository":{"id":36307461,"uuid":"221556825","full_name":"Yelp/dataloader-codegen","owner":"Yelp","description":"🤖 dataloader-codegen is an opinionated JavaScript library for automatically generating DataLoaders over a set of resources (e.g. HTTP endpoints).","archived":false,"fork":false,"pushed_at":"2025-05-02T17:08:08.000Z","size":2405,"stargazers_count":113,"open_issues_count":45,"forks_count":11,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-02T17:30:25.048Z","etag":null,"topics":["dataloader","graphql","nodejs"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Yelp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-13T21:41:01.000Z","updated_at":"2025-02-14T21:58:31.000Z","dependencies_parsed_at":"2024-01-06T03:45:13.738Z","dependency_job_id":"3e945e42-8340-47c8-9888-0a15f30b4696","html_url":"https://github.com/Yelp/dataloader-codegen","commit_stats":{"total_commits":85,"total_committers":9,"mean_commits":9.444444444444445,"dds":0.6235294117647059,"last_synced_commit":"f1ff4c46c5cd356c609813c61ba7f313dce88dd8"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yelp%2Fdataloader-codegen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yelp%2Fdataloader-codegen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yelp%2Fdataloader-codegen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yelp%2Fdataloader-codegen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Yelp","download_url":"https://codeload.github.com/Yelp/dataloader-codegen/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252965358,"owners_count":21832878,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dataloader","graphql","nodejs"],"created_at":"2024-08-03T01:03:50.066Z","updated_at":"2025-05-07T22:31:04.907Z","avatar_url":"https://github.com/Yelp.png","language":"TypeScript","readme":"# 🤖 dataloader-codegen\n\n[![npm](https://img.shields.io/npm/v/dataloader-codegen.svg)](https://yarn.pm/dataloader-codegen)\n[![Build Status](https://api.travis-ci.com/Yelp/dataloader-codegen.svg?branch=master)](https://travis-ci.com/github/Yelp/dataloader-codegen)\n\ndataloader-codegen is an opinionated JavaScript library for automagically generating [DataLoaders](https://github.com/graphql/dataloader) over a set of resources (e.g. HTTP endpoints), with a predictable interface, and maintains type safety.\n\nRead more about the motivation behind this library in our recent blog post: https://engineeringblog.yelp.com/2020/04/open-sourcing-dataloader-codegen.html\n\n![header](./images/header.png)\n\n**Features**:\n\n-   🚚 Supports Batched + Non Batched Resources\n-   ✨ Predictable DataLoader Interfaces\n-   🐛 Error Handling\n-   🔒 Type Safety (Flow)\n-   🔧 Resource Middleware\n\n## Install\n\n```bash\n$ yarn add --dev dataloader-codegen\n```\n\n## Why?\n\n_See: https://engineeringblog.yelp.com/2020/04/open-sourcing-dataloader-codegen.html_\n\nWe believe the DataLoader layer should be (mostly) transparent when implementing\na GraphQL server over a set of existing resources (e.g. HTTP API Endpoints).\n\nWhen fetching data, GraphQL resolver authors should think in terms of the\nunderlying _resources_ that they're already familiar with, not an invented set\nof human defined DataLoaders.\n\nWith dataloader-codegen, we build a **1:1 mapping of resources to DataLoaders**:\n\n\u003cimg src=\"https://raw.githubusercontent.com/Yelp/dataloader-codegen/master/images/mapping.png\" height=\"400\" /\u003e\n\nThis makes it super easy to find the DataLoaders you want - there will be\nexactly 1 DataLoader available per resource, with a predictable name and interface.\n\nThis means **reduced risk of making unnecessary HTTP requests.**\n\nIf there were (accidentally!) multiple DataLoaders created for a single\nendpoint, we potentially lose out on batched requests to that resource.\n\nBy keeping the mapping of one DataLoader per resource, we reduce that risk\nand can make a more efficient set of HTTP requests to the underlying resource.\n\n## Usage\n\n1. Create `dataloader-config.yaml` to describe the shape and behaviour of your resources. (See [the docs](./API_DOCS.md) for detailed info.)\n\n    **Example**\n\n    ```yaml\n    resources:\n        getPeople:\n            docsLink: https://swapi.dev/documentation#people\n            isBatchResource: true\n            batchKey: people_ids\n            newKey: person_id\n        getPlanets:\n            docsLink: https://swapi.dev/documentation#planets\n            isBatchResource: true\n            batchKey: planet_ids\n            newKey: planet_id\n        ...\n    ```\n\n    _(Can be arbitrarily nested. See the [swapi example](./examples/swapi/swapi.dataloader-config.yaml) for an example.)_\n\n2. Call `dataloader-codegen` and pass in your config file:\n\n    ```bash\n    $ dataloader-codegen --config swapi.dataloader-config.yaml --output __codegen__/swapi-loaders.js\n    ```\n\n    See `--help` for more options.\n\n3. Import the generated loaders and use them in your [resolver methods](https://www.apollographql.com/docs/graphql-tools/resolvers/):\n\n    ```js\n    import getLoaders from './__codegen__/swapi-loaders';\n\n    // StarWarsAPI is a clientlib containing fetch calls to swapi.dev\n    // getLoaders is the function that dataloader-codegen generates for us\n    const swapiLoaders = getLoaders(StarWarsAPI);\n\n    class Planet {\n        constructor(id) {\n            this.id = id;\n        }\n\n        async diameter() {\n            const { diameter } = await swapiLoaders.getPlanets.load({ planet_id: this.id });\n\n            return diameter;\n        }\n    }\n    ```\n\n    Check out the [swapi example](./examples/swapi/swapi-server.js) to see a working example of this.\n\n## Batch Resources\n\nThe [DataLoader `.load` interface](https://github.com/graphql/dataloader#loadkey)\naccepts a single key and returns a single value. For [batch resources](https://www.codementor.io/blog/batch-endpoints-6olbjay1hd), we'll need to transform the DataLoader interface accordingly.\n\n**Example**\n\nConsider the following resource that returns information about users:\n\n```js\nconst getUserInfo = (args: {\n    user_ids: Array\u003cnumber\u003e,\n    locale: string,\n    include_slow_fields?: boolean,\n}): Promise\u003cArray\u003cUserInfo\u003e\u003e =\u003e fetch('/userInfo', args);\n```\n\nThis is a [batch resource](https://www.codementor.io/blog/batch-endpoints-6olbjay1hd) that accepts a list of users (`user_ids`) and returns a list of corresponding user objects (`Array\u003cUserInfo\u003e`).\n\nFor the DataLoader version of this, we'll want to instead ask for a **single** user\nobject at a time. This means we need to transform the interface in the following\nways:\n\n1. Call `.load` with the same arguments, but switch \"user_ids\" to \"user_id\".\n\n2. Return a _single_ `UserInfo` object from `.load`, instead of an _array_ of\n   `UserInfo` objects.\n\n![demo!](./images/demo.png)\n\nWe can control this by specifying `batchKey` and `newKey` in the config to\ndescribe the relevant argument in the resource and DataLoader respectively.\n\nThe config for our `getUserInfo` would therefore look like this:\n\n```yaml\nresources:\n    getUserInfo:\n        isBatchResource: true\n        batchKey: user_ids\n        newKey: user_id\n```\n\nSee [the full docs](./API_DOCS.md) for more information on how to configure resources.\n\n## Contributing\n\nPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.\n\nPlease make sure to update tests as appropriate.\n\n## Releasing\n\nSee [PUBLISH.md](PUBLISH.md)\n\n## License\n\n[MIT](https://choosealicense.com/licenses/mit/)\n","funding_links":[],"categories":["JavaScript","Tools","TypeScript"],"sub_categories":["Tools - Miscellaneous"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYelp%2Fdataloader-codegen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FYelp%2Fdataloader-codegen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYelp%2Fdataloader-codegen/lists"}