Skip to content

Commit 987feca

Browse files
kedarchandrayankedarchandrayan
authored
Merge pull request #13 from PLG-Works/release-1.0
Merging release 1 along with beta tag. Beta to be removed later.
2 parents 1c50f75 + a28c74f commit 987feca

33 files changed

Lines changed: 568 additions & 215 deletions

‎.npmignore‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Logs
2+
logs
3+
*.log
4+
npm-debug.log*
5+
yarn-debug.log*
6+
yarn-error.log*
7+
8+
# Runtime data
9+
pids
10+
*.pid
11+
*.seed
12+
*.pid.lock
13+
package-lock.json
14+
15+
# SDK
16+
/.idea
17+
/.idea/*
18+
.DS_Store
19+
20+
# Directory for instrumented libs generated by jscoverage/JSCover
21+
lib-cov
22+
23+
# Coverage directory used by tools like istanbul
24+
coverage
25+
26+
# nyc test coverage
27+
.nyc_output
28+
29+
# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
30+
.grunt
31+
32+
# Bower dependency directory (https://bower.io/)
33+
bower_components
34+
35+
# node-waf configuration
36+
.lock-wscript
37+
38+
# Compiled binary addons (http://nodejs.org/api/addons.html)
39+
build/Release
40+
41+
# Dependency directories
42+
node_modules/
43+
jspm_packages/
44+
45+
# Dev Folder
46+
.dev
47+
48+
# Debug log from npm
49+
npm-debug.log
50+
.vscode
51+
52+
# Typescript v1 declaration files
53+
typings/
54+
55+
# Optional npm cache directory
56+
.npm
57+
58+
# Optional eslint cache
59+
.eslintcache
60+
61+
# Optional REPL history
62+
.node_repl_history
63+
64+
# Output of 'npm pack'
65+
*.tgz
66+
67+
# Yarn Integrity file
68+
.yarn-integrity
69+
70+
# dotenv environment variables file
71+
.env

‎.travis.yml‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
dist: bionic
2+
language: node_js
3+
sudo: required
4+
branches:
5+
only:
6+
- master
7+
- prep_for_ph_launch
8+
- /^release-.*/
9+
notifications:
10+
email:
11+
recipients:
12+
- kedar@plgworks.com
13+
on_success: always
14+
on_failure: always
15+
node_js:
16+
- "18"
17+
- "16"
18+
services:
19+
- "memcached"
20+
before_install:
21+
- sudo apt-get update
22+
- sudo apt-get install nodejs
23+
- sudo apt-get install npm
24+
install:
25+
- npm install
26+
before_script:
27+
- memcached -p 11212 -d
28+
- memcached -p 11213 -d
29+
- memcached -p 11214 -d
30+
- memcached -p 11215 -d
31+
- sudo redis-server /etc/redis/redis.conf --port 6380 --requirepass 'my-secret'
32+
- sudo redis-server /etc/redis/redis.conf --port 6381 --requirepass 'my-secret'
33+
- ps aux | grep 'memcached'
34+
- ps aux | grep 'redis-server'
35+
script:
36+
- npm run test
37+
after_script: "skip"

‎CHANGELOG.md‎

Lines changed: 3 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,3 @@
1-
## Cache v1.0.3
2-
- LICENSE changes.
3-
4-
## Cache v1.0.2
5-
- `redis` NPM version updated to 3.1.1 for fixing `Potential exponential regex in monitor mode` security vulnerability.
6-
7-
## Cache v1.0.1
8-
- First time cache set intermittent issue fixed for memcached.
9-
10-
## Cache v1.0.0
11-
- Cache is cache implementation of three caching engines Memcached, Redis and In-memory.
1+
## UniCache v1.0.0-beta.1
2+
- First release of UniCache having support for 3 caching engines - Memcached, Redis and In-memory Cache
3+
- Test case coverage improved to 95%.

