Skip to content

Commit 2c43f00

Browse files
iprodeviprodev
committed
Initial commit
1 parent baada21 commit 2c43f00

16 files changed

Lines changed: 7571 additions & 0 deletions

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
node_modules
2+
npm-debug.log

‎Gruntfile.js‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
module.exports = function(grunt) {
2+
3+
grunt.initConfig({
4+
5+
jshint: {
6+
files: ["easycache.js", "./tests/tests.js"],
7+
},
8+
uglify: {
9+
dist: {
10+
src: ["easycache.js"],
11+
dest: "easycache.min.js"
12+
}
13+
},
14+
bump: {
15+
options: {
16+
files: ['package.json', 'bower.json'],
17+
commitMessage: 'Release %VERSION%',
18+
commitFiles: ['-a'],
19+
tagName: '%VERSION%',
20+
push: false
21+
}
22+
},
23+
browserify: {
24+
app: {
25+
src: ["./tests/tests.js"],
26+
dest: "./tests/tests-cjs.js",
27+
options: {
28+
shim: {
29+
qunit: {
30+
path: "./tests/qunit.js",
31+
exports: 'qunit'
32+
}
33+
}
34+
}
35+
}
36+
},
37+
qunit: {
38+
options: {
39+
timeout: 60 * 1000 * 2
40+
},
41+
all: ['tests/*.html']
42+
}
43+
});
44+
45+
grunt.loadNpmTasks("grunt-contrib-uglify");
46+
grunt.loadNpmTasks("grunt-contrib-jshint");
47+
grunt.loadNpmTasks('grunt-bump');
48+
grunt.loadNpmTasks('grunt-browserify');
49+
grunt.loadNpmTasks('grunt-contrib-qunit');
50+
51+
grunt.registerTask("default", ["jshint", "uglify", "browserify"]);
52+
grunt.registerTask("test", ["jshint", "uglify", "browserify", "qunit"]);
53+
54+
};

‎LICENSE.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
The MIT License (MIT)
2+
3+
Copyright (c) 2015 iProDev
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in
13+
all copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21+
THE SOFTWARE.

‎README.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
JS-EasyCache
2+
===============================
3+
This is a easy & fast library that emulates `memcache` functions using HTML5 `localStorage` with lossless data compression support, so that you can cache data on the client
4+
and associate an expiration time with each piece of data. If the `localStorage` limit (~5MB) is exceeded, it tries to create space by removing the items that are closest to expiring anyway. If `localStorage` is not available at all in the browser, the library degrades by simply not caching and all cache requests return null.
5+
6+
JS-EasyCache uses high-performance lossless data compression algorithm to make data stored size smaller so you can store more data to the `localStorage`.
7+
8+
Methods
9+
-------
10+
11+
The library exposes 9 methods: `set()`, `get()`, `remove()`, `flush()`, `flushExpired()`, `setBucket()`, `resetBucket()`, `supported()`, and `enableWarnings()`.
12+
13+
* * *
14+
15+
### EasyCache.set
16+
Stores the value in localStorage. Expires after specified number of minutes.
17+
#### Arguments
18+
1. `key` (**string**)
19+
2. `value` (**Object|string**)
20+
3. `time` (**number: optional**)
21+
22+
* * *
23+
24+
### EasyCache.get
25+
Retrieves specified value from localStorage, if not expired.
26+
#### Arguments
27+
1. `key` (**string**)
28+
29+
#### Returns
30+
**string | Object** : The stored value. If no value is available, null is returned.
31+
32+
* * *
33+
34+
### EasyCache.remove
35+
Removes a value from localStorage.
36+
#### Arguments
37+
1. `key` (**string**)
38+
39+
* * *
40+
41+
### EasyCache.flush
42+
Removes all EasyCache items from localStorage without affecting other data.
43+
44+
* * *
45+
46+
### EasyCache.setBucket
47+
Appends CACHE_PREFIX so EasyCache will partition data in to different buckets
48+
#### Arguments
49+
1. `bucket` (**string**)
50+
51+
Usage
52+
-------
53+
54+
The interface should be familiar to those of you who have used `memcache`, and should be easy to understand for those of you who haven't.
55+
56+
For example, you can store a string for 2 minutes using `EasyCache.set()`:
57+
58+
```js
59+
EasyCache.set('greeting', 'Hello World!', 2);
60+
```
61+
62+
You can then retrieve that string with `EasyCache.get()`:
63+
64+
```js
65+
alert(EasyCache.get('greeting'));
66+
```
67+
68+
You can remove that string from the cache entirely with `EasyCache.remove()`:
69+
70+
```js
71+
EasyCache.remove('greeting');
72+
```
73+
74+
You can remove all items from the cache entirely with `EasyCache.flush()`:
75+
76+
```js
77+
EasyCache.flush();
78+
```
79+
80+
You can remove only expired items from the cache entirely with `EasyCache.flushExpired()`:
81+
82+
```js
83+
EasyCache.flushExpired();
84+
```
85+
86+
Returns whether local storage is supported.:
87+
88+
```js
89+
alert(EasyCache.supported());
90+
```
91+
92+
The library also takes care of serializing objects, so you can store more complex data:
93+
94+
```js
95+
EasyCache.set('data', {'name': 'Hemn', 'age': 26}, 2);
96+
```
97+
98+
And then when you retrieve it, you will get it back as an object:
99+
100+
```js
101+
alert(EasyCache.get('data').name);
102+
```
103+
104+
If you have multiple instances of EasyCache running on the same domain, you can partition data in a certain bucket via:
105+
106+
```js
107+
EasyCache.set('response', '...', 2);
108+
EasyCache.setBucket('lib');
109+
EasyCache.set('path', '...', 2);
110+
EasyCache.flush(); // Only removes 'path' which was set in the lib bucket
111+
EasyCache.resetBucket();
112+
EasyCache.flush(); // Remove all EasyCache items and expiry markers without affecting rest of localStorage
113+
```
114+
115+
For more live examples, play around with the demo here:
116+
http://iprodev.github.io/JS-EasyCache/demo/index.html
117+
118+
119+
Real-World Usage
120+
----------
121+
This library was originally developed with the use case of caching results of JSON API queries
122+
to speed up my webapps and give them better protection against flaky APIs.
123+
124+
For example use `EasyCache` to fetch Youtube API results for 10 minutes:
125+
126+
```js
127+
var key = 'youtube:' + query;
128+
var json = EasyCache.get(key);
129+
if (json) {
130+
processJSON(json);
131+
} else {
132+
fetchJSON(query);
133+
}
134+
135+
function processJSON(json) {
136+
// ..
137+
}
138+
139+
function fetchJSON() {
140+
var searchUrl = 'http://gdata.youtube.com/feeds/api/videos';
141+
var params = {
142+
'v': '2', 'alt': 'jsonc', 'q': encodeURIComponent(query)
143+
}
144+
JSONP.get(searchUrl, params, null, function(json) {
145+
processJSON(json);
146+
EasyCache.set(key, json, 10);
147+
});
148+
}
149+
```
150+
151+
It does not have to be used for only expiration-based caching, however. It can also be used as just a wrapper for `localStorage`, as it provides the benefit of handling JS object (de-)serialization.
152+
153+
Browser Support
154+
----------------
155+
156+
The `EasyCache` library should work in all browsers where `localStorage` is supported.
157+
A list of those is here:
158+
http://caniuse.com/#search=localstorage
159+
160+
## Credits
161+
162+
JS-EasyCache was created by [Hemn Chawroka](http://iprodev.com) from [iProDev](http://iprodev.com). Released under the MIT license.

‎bower.json‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
"name": "EasyCache",
3+
"version": "1.0.0",
4+
"homepage": "https://github.com/iprodev/JS-EasyCache",
5+
"main": ["easycache.min.js", "easycache.js"],
6+
"ignore": [
7+
"demo",
8+
"tests",
9+
"Gruntfile.js",
10+
"package.json"
11+
],
12+
"keywords": [
13+
"localstorage",
14+
"local",
15+
"storage",
16+
"easycache"
17+
]
18+
}

