Basic TTL engine

.npmignore

@@ -4,6 +4,6 @@
 report
 tmp/
 .env
-dist
 .cache
-.github
+.github
+docs

.prettierrc

@@ -1,5 +1,5 @@
 {
-  "printWidth": 80,
+  "printWidth": 100,
   "tabWidth": 2,
   "useTabs": false,
   "semi": true,

README.md

@@ -34,6 +34,38 @@ const cache = createCache({
 }); 
 ```
 
+#### Engines and options
+
+| Engines Name        | key | supported options     |   |   |
+|---------------------|-----|-----------------------|---|---|
+| Least Recently Used | LRU | HashTable, size       |   |   |
+| Time To Live        | TTL | HashTable, defaultTTL |   |   |
+
+### Thing to know about TTL engine.
+
+Creating a ttl cache instance. [How it works and Architecture](./docs/ttl-engine.md)
+
+```javascript
+import { createCache } from 'node-cache-engine';
+
+const cache = createCache({
+  engine = 'TTL',
+  HashTable = YourCustomHashTable, // for custom hash Table. default hashTable is 'src/dataStructure/HashTable.js'
+  defaultTTL = 3600, // In milliseconds. defaultTTL is an optional property. This will use when ttl value is not passed on item add. 
+}); 
+
+const ttl = 5 * 60 * 1000; // (defined 5 minutes) ttl should be in milliseconds 
+
+cache.add('key', 'value', ttl); // add into cache. parameters key, value, ttl.
+cache.get('key'); // get from cache
+cache.has('key'); // checking from key is existing in cache
+cache.remove('key'); // removing from cache
+cache.size(); // get the size of cache
+cache.runGC(); // manual cleaning the expired item.
+
+```
+
+
 ### Creating Custom HashTable
 When and Why you should create custom hash table?  
 The default hash table implemented with `Map`. If you want much more performance than default you can implement your own (like node wrapped c++ hash table). I think 1 to 5 million cache entry default hash table is fine if your use case is more than this go for custom hash table.  
@@ -42,6 +74,5 @@ To implement custom hashTable you have to use methods with symbols name provided
 
 
 #### Next?
-* TTL engine.
-* TTL combining with LRU engine
+* TTL engine combining with LRU engine
 * LFU (Least frequently used) engine.

babel.config.js

@@ -9,5 +9,8 @@ module.exports = {
       },
     ],
   ],
-  plugins: [['@babel/plugin-proposal-optional-chaining']],
+  plugins: [
+    ['@babel/plugin-proposal-optional-chaining'],
+    ['@babel/plugin-transform-destructuring'],
+  ],
 };

docs/ttl-engine.md

@@ -0,0 +1,9 @@
+# TTL cache engine Architecture
+
+One of the challenges on ttl cache replacement is to clean the expired items. For smart cleaning, when we add new item it will time partitioned by ttl/expired value and put it into a time corresponded bucket.  
+Whenever a get method called it check the element exist and check it is expired or not. If it is expired then removes the item and clean previous buckets.  
+There is also a `runGC()` method in ttl cache. It will clean the buckets in between last cleaned time and now.  
+TTL engine do not run `runGC()` method automatically or in an interval.   
+We do not need to iterate or look all items for cleaning because of expired time partitioning. check below image for more information of architecture.
+
+![](./images/ttl-arct.png)

package.json

@@ -48,6 +48,7 @@
     "@babel/core": "^7.9.0",
     "@babel/node": "^7.8.7",
     "@babel/plugin-proposal-optional-chaining": "^7.9.0",
+    "@babel/plugin-transform-destructuring": "^7.10.1",
     "@babel/preset-env": "^7.9.0",
     "babel-eslint": "^10.1.0",
     "babel-jest": "^25.1.0",
@@ -57,6 +58,7 @@
     "jest": "^25.1.0",
     "lint-staged": "^10.0.8",
     "microbundle": "^0.12.0",
+    "mockdate": "^3.0.2",
     "pre-commit": "^1.2.2",
     "prettier": "^1.19.1"
   }

src/cache.js

@@ -1,18 +1,20 @@
 import DefaultHashTable from './dataStructure/HashTable';
 import LRU from './engines/LeastRecentlyUsed';
+import TTL from './engines/TimeToLive';
 
 function factory({
   size = Number.MAX_SAFE_INTEGER,
   engine = 'LRU',
   HashTable = DefaultHashTable,
+  defaultTTL,
 } = {}) {
   switch (engine) {
     case 'LRU':
       return new LRU({ size, HashTable });
+    case 'TTL':
+      return new TTL({ HashTable, defaultTTL });
     default:
-      throw Error(
-        `Engine : ${engine} is not implemented. Currently we have only 'LRU' engine.`,
-      );
+      throw Error(`Engine : ${engine} is not implemented. Engine options are 'LRU', 'TTL'`);
   }
 }
 

src/cache.test.js

@@ -1,5 +1,6 @@
 import createCache from './cache';
 import LRU from './engines/LeastRecentlyUsed';
+import TTL from './engines/TimeToLive';
 
 describe('cache factory', () => {
   it('should create a default cache instance of LRU if no engine is mentioned', () => {
@@ -12,6 +13,11 @@ describe('cache factory', () => {
     expect(cache1 instanceof LRU).toBe(true);
   });
 
+  it('should create ttl cache instance',()=>{
+    const cache1 = createCache({ engine: 'TTL' });
+    expect(cache1 instanceof TTL).toBe(true);
+  })
+
   it('should throw error if engine type is not implemented', () => {
     expect(() => createCache({ engine: 'NOT_HERE' })).toThrow(
       `Engine : NOT_HERE is not implemented`,

src/engines/TimeToLive.js

@@ -0,0 +1,149 @@
+import DefaultHashTable from '../dataStructure/HashTable';
+import DoublyLinkedList from '../dataStructure/DoublyLinkedList';
+import * as hashTableProp from '../hashTableSymbol';
+
+function TimeToLive({ HashTable = DefaultHashTable, defaultTTL } = {}) {
+  const store = new HashTable();
+  const timePartition = new HashTable();
+  const timeIndexInterval = 5 * 60 * 1000; // milliseconds.
+
+  let lowestTimePartition = Date.now();
+
+  this.add = (key, value, ttl = defaultTTL) => {
+    if (!ttl || !Number.isInteger(ttl) || ttl <= 0)
+      throw Error(
+        'Expected ttl value (should be positive integer). ' +
+          'you can have to mention it in add method or mention as defaultTTL at constructor',
+      );
+
+    const expireTTL = Date.now() + ttl;
+    const bucket = getTimeBucket(expireTTL);
+    bucket.addFirst(key);
+    const tNode = bucket.getFirstNode();
+    const payload = { value, ttl: expireTTL, tNode };
+    store[hashTableProp.add](key, payload);
+  };
+
+  this.get = key => {
+    const payload = store[hashTableProp.get](key);
+    if (payload) {
+      const { ttl, value } = payload;
+      if (checkIfElementExpire({ ttl, key })) return undefined;
+      else return value;
+    }
+    return undefined;
+  };
+
+  this.has = key => {
+    return (
+      store[hashTableProp.has](key) &&
+      !checkIfElementExpire({ ttl: store[hashTableProp.get](key), key })
+    );
+  };
+
+  this.remove = key => {
+    if (this.has(key)) {
+      const { ttl, tNode } = store[hashTableProp.get](key);
+      const timeBucket = getTimeBucket(ttl);
+      timeBucket.remove(tNode);
+      store[hashTableProp.remove](key);
+    }
+  };
+
+  this.size = () => {
+    return store[hashTableProp.size]();
+  };
+
+  this.runGC = () => {
+    const cleanTo = getBackwardTimeIndex({ time: Date.now(), interval: timeIndexInterval });
+    cleanExpiredBuckets(cleanTo);
+
+    const nextCleanBucket = getForwardTimeIndex({ time: Date.now(), interval: timeIndexInterval });
+    cleanNotExpiredBucket(nextCleanBucket);
+  };
+
+  function getTimeBucket(expireTTL) {
+    const timeIndex = getForwardTimeIndex({
+      time: expireTTL,
+      interval: timeIndexInterval,
+    });
+
+    if (timePartition[hashTableProp.has](timeIndex)) {
+      return timePartition[hashTableProp.get](timeIndex);
+    } else {
+      const list = new DoublyLinkedList();
+      timePartition[hashTableProp.add](timeIndex, list);
+      return list;
+    }
+  }
+
+  const checkIfElementExpire = ({ ttl, key }) => {
+    if (ttl < Date.now()) {
+      const timeIndex = getBackwardTimeIndex({
+        time: ttl,
+        interval: timeIndexInterval,
+      });
+      this.remove(key);
+      cleanExpiredBuckets(timeIndex);
+      return true;
+    }
+    return false;
+  };
+
+  function cleanExpiredBucket(timeIndex) {
+    if (timePartition[hashTableProp.has](timeIndex)) {
+      const tNodes = timePartition[hashTableProp.get](timeIndex);
+      for (const tNode of tNodes) {
+        store[hashTableProp.remove](tNode.value);
+      }
+      timePartition[hashTableProp.remove](timeIndex);
+    }
+  }
+
+  function cleanExpiredBuckets(tillTimeIndex) {
+    const cleanFrom = getForwardTimeIndex({
+      time: lowestTimePartition,
+      interval: timeIndexInterval,
+    });
+
+    for (const curTimeIndex of getIndexBetween({
+      from: cleanFrom,
+      to: tillTimeIndex,
+      interval: timeIndexInterval,
+    })) {
+      cleanExpiredBucket(curTimeIndex);
+    }
+    lowestTimePartition = tillTimeIndex;
+  }
+
+  function cleanNotExpiredBucket(timeIndex) {
+    if (timePartition[hashTableProp.has](timeIndex)) {
+      const tNodes = timePartition[hashTableProp.get](timeIndex);
+      for (const { value: key } of tNodes) {
+        const { ttl } = store[hashTableProp.get](key);
+        if (ttl < Date.now()) {
+          store[hashTableProp.remove](key);
+        }
+      }
+    }
+  }
+}
+
+// time : unix timestamp milliseconds
+// interval : milliseconds (better to be factors of 60  (minutes))
+function getForwardTimeIndex({ time, interval }) {
+  const timeParts = (time / interval) | 0;
+  return timeParts * interval + interval;
+}
+
+function getBackwardTimeIndex({ time, interval }) {
+  const timeParts = (time / interval) | 0;
+  return timeParts * interval;
+}
+
+function* getIndexBetween({ from, to, interval }) {
+  for (let i = from; i <= to; i += interval) yield i;
+}
+
+export { getForwardTimeIndex, getBackwardTimeIndex, getIndexBetween };
+export default TimeToLive;