{"id":23821006,"url":"https://github.com/truesparrowsystems/unicache","last_synced_at":"2025-09-07T03:31:24.206Z","repository":{"id":37826243,"uuid":"499026707","full_name":"TrueSparrowSystems/UniCache","owner":"TrueSparrowSystems","description":"UniCache is an NPM package that provides singleton interface and behavior for Memcached, Redis and In-memory caching. Easily interact or switch between them in minutes!","archived":false,"fork":false,"pushed_at":"2023-01-30T12:34:18.000Z","size":75,"stargazers_count":48,"open_issues_count":0,"forks_count":12,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-09-03T11:59:06.231Z","etag":null,"topics":["cache","in-memory","memcached","redis"],"latest_commit_sha":null,"homepage":"https://plgworks.com/unicache","language":"JavaScript","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/TrueSparrowSystems.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-06-02T06:58:56.000Z","updated_at":"2024-07-17T04:53:31.000Z","dependencies_parsed_at":"2023-02-16T07:30:27.057Z","dependency_job_id":null,"html_url":"https://github.com/TrueSparrowSystems/UniCache","commit_stats":null,"previous_names":["plg-works/cache","plg-works/unicache"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/TrueSparrowSystems/UniCache","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TrueSparrowSystems%2FUniCache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TrueSparrowSystems%2FUniCache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TrueSparrowSystems%2FUniCache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TrueSparrowSystems%2FUniCache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TrueSparrowSystems","download_url":"https://codeload.github.com/TrueSparrowSystems/UniCache/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TrueSparrowSystems%2FUniCache/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273992365,"owners_count":25203728,"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","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["cache","in-memory","memcached","redis"],"created_at":"2025-01-02T08:19:41.480Z","updated_at":"2025-09-07T03:31:23.852Z","avatar_url":"https://github.com/TrueSparrowSystems.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![UniCache logo Dark](https://user-images.githubusercontent.com/7627517/215476333-a8f05cb4-f785-4653-9be8-2fffc170edec.png)\n\n\n\n[![Latest version](https://img.shields.io/npm/v/@truesparrow/unicache.svg?maxAge=3600)][npm]\n\n[npm]: https://www.npmjs.com/package/@truesparrow/unicache\n\nUniCache is an open-source NPM package that provides unified / singleton interface and behavior for [Memcached](https://memcached.org/), \n[Redis](https://redis.io/docs/) and In-memory caching. Easily interact or switch between them in minutes!\n\n## Why UniCache?\n- UniCache abstracts the unnecessary deviations between the base NPM packages of Memcached and Redis, in turn helping you \nlearn about and interact with 3 different caching engines (Memcached, Redis and In-memory) all at once.\n- Singleton interface of UniCache is not only compatible with Memcached and Redis but also for In-Memory cache.\n- If your backend is interacting with multiple caching engines, UniCache helps developers to reduce translation layer \nfor input and output - thus reducing development time and effort. Even exceptions are given out consistently.\n- When using multiple caching engines simultaneously or want to switch between them, consistent output from UniCache \nwill help in faster development.\n- Be rest assured that your code will not need any further changes in order to use the upcoming base NPM package versions. \nUniCache will take care of it.\n- UniCache is thoroughly tested and is fully compatible with AWS ElastiCache for Redis and AWS ElastiCache for Memcached.\n\n## Prerequisites\n- [Node.js](https://nodejs.org/en/) (\u003e= version 6)\n- [NPM](https://www.npmjs.com/package/npm)\n\nFollow the installation guides to get the caching engines of your choice, up and running:\n- [Memcached installation guide](https://memcached.org/)\n- [Redis installation guide](https://redis.io/docs/getting-started/installation/)\n\n## Install NPM\n```shell script\nnpm install @truesparrow/unicache --save\n```\n\n## Initialize\nWhile using the package, create a singleton object of UniCache for each caching engines and then use it across the application.\nExample snippet for the UniCache singleton object initialization is given below.\n\n```js\n// Include the following snippet in a separate file, which can be required all accross the code to get unicache instance.\n// If using different caching engines simultaneously in a single codebase, have different files for each.\nconst UniCache = require('@truesparrow/unicache');\n\nconst configStrategy = {\n  engine: \"none/redis/memcached\",\n  // Other keys depend on the engine, refer to the next section on Config Strategy, for the same.\n};\n\nmodule.exports = UniCache.getInstance(configStrategy);\n```\n\nThe singleton object can be used as given below. \n```js\nconst cacheProvider = require('path-to-your-uni-cache-singleton-provider');\nconst cacheImplementer = cacheProvider.cacheInstance;\n\ncacheImplementer.set('testKey', 'testValue', 5000).then(console.log);\ncacheImplementer.get('testKey').then(console.log);\n```\n\n**Note**: To print detailed logs, add `UNICACHE_DEBUG_ENABLED = '1'` in the ENV variables.\n\n### Config Strategy\n**`configStrategy`** is a mandatory parameter which specifies the configuration to be used for the caching engine.\nUsing the `engine` property, you can select which caching engine to use.\n\nAn example of the configStrategy is:\n```js\nconst configStrategy = {\n    engine: \"none/redis/memcached\",\n  // other keys depend on the engine.\n};\n```\n\n#### Redis Config Strategy\nFollowing is how the config strategy looks for redis caching engine.\n```js\nconst configStrategy = {\n  engine: \"redis\",\n  host: \"localhost\",\n  port: \"6380\",\n  password: \"dsdsdsd\",\n  enableTsl: \"0\",\n  defaultTtl: 36000,\n  consistentBehavior: \"1\"\n}\n````\n- **engine**: Pass value `redis` for using UniCahce with Redis. \n- **host**: Host of the Redis server.\n- **port**: Port of the Redis server.\n- **password**: Password for auth with Redis server.\n- **enableTsl**: Pass '1' for enabling TSL. Otherwise '0'\n- **defaultTtl**: Default time to live (TTL) for cache in seconds.\n- **consistentBehavior**: Pass '1' to use the consistent behaviour accross various caching engines option. Otherwise '0'.\n\n#### Memcache Config Strategy\nFollowing is how the config strategy looks for Memcache caching engine.\n```js\nconst configStrategy = {\n  engine: \"memcached\",\n  servers: [\"127.0.0.1:11211\"],\n  defaultTtl: 36000,\n  consistentBehavior: \"1\"\n}\n````\n- **engine**: Pass value `memcached` for using UniCahce with Memcache.\n- **servers**: Servers is an array of memcached servers' hosts.\n- **defaultTtl**: Default time to live (TTL) for cache in seconds.\n- **consistentBehavior**: Pass '1' to use the consistent behaviour accross various caching engines option. Otherwise '0'.\n\n#### In-Memory Config Strategy\nFollowing is how the config strategy looks for In-memory caching engine.\n```js\nconst configStrategy = {\n  engine: \"none\",\n  namespace: \"A\",\n  defaultTtl: \"36000\",\n  consistentBehavior: \"1\"\n}\n```\n- **engine**: Pass value `none` for using UniCahce with In-memory cache.\n- **namespace**: In-memory cache namespace. You can segregate cache keys in the same machine with different namespaces.\n- **defaultTtl**: Default time to live (TTL) for cache in seconds.\n- **consistentBehavior**: Pass '1' to use the consistent behaviour accross various caching engines option. Otherwise '0'.\n\n## `cacheImplementer` methods\nIrrespective of the caching engine, the methods exposed in `cacheImplementer` have the consistent signature, \ni.e. singleton interface implementation.\n\n### Store and retrieve data in cache using `set` and `get`:\n```js\nconst resolvePromise = function(cacheResponse){\n                           if (cacheResponse.isSuccess()) {\n                             console.log(cacheResponse.data.response);\n                           } else {\n                             console.log(cacheResponse);\n                           }\n                         };\n\ncacheImplementer.set('testKey', 'testValue', 5000).then(resolvePromise);\n\ncacheImplementer.get('testKey').then(resolvePromise);\n```\n\n### Manage objects in cache using `setObject` and `getObject`:\n\n```js\ncacheImplementer.setObject('testObjKey', {dataK1: 'a', dataK2: 'b'}).then(resolvePromise);\ncacheImplementer.getObject('testObjKey').then(resolvePromise);\n```\n\n### Retrieve multiple cache data using `multiGet`:\n\n\u003cb\u003eNOTE: Redis returns null from `multiGet` for objects, even if a value is set in the cache. The other caching implementers match this behaviour.\u003c/b\u003e\n\n```js\ncacheImplementer.set('testKeyOne', 'One').then(console.log);\ncacheImplementer.set('testKeyTwo', 'Two').then(console.log);\ncacheImplementer.multiGet(['testKeyOne', 'testKeyTwo']).then(resolvePromise);\n```\n\n### Delete cache using `del`:\n\n```js\ncacheImplementer.set('testKey', 'testValue').then(console.log);\ncacheImplementer.del('testKey').then(resolvePromise);\n```\n\n### Manage counters in cache using `increment` and `decrement`: \n\n```js\ncacheImplementer.set('testCounterKey', 1).then(console.log);\ncacheImplementer.increment('testCounterKey', 10).then(resolvePromise);\ncacheImplementer.decrement('testCounterKey', 5).then(resolvePromise);\n```\n\n### Change the cache expiry time using `touch`:\n\n```js\ncacheImplementer.set('testKey', \"testData\").then(console.log);\ncacheImplementer.touch('testKey', 10).then(resolvePromise);\n```\n\n## Test Cases\nTest cases cover all the 3 caching engines. Also a coverage report is generated at the end.\nRunning test cases is a 2 step process.\n\n### Step 1: Start Cache Engines\nFollowing processes are needed for running test cases.\n\n* Start Redis on 2 ports - 6380 and 6381 as needed by the test cases.\n```shell script\nredis-server --port 6380\nredis-server --port 6381\n```\n\n* Start Memcached on 4 ports - 11212,11213,11214 and 11215 as needed by the test cases.\n```shell script\nmemcached -p 11212 -d\nmemcached -p 11213 -d\nmemcached -p 11214 -d\nmemcached -p 11215 -d\n```\n\n### Step 2: Run tests\nFor running tests for all the 3 caching engines, use the following command.\n```shell script\nnpm run test\n```\n\n## Contribution\nWe welcome more helping hands to make UniCache better. Feel free to report issues, raise PRs for fixes \u0026 enhancements.\n\n\u003cp align=\"left\"\u003eBuilt with :heart: by \u003ca href=\"https://truesparrow.com/\" target=\"_blank\"\u003eTrue Sparrow\u003c/a\u003e\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftruesparrowsystems%2Funicache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftruesparrowsystems%2Funicache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftruesparrowsystems%2Funicache/lists"}