‎demo/index.html‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<meta charset="utf-8">
5+
<title>JS-EasyCache</title>
6+
<style>
7+
body {
8+
font-family: Arial, sans-serif;
9+
}
10+
textarea {
11+
width: 400px;
12+
height: 80px;
13+
}
14+
</style>
15+
<script src="../easycache.js"></script>
16+
<script>
17+
function run(id) {
18+
if(console && console.time) console.time('EasyCache');
19+
var code = document.getElementById(id).value;
20+
eval(code);
21+
if(console && console.time) console.timeEnd('EasyCache');
22+
}
23+
</script>
24+
</head>
25+
26+
<body>
27+
28+
<h1>JS-EasyCache</h1>
29+
30+
<p>The JS-EasyCache library is a simple library that emulates memcache functions using HTML5 localStorage, so that you can store items with an expiration date. These demos show its current functionality - set, get, remove.</p>
31+
32+
<p><b>Set memcache entries (most with expiration of 2 minutes):</b>
33+
<br> (Check "Storage->Local Storage" in Chrome Dev Tools to see them stored.)</p>
34+
<textarea id="set">
35+
EasyCache.set('forever', 'And Ever');
36+
EasyCache.set('greeting', 'Hiii!', 2);
37+
EasyCache.set('counter', 1, 2);
38+
EasyCache.set('data', {'name': 'Hemn', 'age': 26}, 2);
39+
</textarea>
40+
<br>
41+
<button onclick="run('set')">Run</button>
42+
43+
<br>
44+
45+
<p><b>Retrieve EasyCache entries:</b>
46+
</p>
47+
<textarea id="get">
48+
console.log(EasyCache.get('forever'));
49+
console.log(EasyCache.get('greeting'));
50+
console.log(EasyCache.get('counter')+1);
51+
console.log(EasyCache.get('data').name);
52+
</textarea>
53+
<br>
54+
<button onclick="run('get')">Run</button>
55+
56+
<br>
57+
58+
<p><b>Delete EasyCache entries and try to retrieve them:</b>
59+
</p>
60+
<textarea id="delete">
61+
EasyCache.remove('forever');
62+
EasyCache.remove('greeting');
63+
EasyCache.remove('counter');
64+
EasyCache.remove('data');
65+
console.log(EasyCache.get('greeting'));
66+
</textarea>
67+
<br>
68+
<button onclick="run('delete')">Run</button>
69+
70+
<div id="result"></div>
71+
72+
<br>
73+
74+
</body>
75+
</html>

0 commit comments

Comments
 (0)