{"id":18308685,"url":"https://github.com/ardriveapp/promise-cache","last_synced_at":"2026-03-15T20:39:01.602Z","repository":{"id":185960424,"uuid":"673058995","full_name":"ardriveapp/promise-cache","owner":"ardriveapp","description":"Caching library designed to cache promises, enabling faster subsequent retrievals of data.","archived":false,"fork":false,"pushed_at":"2024-09-05T10:25:55.000Z","size":13277,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-21T08:11:24.753Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@ardrive/ardrive-promise-cache","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ardriveapp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-31T19:20:52.000Z","updated_at":"2024-09-05T10:25:57.000Z","dependencies_parsed_at":"2024-05-03T19:25:33.597Z","dependency_job_id":"7ff80432-c764-45bf-b0e2-5b70554c4677","html_url":"https://github.com/ardriveapp/promise-cache","commit_stats":null,"previous_names":["ar-io/promise-cache","ardriveapp/promise-cache"],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ardriveapp%2Fpromise-cache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ardriveapp%2Fpromise-cache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ardriveapp%2Fpromise-cache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ardriveapp%2Fpromise-cache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ardriveapp","download_url":"https://codeload.github.com/ardriveapp/promise-cache/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247375078,"owners_count":20928944,"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":[],"created_at":"2024-11-05T16:08:53.204Z","updated_at":"2026-03-15T20:38:56.559Z","avatar_url":"https://github.com/ardriveapp.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## @ardrive/ardrive-promise-cache\n\n`@ardrive/ardrive-promise-cache` is a caching library designed to cache promises, enabling faster subsequent retrievals of data. It includes two types of caching implementations:\n\n- [PromiseCache](#promisecache) - a simple cache that stores promises in memory\n- [ReadThroughPromiseCache](#readthroughpromisecache) - a wrapper of `PromiseCache` that allows providing an async `readThroughFunction` that is called when the cache does contain the requested key\n\n## Installation\n\nYou can install the library using npm or yarn:\n\n```bash\nnpm i @ardrive/ardrive-promise-cache\n```\n\n```bash\nyarn add @ardrive/ardrive-promise-cache\n```\n\n## Usage\n\n### PromiseCache\n\n#### Example\n\n```typescript\nimport { PromiseCache, CacheParams } from '@ardrive/ardrive-promise-cache';\n\nconst params: CacheParams = {\n  cacheCapacity: 100,\n  cacheTTL: 60_000, // cache for 1 minute\n};\n\nconst cache = new PromiseCache\u003cstring, number\u003e(params);\n\n// Storing a promise\nconst promise1 = new Promise\u003cnumber\u003e((resolve) =\u003e resolve(42));\n\ncache.put('answer', promise1);\n\n// resolves to 42\nawait cache.get('answer');\n\nconst promise2 = new Promise\u003cnumber\u003e((resolve) =\u003e resolve(100));\n\n// overwrite existing cached promise\ncache.put('answer', promise2);\n\n// resolves to 100\nawait cache.get('answer');\n\n// removes the promise from the cache\ncache.remove('answer');\n\n// resolves to undefined as no longer exists in the cache\nawait cache.get('answer');\n\n// clear the cache\ncache.clear();\n\n// Getting the cache size\nconst size = cache.size();\n```\n\n#### API\n\n#### `constructor({ cacheCapacity, cacheTTL }: CacheParams)`\n\nCreates a new `PromiseCache` instance with the specified capacity and time-to-live (TTL) for cached items.\n\n#### `put(key: K, value: Promise\u003cV\u003e): Promise\u003cV\u003e`\n\nStores a promise with the specified key in the cache.\n\n#### `get(key: K): Promise\u003cV\u003e | undefined`\n\nRetrieves a promise from the cache using the specified key. Returns `undefined` if the key is not found.\n\n#### `remove(key: K): void`\n\nRemoves a promise from the cache using the specified key.\n\n#### `clear(): void`\n\nClears the entire cache.\n\n#### `size(): number`\n\nReturns the current number of items in the cache.\n\n---\n\n### ReadThroughPromiseCache\n\nA Read Through Cache is useful for high throughput systems. If the cache contains the requested data, it is immediately returned. If the data does not exist (or has expired), the cache will fetch and place resulting promise in the cache for future requests. Some examples and use cases for Read Through Caching (and other caching patterns) can be found [here](https://www.prisma.io/dataguide/managing-databases/introduction-database-caching#read-through).\n\n#### Example\n\n```typescript\nimport { ReadThroughPromiseCache, CacheParams } from '@ardrive/ardrive-promise-cache';\n\nconst params: CacheParams = {\n  cacheCapacity: 100,\n  cacheTTL: 60_000, // cache for 1 minute\n};\n\nconst readThroughCacheParams: ReadThroughPromiseCacheParams\u003cstring,AxiosResponse\u003e = {\n  cacheParams: params,\n  readThroughFunction: async (key: K) =\u003e {\n    // This function will be called when the cache does not contain the requested key.\n    // It should return a promise that resolves with the value to cache.\n    return axios.get(`https://example.com/api/${key}`);\n  }\n};\n\n// create ReadThroughPromiseCache with capacity of 100 and TTL of 1 minute, and readThroughFunction to call API function\nconst readThroughCache = new ReadThroughPromiseCache\u003cstring, AxiosResponse\u003e(readThroughCacheParams);\n\n// caches new key and resulting axios promise (https://example.com/api/example) for 1 minute\nconst { status, data } = await readThroughCache.get('example')\n\n// the cached axios promise will be returned\nconst { status: cachedStatus, data: cacheData } = await readThroughCache.get('example')\n\n// wait 1 minute\nawait new Promise((res) =\u003e setTimeout(() =\u003e res, 60_000);\n\n// 'example' key has expired, so readThroughFunction will be called again and new promise will be returned\nconst { status: refreshedStatus, data:refreshedData } = await readThroughCache.get('example')\n```\n\n### API\n\n#### `constructor({ cacheParams: { cacheCapacity, cacheTTL }, readThroughFunction: (key: string) =\u003e Promise\u003cV\u003e: ReadThroughPromiseCacheParams)`\n\nCreates a new `ReadThroughPromiseCache` instance with the specified capacity and time-to-live (TTL) for cached items and `readThroughFunction` that will be called when the cache does not contain the key.\n\n#### `getWithStatus(key: K): Promise\u003c{status: 'hit' | 'miss', data: V}\u003e`\n\nReturns a Promise'd object, with the key 'data' pre-awaited and 'status' key indicating if it was a hit or a miss.\n\n## Note\n\nThe method `cacheKeyString(key: K): string` is used internally to create cache keys. The default implementation may not sufficiently differentiate keys for certain object types, depending on their `toJSON` implementation. You may need to override this method if you encounter issues.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fardriveapp%2Fpromise-cache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fardriveapp%2Fpromise-cache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fardriveapp%2Fpromise-cache/lists"}