{"id":25006615,"url":"https://github.com/croct-tech/cache-js","last_synced_at":"2025-09-09T15:34:00.273Z","repository":{"id":272621540,"uuid":"463726625","full_name":"croct-tech/cache-js","owner":"croct-tech","description":"An abstraction layer for caching strategies.","archived":false,"fork":false,"pushed_at":"2025-01-15T17:11:45.000Z","size":854,"stargazers_count":2,"open_issues_count":4,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-11T20:48:30.766Z","etag":null,"topics":["abstraction","cache"],"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/croct-tech.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":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-26T01:50:44.000Z","updated_at":"2025-01-15T17:09:29.000Z","dependencies_parsed_at":"2025-01-15T17:32:20.948Z","dependency_job_id":"1b88c816-41d2-423c-9310-06e7a8daf8f5","html_url":"https://github.com/croct-tech/cache-js","commit_stats":null,"previous_names":["croct-tech/cache-js"],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/croct-tech%2Fcache-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/croct-tech%2Fcache-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/croct-tech%2Fcache-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/croct-tech%2Fcache-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/croct-tech","download_url":"https://codeload.github.com/croct-tech/cache-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248591990,"owners_count":21130161,"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":["abstraction","cache"],"created_at":"2025-02-05T01:50:23.733Z","updated_at":"2025-09-09T15:33:59.991Z","avatar_url":"https://github.com/croct-tech.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://croct.com\"\u003e\n        \u003cimg src=\"https://cdn.croct.io/brand/logo/repo-icon-green.svg\" alt=\"Croct\" height=\"80\"/\u003e\n    \u003c/a\u003e\n    \u003cbr /\u003e\n    \u003cstrong\u003eCache\u003c/strong\u003e\n    \u003cbr /\u003e\n    An abstraction layer for caching strategies.\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n    \u003cimg alt=\"Build\" src=\"https://github.com/croct-tech/cache-js/actions/workflows/validate-branch.yaml/badge.svg\" /\u003e\n    \u003ca href=\"https://qlty.sh/gh/croct-tech/projects/cache-js\"\u003e\u003cimg src=\"https://qlty.sh/badges/0bb508c4-718a-4b95-bf4c-7fa1287bc0d9/coverage.svg\" alt=\"Code Coverage\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://qlty.sh/gh/croct-tech/projects/cache-js\"\u003e\u003cimg src=\"https://qlty.sh/badges/0bb508c4-718a-4b95-bf4c-7fa1287bc0d9/maintainability.svg\" alt=\"Maintainability\" /\u003e\u003c/a\u003e\n\u003cbr /\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"https://github.com/croct-tech/cache-js/releases\"\u003e📦Releases\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/croct-tech/cache-js/issues/new?labels=bug\u0026template=bug-report.md\"\u003e🐞Report Bug\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/croct-tech/cache-js/issues/new?labels=enhancement\u0026template=feature-request.md\"\u003e✨Request Feature\u003c/a\u003e\n\u003c/p\u003e\n\n## Installation\n\nWe recommend using [NPM](https://www.npmjs.com) to install the package:\n\n```sh\nnpm install @croct/cache\n```\n\n## Basic usage \n\nThe most common use case of this library is to decorate implementations with caching capabilities:\n\n```ts\nimport {CacheProvider} from '@croct/cache';\n\nclass CachedService implements Service {\n    private cache: CacheProvider\u003cstring, object\u003e;\n    \n    private service: Service;\n    \n    public constructor(service: Service) {\n        this.service = service;\n        this.cache = new CacheProvider();\n    }\n    \n    public load(key: string): Promise\u003cobject\u003e {\n        return this.cache.get(key, () =\u003e this.service.load(key));\n    }\n}\n```\n\n## Methods\n\nThe [`CacheProvider\u003cK, V\u003e`](src/cacheProvider.ts) interface is the main interface of this library. \nThe generic parameter `K` is the type of the key that identifies the cached value and `V` is the type \nof the value to be cached.\n\nIt defines the following methods:\n\n### Get\n\nThe `get` method accepts a key and a loader function that's called to retrieve a new, fresh, value.\n\nWhen and how the function is called is up to the cache implementation. It is also up to the implementation\nto automatically cache the loaded value or not, see [Implementations](#implementations) for more information\nabout to know which implementations do and do not auto-cache.\n\nThe following example shows how to use the `get` method:\n\n```ts\nconst cache = new InMemoryCache\u003cstring, number\u003e();\n\nconsole.assert((await cache.get('key', () =\u003e 42)) === 42);\n```\n\n### Set\n\nThe `set` method accepts a key and a value and sets the corresponding value in the cache, overriding\nany previous entry present in the cache regardless of whether it was set manually or automatically.\n\nNormally you won't need to use this method to cache a value on a read operation. Delegating the caching\nto the `get` method is the recommended way to achieve this. This way you can define the strategy for\ncaching in the wiring of the application.\n\nThe example below shows how to use the `set` method:\n\n```ts\nconst cache = new InMemoryCache\u003cstring, number|null\u003e();\n\nawait cache.set('key', 42);\n\nconsole.assert((await cache.get('key', () =\u003e null)) === 42);\n\nawait cache.set('key', 43);\n\nconsole.assert((await cache.get('key', () =\u003e null)) === 43);\n```\n\n### Delete\n\nThe `delete` method takes a key and removes the corresponding value from the cache.\n\nHere's an example of how to delete a value from the cache:\n\n```ts\nconst cache = new InMemoryCache\u003cstring, number|null\u003e();\n\nawait cache.set('key', 42);\n\nconsole.assert((await cache.get('key', () =\u003e null)) === 42);\n\nawait cache.delete('key');\n\nconsole.assert((await cache.get('key', () =\u003e null)) === null);\n```\n\n## Implementations\n\nThis library ships with a few `CacheProvider` implementations, including:\n\n- Standalone providers\n- Adapters for key and value transformation\n- Auto-caching strategies\n- Behavior strategies\n\n### Standalone providers\n\n- [`NoopCache`](src/noop.ts): A no-op implementation that does not cache anything, suitable for testing. \n  Supports any key and value type.\n- [`InMemoryCache`](src/inMemory.ts): A simple in-memory cache implementation.\n  Supports string keys and any data type for values.\n- [`LruCache`](src/lruCache.ts): An in-memory Least Recently Used (LRU) cache implementation.\n  Like the simple in-memory cache, supports string keys and any data type for values.\n\n### Data and key manipulation\n\n- [`PrefixedCache`](src/prefixed.ts): A cache wrapper that prefixes all keys with a string.\n- [`AdaptedCache`](src/adapted.ts): A cache wrapper that adapts a typed `CacheProvider\u003cK, V\u003e` into a \n`CacheProvider\u003cIK, IV\u003e` by transforming keys and values. Available transformers:\n     - `AdaptedCache.createHashSerializer`: Serializes any object into a hash. This is typically used to transform keys into strings.\n     - `AdaptedCache.jsonSerializer`: Serializes any object to a JSON string. This is a typed wrapper around `JSON.stringify`.\n     - `AdaptedCache.jsonDeserializer`: Deserializes a JSON string into a `JsonValue`. This is a typed wrapper around `JSON.parse`.\n  \n### Auto-caching strategies\n\n- [`AutoSaveCache`](src/autoSave.ts): A cache wrapper that automatically caches the result of a loader function.\n- [`HoldWhileRevalidateCache`](src/holdWhileRevalidate.ts): A cache wrapper that automatically caches the result of a \nloader function for the expiration period that you configure. Once the cache expires, subsequent calls to the `get`\nmethod will wait until the result of the loader function is resolved.\n- [`StaleWhileRevalidateCache`](src/staleWhileRevalidate.ts): A cache wrapper that automatically caches the result \nof a loader function for the expiration period that you configure. Once the cache expires, the next `get` call will \nstill return the cached value while the loader function is being resolved in the background.\n- [`SharedInFlightCache`](src/sharedInFlight.ts): A cache that ensures there is no concurrent get requests for a key to the underlying cache.\n\n### Behavior strategies\n\n- [`ErrorResilientCache`](src/errorResilient.ts): A cache wrapper that suppresses and logs errors from the underlying cache. Consumers can then assume that the cache never fails.\n\n## Contributing\n\nContributions to the package are always welcome! \n\n- Report any bugs or issues on the [issue tracker](https://github.com/croct-tech/cache-js/issues).\n- For major changes, please [open an issue](https://github.com/croct-tech/cache-js/issues) first to discuss what you would like to change.\n- Please make sure to update tests as appropriate.\n\n## Testing\n\nBefore running the test suites, the development dependencies must be installed:\n\n```sh\nnpm install\n```\n\nThen, to run all tests:\n\n```sh\nnpm run test\n```\n\nRun the following command to check the code against the style guide:\n\n```sh\nnpm run lint\n```\n\n## Building\n\nBefore building the project, the dependencies must be installed:\n\n```sh\nnpm install\n```\n\nThe following command builds the library:\n\n```sh\nnpm run build\n```\n\n## License\n\nCopyright © 2015-2021 Croct Limited, All Rights Reserved.\n\nAll information contained herein is, and remains the property of Croct Limited. The intellectual, design and technical concepts contained herein are proprietary to Croct Limited s and may be covered by U.S. and Foreign Patents, patents in process, and are protected by trade secret or copyright law. Dissemination of this information or reproduction of this material is strictly forbidden unless prior written permission is obtained from Croct Limited.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcroct-tech%2Fcache-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcroct-tech%2Fcache-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcroct-tech%2Fcache-js/lists"}