{"id":27603216,"url":"https://github.com/akshitkrnagpal/keyv-dataloader","last_synced_at":"2026-02-17T09:37:09.146Z","repository":{"id":283357711,"uuid":"951284427","full_name":"akshitkrnagpal/keyv-dataloader","owner":"akshitkrnagpal","description":"A DataLoader implementation with caching support using Keyv","archived":false,"fork":false,"pushed_at":"2025-03-19T21:14:52.000Z","size":112,"stargazers_count":1,"open_issues_count":6,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-22T19:13:55.141Z","etag":null,"topics":["batching","cache","dataloader","graphql","keyv"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/keyv-dataloader","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/akshitkrnagpal.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":null,"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},"funding":{"github":"akshitkrnagpal"}},"created_at":"2025-03-19T12:49:37.000Z","updated_at":"2025-03-19T21:14:54.000Z","dependencies_parsed_at":"2025-03-19T20:46:56.856Z","dependency_job_id":null,"html_url":"https://github.com/akshitkrnagpal/keyv-dataloader","commit_stats":null,"previous_names":["akshitkrnagpal/keyv-dataloader"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akshitkrnagpal%2Fkeyv-dataloader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akshitkrnagpal%2Fkeyv-dataloader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akshitkrnagpal%2Fkeyv-dataloader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akshitkrnagpal%2Fkeyv-dataloader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/akshitkrnagpal","download_url":"https://codeload.github.com/akshitkrnagpal/keyv-dataloader/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250306639,"owners_count":21408926,"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":["batching","cache","dataloader","graphql","keyv"],"created_at":"2025-04-22T19:13:59.281Z","updated_at":"2025-10-16T10:39:57.034Z","avatar_url":"https://github.com/akshitkrnagpal.png","language":"TypeScript","readme":"# keyv-dataloader\n\nA DataLoader implementation with caching support using [Keyv](https://github.com/jaredwray/keyv). Combines the batching capabilities of Facebook's DataLoader with the flexible caching of Keyv.\n\n## Installation\n\n```bash\n# Install the package (recommended)\npnpm add keyv-dataloader\npnpm add dataloader keyv\n```\n\n```bash\n# Or with npm\nnpm install keyv-dataloader\nnpm install dataloader keyv\n```\n\n```bash\n# Or with yarn\nyarn add keyv-dataloader\nyarn add dataloader keyv\n```\n\n## Usage\n\n```typescript\nimport { KeyvDataLoader } from 'keyv-dataloader';\n\n// Create a new loader with caching\nconst loader = new KeyvDataLoader({\n  // Function to batch load keys\n  batchLoadFn: async (keys) =\u003e {\n    console.log('Loading keys:', keys);\n    return keys.map((key) =\u003e `Value for ${key}`);\n  },\n  // Optional: Custom function to generate cache keys\n  cacheKeyFn: (key) =\u003e `custom-prefix:${key}`,\n  // Optional: TTL in milliseconds (how long to keep items in cache)\n  ttl: 60 * 1000, // 1 minute\n  // Optional: Keyv options (storage adapters, etc.)\n  keyvOptions: {\n    namespace: 'my-cache',\n  },\n  // Optional: DataLoader options\n  dataLoaderOptions: {\n    maxBatchSize: 100,\n    cache: true,\n  },\n});\n\n// Load a single value (returns a Promise)\nconst value = await loader.load('key1');\n\n// Load multiple values (returns a Promise)\nconst values = await loader.loadMany(['key2', 'key3']);\n\n// Prime the cache with a value (returns a Promise that resolves to the instance for chaining)\n// If the key already exists, no change is made\nawait loader.prime('key4', 'Value for key4');\n\n// Prime the cache with an error\nawait loader.prime('key5', new Error('This is an error'));\n\n// Clear a value from cache (returns a Promise that resolves to the instance for chaining)\nawait loader.clear('key1');\n\n// Clear all cached values (returns a Promise that resolves to the instance for chaining)\nawait loader.clearAll();\n\n// Sequential calls for forcefully updating a cached value\nawait loader.clear('key1');\nawait loader.prime('key1', 'new value');\n\n// Using Promise chaining\nloader.clear('key1')\n  .then(loader =\u003e loader.prime('key1', 'new value'))\n  .then(loader =\u003e {\n    // Continue using the loader...\n  });\n```\n\n## API\n\n### `new KeyvDataLoader(options)`\n\nCreates a new `KeyvDataLoader` instance.\n\n#### Options\n\n- `batchLoadFn`: Function to batch load multiple keys\n- `cacheKeyFn` (optional): Function to generate cache key from the input key\n- `ttl` (optional): TTL in milliseconds for cache entries\n- `dataLoaderOptions` (optional): DataLoader options\n- `keyvOptions` (optional): Keyv options\n\n### Methods\n\n- **`load(key)`**: Loads a key, returns a Promise for the value\n- **`loadMany(keys)`**: Loads multiple keys, returns a Promise for array of values\n- **`prime(key, value)`**: Prime the cache with a key-value pair. Returns a Promise that resolves to the instance for method chaining. If the key already exists, no change is made. To forcefully prime the cache, clear the key first with sequential calls: `await loader.clear(key); await loader.prime(key, value);`. To prime the cache with an error, provide an Error instance.\n- **`clear(key)`**: Clear a key from cache. Returns a Promise that resolves to the instance for method chaining.\n- **`clearAll()`**: Clear all keys from cache. Returns a Promise that resolves to the instance for method chaining.\n\nAll methods return Promises. The `clear()`, `clearAll()`, and `prime()` methods resolve to the instance for method chaining, while `load()` and `loadMany()` resolve to the loaded values.\n\n## Features\n\n- **DataLoader Compatible**: Implements the same API as Facebook's DataLoader\n- **Batching**: Groups individual loads that occur within a single tick of the event loop into a single batch\n- **Efficient Caching**: Uses Keyv's batch methods (getMany, setMany) for optimal performance\n- **Redis Storage**: Works with Redis storage adapter via Keyv\n- **TypeScript Support**: Fully typed API\n- **Method Chaining**: All methods support Promise-based method chaining\n\n## Performance\n\nBy leveraging Keyv's batch operations (`getMany`, `setMany`), this implementation reduces the number of I/O operations required when working with multiple keys, resulting in better performance compared to individual operations, especially when using Redis.\n\n## Testing\n\nThe package includes a comprehensive test suite covering Redis storage adapter. See the [tests README](./tests/README.md) for detailed instructions on running tests.\n\n```bash\n# Run all tests\npnpm test\n\n# Run Redis tests only\npnpm test:redis\n\n# Run all tests with Docker (requires Docker and Docker Compose)\npnpm test:docker\n\n# Run tests with coverage\npnpm test:coverage\n```\n\n## Development\n\nThis project uses [changesets](https://github.com/changesets/changesets) for version management and publishing.\n\n```bash\n# Add a new changeset\npnpm changeset\n\n# Update versions and changelogs\npnpm version\n\n# Publish to npm\npnpm release\n```\n\n## License\n\nMIT\n","funding_links":["https://github.com/sponsors/akshitkrnagpal"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakshitkrnagpal%2Fkeyv-dataloader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakshitkrnagpal%2Fkeyv-dataloader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakshitkrnagpal%2Fkeyv-dataloader/lists"}