‎CONTRIBUTING.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Contributing
2+
3+
Helping hands are always welcome to contribute with bug fixes and enhancements to UniCache. Feel free to report issues
4+
which you observe while integrating UniCache in your project.
5+
6+
## How to Report Issues
7+
To report an issue, please use the [Github issues tracker](https://github.com/PLG-Works/UniCache/issues). When reporting issues,
8+
please mention the following details, whichever applicable:
9+
- Steps to reproduce with sample snippets.
10+
- Actual vs. expected behaviour.
11+
- Whether it is a bug or proposed enhancement.
12+
- Release version which the issue is concerned with.
13+
14+
## Workflow for Pull Requests
15+
In order to contribute, please fork off the particular release-{version} branch and make your changes there. Your commit
16+
messages should detail why you made your change in addition to what you did (unless it is a tiny change).
17+
18+
If you are enhancing with a new feature, please ensure to add appropriate test cases under `test/` folder. It's also a
19+
good practice to add new test cases in case of bug fixes too.
20+
21+
Please update CHANGELOG.md with each PR.
22+
23+
If you are taking up a big change, please add an issue and discuss with the UniCache team first to get opinions from
24+
multiple developers.
25+
26+
Finally, please respect the coding style of this project. And of course, please test your code thoroughly before raising PR.
27+
28+
Thank you for your help!
29+
30+

‎README.md‎

Lines changed: 95 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -1,108 +1,122 @@
1-
# Cache
1+
![UniCache logo Dark](https://user-images.githubusercontent.com/7627517/195535780-47906a3b-c302-4c59-bb1e-d171914ff1bd.png)
22

33
[![Latest version](https://img.shields.io/npm/v/@plgworks/cache.svg?maxAge=3600)][npm]
44

5-
[npm]: https://www.npmjs.com/package/@plgworks/cache
5+
[npm]: https://www.npmjs.com/package/@plgworks/unicache
66

7-
Cache NPM implements wrapper over multiple caching engines - [Memcached](https://memcached.org/), [Redis](https://redis.io/docs/) and In-memory (use with single threaded process in development mode only).
8-
The decision of which caching engine to use is governed while creating the Cache NPM object.
7+
UniCache is an NPM package that provides singleton interface and behavior for [Memcached](https://memcached.org/), [Redis](https://redis.io/docs/) and
8+
In-memory caching. Easily interact or switch between them in minutes!
99

10-
## Why Cache?
11-
Core packages of different caching systems do not have a common interface, i.e. they have the same functionality implemented with different method signatures.
12-
Thus changing from one cache system to another becomes difficult as all the usages need to be revisited.
13-
This NPM package solves the problem by providing common wrapper methods for memcached, redis and in-memory caching systems.
10+
## Why UniCache?
11+
- UniCache abstracts the unnecessary deviations between the base packages, in turn helping you learn about and interact with 3 different caching engines (Memcached, Redis and In-memory) all at once.
12+
- Singleton interface of UniCache is not only compatible with Memcached and Redis but also for In-Memory cache.
13+
- If your backend is interacting with multiple caching engines, UniCache helps developers to reduce translation layer for input and output - thus reducing development time and effort.
14+
- When using multiple caching engines simultaneously or want to switch between them, consistent output from UniCache will help in faster development. Even exceptions are given out consistently.
15+
- Be rest assured that your code will not need any further changes in order to use the upcoming base NPM package versions. UniCache will take care of it.
16+
- UniCache is thoroughly tested and is fully compatible with AWS ElastiCache for Redis and AWS ElastiCache for Memcached.
1417

1518
## Prerequisites
16-
Required caching engine for the use case must be installed and up.
17-
Refer [memcached](https://memcached.org/) and [redis](https://redis.io/docs/getting-started/installation/) installation guide.
19+
- [Node.js](https://nodejs.org/en/) (>= version 6)
20+
- [NPM](https://www.npmjs.com/package/npm)
1821

19-
## Installion
22+
Follow the installation guides to get the caching engines of your choice, up and running:
23+
- [Memcached installation guide](https://memcached.org/)
24+
- [Redis installation guide](https://redis.io/docs/getting-started/installation/)
25+
26+
## Install NPM
2027
```shell script
21-
npm install @plgworks/cache --save
28+
npm install @plgworks/unicache --save
2229
```
2330

2431
## Initialize
32+
While using the package, create a singleton object of UniCache and then use it across the application. Example snippet for the UniCache singleton object is given below.
2533

2634
```js
27-
const Cache = require('@plgworks/cache');
35+
// Include the following snippet in a separate file, which can be required all accross the code to get unicache instance.
36+
// If using different caching engines simultaneously in a single codebase, have different files for each.
37+
const UniCache = require('@plgworks/unicache');
2838

29-
const configStrategy = {}; // Refer the next section for detailed documentation on configStrategy
30-
const cache = Cache.getInstance(configStrategy);
39+
const configStrategy = {
40+
engine: "none/redis/memcached",
41+
// Other keys depend on the engine, refer to the next section on Config Strategy, for the same.
42+
};
3143

32-
const cacheImplementer = cache.cacheInstance;
44+
module.exports = UniCache.getInstance(configStrategy);
45+
```
46+
47+
The singleton object can be used as given below.
48+
```js
49+
const cacheProvider = require('path-to-your-uni-cache-singleton-provider');
50+
const cacheImplementer = cacheProvider.cacheInstance;
51+
52+
cacheImplementer.set('testKey', 'testValue', 5000);
53+
cacheImplementer.get('testKey');
3354
```
3455

3556
**Note**: To print detailed logs, add `CACHE_DEBUG_ENABLED = '1'` in your env variables.
3657

3758
### Config Strategy
38-
**`configStrategy`** is a mandatory parameter which specifies the configuration strategy to be used for a particular cache engine.
59+
**`configStrategy`** is a mandatory parameter which specifies the configuration strategy to be used for the caching engine.
60+
Using the `engine` property, you can select which caching engine to use.
3961

4062
An example of the configStrategy is:
4163
```js
4264
const configStrategy = {
43-
cache: {
4465
engine: "none/redis/memcached",
45-
host: "",
46-
port: "",
47-
password: "",
48-
enableTsl: "",
49-
defaultTtl: 10000,
50-
consistentBehavior: "",
51-
servers:[],
52-
namespace: ""
53-
}
66+
// other keys depend on the engine.
5467
};
5568
```
56-
- **engine**: redis, memcached are different types of caching engine. For in-memory cache engine parameter will be `none`.
69+
70+
#### Redis Config Strategy
71+
Following is the redis engine config strategy to be used in initializing UniCache.
72+
```js
73+
const configStrategy = {
74+
engine: "redis",
75+
host: "localhost",
76+
port: "6380",
77+
password: "dsdsdsd",
78+
enableTsl: "0",
79+
defaultTtl: 36000,
80+
consistentBehavior: "1"
81+
}
82+
````
83+
- **engine**: redis caching engine to be used.
5784
- **host**: Host of the redis caching engine.
5885
- **port**: Port on which redis caching engine is running.
5986
- **password**: Redis caching engine password.
6087
- **enableTsl**: This field is used to enable tsl.
6188
- **defaultTtl**: Default cache expiry time in sec.
6289
- **consistentBehavior**: This field is required to create cache instance key.
63-
- **servers**: servers is an array of memcached servers.
64-
- **namespace**: It is in-memory cache namespace.
6590

66-
67-
#### Redis Example
68-
Following is an example of redis engine config strategy to be used in initializing Cache.
69-
```js
70-
const configStrategy = {
71-
cache: {
72-
engine: "redis",
73-
host: "localhost",
74-
port: "6830",
75-
password: "dsdsdsd",
76-
enableTsl: "0",
77-
defaultTtl: 36000,
78-
consistentBehavior: "1"
79-
}
80-
}
81-
````
82-
#### Memcache Example
83-
Following is an example of memcache engine config strategy to be used in initializing Cache.
91+
#### Memcache Config Strategy
92+
Following is the memcache engine config strategy to be used in initializing UniCache.
8493
```js
8594
const configStrategy = {
86-
cache: {
87-
engine: "memcached",
88-
servers: ["127.0.0.1:11211"],
89-
defaultTtl: 36000,
90-
consistentBehavior: "1"
91-
}
95+
engine: "memcached",
96+
servers: ["127.0.0.1:11211"],
97+
defaultTtl: 36000,
98+
consistentBehavior: "1"
9299
}
93100
````
94-
#### In-memory Example
95-
Following is an example of in-memory engine config strategy to be used in initializing Cache.
101+
- **engine**: memcached caching engine to be used.
102+
- **servers**: servers is an array of memcached servers.
103+
- **defaultTtl**: Default cache expiry time in sec.
104+
- **consistentBehavior**: This field is required to create cache instance key.
105+
106+
#### In-Memory Config Strategy
107+
Following is the in-memory engine config strategy to be used in initializing UniCache.
96108
```js
97109
const configStrategy = {
98-
cache: {
99-
engine: "none",
100-
namespace: "A",
101-
defaultTtl: "36000",
102-
consistentBehavior: "1"
103-
}
110+
engine: "none",
111+
namespace: "A",
112+
defaultTtl: "36000",
113+
consistentBehavior: "1"
104114
}
105115
```
116+
- **engine**: For in-memory cache engine parameter will be `none`.
117+
- **namespace**: It is in-memory cache namespace.
118+
- **defaultTtl**: Default cache expiry time in sec.
119+
- **consistentBehavior**: This field is required to create cache instance key.
106120

107121
## `cacheImplementer` methods
108122
Irrespective of the caching engine, the methods exposed in `cacheImplementer` have the consistent signature.
@@ -161,32 +175,31 @@ cacheImplementer.set('testKey', "testData").then(console.log);
161175
cacheImplementer.touch('testKey', 10).then(resolvePromise);
162176
```
163177

164-
## Running test cases
165-
### Set environment variables of particular cache engine for which you want to run the tests.
166-
167-
* Redis
168-
```shell script
169-
source test/env/redis.sh
170-
```
171-
* Memcached
172-
```shell script
173-
source test/env/memcached.sh
174-
```
175-
* In-memory
176-
```shell script
177-
source test/env/inMemory.sh
178-
```
179-
### Cache engines must be running on the specified ports.
178+
## Test Cases
179+
Test cases cover all the 3 caching engines. Also a coverage report is generated at the end.
180180

181-
* Redis (6380,6381)
181+
### Step 1: Start Cache engines
182+
Following processes are needed for running test cases.
183+
* Start Redis on 2 ports - 6380 and 6381 as needed by the test cases.
182184
```shell script
183185
redis-server --port 6380
186+
redis-server --port 6381
184187
```
185-
* Memcached (11212,11213,11214,11215)
188+
* Start Memcached on 4 ports - 11212,11213,11214 and 11215 as needed by the test cases.
186189
```shell script
187190
memcached -p 11212 -d
191+
memcached -p 11213 -d
192+
memcached -p 11214 -d
193+
memcached -p 11215 -d
188194
```
189-
### Run tests
195+
196+
### Step 2: Run tests
197+
For running tests for all the 3 caching engines, use the following command.
190198
```shell script
191-
./node_modules/.bin/mocha --recursive "./test/*.js"
199+
npm run test
192200
```
201+
202+
## Contribution
203+
We welcome more helping hands to make UniCache better. Feel free to report issues, raise PRs for fixes & enhancements.
204+
205+
<p align="left">Built with :heart: by <a href="https://plgworks.com/" target="_blank">PLG Works</a></p>

‎VERSION‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
1.0.3
1+
1.0.0-beta.1

0 commit comments

Comments
 (0)