petty-cache 3.5.0 → 3.7.0

package/index.js

@@ -3,6 +3,11 @@ const lock = require('lock').Lock();
 const memoryCache = require('memory-cache');
 const redis = require('redis');
 
+/**
+ * Creates a new PettyCache instance backed by Redis.
+ * Accepts the same arguments as redis.createClient(), or an existing RedisClient instance.
+ * @param {...*} args - Either a RedisClient instance, or arguments forwarded to redis.createClient().
+ */
 function PettyCache() {
     const intervals = {};
     let redisClient;
@@ -16,18 +21,23 @@ function PettyCache() {
     //eslint-disable-next-line no-console
     redisClient.on('error', err => console.warn(`Warning: Redis reported a client error: ${err}`));
 
+    /**
+     * Fetches multiple keys from Redis.
+     * @param {string[]} keys
+     * @param {Function} callback - callback(err, values) where values maps each key to {exists, value}.
+     */
     function bulkGetFromRedis(keys, callback) {
         // Try to get values from Redis
-        redisClient.mget(keys, function(err, data) {
+        redisClient.mget(keys, (err, data) => {
             if (err) {
                 return callback(err);
             }
 
             const values = {};
 
-            for (var i = 0; i < keys.length; i++) {
-                var key = keys[i];
-                var value = data[i];
+            for (let i = 0; i < keys.length; i++) {
+                const key = keys[i];
+                const value = data[i];
 
                 if (value === null) {
                     values[key] = { exists: false };
@@ -41,6 +51,11 @@ function PettyCache() {
         });
     }
 
+    /**
+     * Fetches a single key from the in-process memory cache.
+     * @param {string} key
+     * @returns {{exists: boolean, value: *}}
+     */
     function getFromMemoryCache(key) {
         // Try to get value from memory cache
         const value = memoryCache.get(key);
@@ -59,9 +74,14 @@ function PettyCache() {
         return { exists: false };
     }
 
+    /**
+     * Fetches a single key from Redis.
+     * @param {string} key
+     * @param {Function} callback - callback(err, {exists, value}).
+     */
     function getFromRedis(key, callback) {
         // Try to get value from Redis
-        redisClient.get(key, function(err, data) {
+        redisClient.get(key, (err, data) => {
             if (err) {
                 return callback(err);
             }
@@ -75,6 +95,12 @@ function PettyCache() {
         });
     }
 
+    /**
+     * Resolves TTL options into a {min, max} object in milliseconds. Defaults to 30–60 seconds.
+     * @param {Object} options
+     * @param {number|Object} [options.ttl] - Fixed ms value, or an object with min/max properties.
+     * @returns {{min: number, max: number}}
+     */
     function getTtl(options) {
         // Default TTL is 30-60 seconds
         const ttl = {
@@ -101,163 +127,223 @@ function PettyCache() {
     }
 
     /**
-     * @param {Array} keys - An array of keys.
+     * Returns data from cache for each key if available; otherwise executes func for the missing keys
+     * and stores the results in cache before returning. Supports both callback and promise styles.
+     * @param {Array} keys - An array of cache keys.
+     * @param {Function} func - Function called with missing keys and a callback: (keys, callback).
+     * @param {Object} [options] - Optional settings.
+     * @param {number|Object} [options.ttl] - TTL in ms, or object with min/max properties.
+     * @param {Function} [callback] - Optional callback(err, values). If omitted, returns a Promise.
+     * @returns {Promise|undefined} Resolves with an object mapping each key to its cached value.
      */
-    this.bulkFetch = function(keys, func, options, callback) {
-        // Options are optional
-        if (!callback) {
+    this.bulkFetch = (keys, func, options = {}, callback) => {
+        if (typeof options === 'function') {
             callback = options;
             options = {};
         }
 
-        // If there aren't any keys, return
-        if (!keys.length) {
-            return callback(null, {});
-        }
+        const executor = () => {
+            return new Promise((resolve, reject) => {
+                // If there aren't any keys, return
+                if (!keys.length) {
+                    return resolve({});
+                }
 
-        const _keys = Array.from(new Set(keys));
-        const values = {};
+                const _keys = Array.from(new Set(keys));
+                const values = {};
 
-        // Try to get values from memory cache
-        for (var i = _keys.length - 1; i >= 0; i--) {
-            const key = _keys[i];
-            const result = getFromMemoryCache(key);
+                // Try to get values from memory cache
+                for (let i = _keys.length - 1; i >= 0; i--) {
+                    const key = _keys[i];
+                    const result = getFromMemoryCache(key);
 
-            if (result.exists) {
-                values[key] = result.value;
-                _keys.splice(i, 1);
-            }
-        }
+                    if (result.exists) {
+                        values[key] = result.value;
+                        _keys.splice(i, 1);
+                    }
+                }
 
-        // If there aren't any keys left, return
-        if (!_keys.length) {
-            return callback(null, values);
-        }
+                // If there aren't any keys left, return
+                if (!_keys.length) {
+                    return resolve(values);
+                }
 
-        const _this = this;
+                // Try to get values from Redis
+                bulkGetFromRedis(_keys, (err, results) => {
+                    if (err) {
+                        return reject(err);
+                    }
 
-        // Try to get values from Redis
-        bulkGetFromRedis(_keys, function(err, results) {
-            if (err) {
-                return callback(err);
-            }
+                    for (let i = _keys.length - 1; i >= 0; i--) {
+                        const key = _keys[i];
+                        const result = results[key];
 
-            for (var i = _keys.length - 1; i >= 0; i--) {
-                const key = _keys[i];
-                const result = results[key];
+                        if (result.exists) {
+                            _keys.splice(i, 1);
+                            values[key] = result.value;
 
-                if (result.exists) {
-                    _keys.splice(i, 1);
-                    values[key] = result.value;
+                            // Store value in memory cache with a short expiration
+                            memoryCache.put(key, result.value, random(2000, 5000));
+                        }
+                    }
 
-                    // Store value in memory cache with a short expiration
-                    memoryCache.put(key, result.value, random(2000, 5000));
-                }
-            }
+                    // If there aren't any keys left, return
+                    if (!_keys.length) {
+                        return resolve(values);
+                    }
 
-            // If there aren't any keys left, return
-            if (!_keys.length) {
-                return callback(null, values);
-            }
+                    // Execute the specified function for remaining keys
+                    func(_keys, (err, data) => {
+                        if (err) {
+                            return reject(err);
+                        }
 
-            // Execute the specified function for remaining keys
-            func(_keys, function(err, data) {
-                if (err) {
-                    return callback(err);
-                }
+                        Object.keys(data).forEach(key => values[key] = data[key]);
 
-                Object.keys(data).forEach(key => values[key] = data[key]);
+                        this.bulkSet(data, options, err => {
+                            if (err) {
+                                return reject(err);
+                            }
 
-                _this.bulkSet(data, options, err => callback(err, values));
+                            resolve(values);
+                        });
+                    });
+                });
             });
-        });
+        };
+
+        if (callback) {
+            executor().then(result => callback(null, result)).catch(callback);
+        } else {
+            return executor();
+        }
     };
 
     /**
-     * @param {Array} keys - An array of keys.
+     * Gets cached values for an array of keys. Supports both callback and promise styles.
+     * @param {Array} keys - An array of cache keys.
+     * @param {Function} [callback] - Optional callback(err, values). If omitted, returns a Promise.
+     * @returns {Promise|undefined} Resolves with an object mapping each key to its value, or null if not found.
      */
-    this.bulkGet = function(keys, callback) {
-        // If there aren't any keys, return
-        if (!keys.length) {
-            return callback(null, {});
-        }
+    this.bulkGet = (keys, callback) => {
+        const executor = () => {
+            return new Promise((resolve, reject) => {
+                // If there aren't any keys, return
+                if (!keys.length) {
+                    return resolve({});
+                }
 
-        const _keys = Array.from(new Set(keys));
-        const values = {};
+                const _keys = Array.from(new Set(keys));
+                const values = {};
 
-        // Try to get values from memory cache
-        for (var i = _keys.length - 1; i >= 0; i--) {
-            const key = _keys[i];
-            const result = getFromMemoryCache(key);
+                // Try to get values from memory cache
+                for (let i = _keys.length - 1; i >= 0; i--) {
+                    const key = _keys[i];
+                    const result = getFromMemoryCache(key);
 
-            if (result.exists) {
-                values[key] = result.value;
-                _keys.splice(i, 1);
-            }
-        }
+                    if (result.exists) {
+                        values[key] = result.value;
+                        _keys.splice(i, 1);
+                    }
+                }
 
-        // If there aren't any keys left, return
-        if (!_keys.length) {
-            return callback(null, values);
-        }
+                // If there aren't any keys left, return
+                if (!_keys.length) {
+                    return resolve(values);
+                }
 
-        // Try to get values from Redis
-        bulkGetFromRedis(_keys, function(err, results) {
-            if (err) {
-                return callback(err);
-            }
+                // Try to get values from Redis
+                bulkGetFromRedis(_keys, (err, results) => {
+                    if (err) {
+                        return reject(err);
+                    }
 
-            for (var i = 0; i < _keys.length; i++) {
-                var key = _keys[i];
-                var result = results[key];
+                    for (let i = 0; i < _keys.length; i++) {
+                        const key = _keys[i];
+                        const result = results[key];
 
-                if (!result.exists) {
-                    values[key] = null;
-                    continue;
-                }
+                        if (!result.exists) {
+                            values[key] = null;
+                            continue;
+                        }
 
-                values[key] = result.value;
+                        values[key] = result.value;
 
-                // Store value in memory cache with a short expiration
-                memoryCache.put(key, result.value, random(2000, 5000));
-            }
+                        // Store value in memory cache with a short expiration
+                        memoryCache.put(key, result.value, random(2000, 5000));
+                    }
 
-            callback(null, values);
-        });
+                    resolve(values);
+                });
+            });
+        };
+
+        if (callback) {
+            executor().then(result => callback(null, result)).catch(callback);
+        } else {
+            return executor();
+        }
     };
 
-    this.bulkSet = function(values, options, callback) {
-        // Options are optional
-        if (!callback) {
+    /**
+     * Sets multiple key/value pairs in cache simultaneously. Supports both callback and promise styles.
+     * @param {Object} values - An object mapping cache keys to their values.
+     * @param {Object} [options] - Optional settings.
+     * @param {number|Object} [options.ttl] - TTL in ms, or object with min/max properties.
+     * @param {Function} [callback] - Optional callback(err). If omitted, returns a Promise.
+     * @returns {Promise|undefined}
+     */
+    this.bulkSet = (values, options = {}, callback) => {
+        if (typeof options === 'function') {
             callback = options;
             options = {};
         }
 
-        // Get TTL based on specified options
-        const ttl = getTtl(options);
+        const executor = () => {
+            return new Promise((resolve, reject) => {
+                // Get TTL based on specified options
+                const ttl = getTtl(options);
 
-        // Redis does not have a MSETEX command so we batch commands: http://redis.js.org/#api-clientbatchcommands
-        const batch = redisClient.batch();
+                // Redis does not have a MSETEX command so we batch commands: http://redis.js.org/#api-clientbatchcommands
+                const batch = redisClient.batch();
 
-        Object.keys(values).forEach(key => {
-            const value = values[key];
+                Object.keys(values).forEach(key => {
+                    const value = values[key];
 
-            // Store value in memory cache with a short expiration
-            memoryCache.put(key, value, random(2000, 5000));
+                    // Store value in memory cache with a short expiration
+                    memoryCache.put(key, value, random(2000, 5000));
 
-            // Add Redis command
-            batch.psetex(key, random(ttl.min, ttl.max), PettyCache.stringify(value));
-        });
+                    // Add Redis command
+                    batch.psetex(key, random(ttl.min, ttl.max), PettyCache.stringify(value));
+                });
 
-        batch.exec(function(err) {
-            callback(err);
-        });
+                batch.exec((err) => {
+                    if (err) {
+                        return reject(err);
+                    }
+
+                    resolve();
+                });
+            });
+        };
+
+        if (callback) {
+            executor().then(result => callback(null, result)).catch(callback);
+        } else {
+            return executor();
+        }
     };
 
-    this.del = function(key, callback) {
+    /**
+     * Deletes a key from both the memory cache and Redis. Supports both callback and promise styles.
+     * @param {string} key - The cache key to delete.
+     * @param {Function} [callback] - Optional callback(err). If omitted, returns a Promise.
+     * @returns {Promise|undefined}
+     */
+    this.del = (key, callback) => {
         const executor = () => {
             return new Promise((resolve, reject) => {
-                redisClient.del(key, function(err) {
+                redisClient.del(key, (err) => {
                     if (err) {
                         return reject(err);
                     }
@@ -275,21 +361,26 @@ function PettyCache() {
         }
     };
 
-    // Returns data from cache if available;
-    // otherwise executes the specified function and places the results in cache before returning the data.
-    this.fetch = function(key, func, options, callback) {
-        options = options || {};
-
+    /**
+     * Returns data from cache if available; otherwise executes func, stores the result, and returns it.
+     * Uses double-checked locking to prevent cache stampedes. Supports async and callback func signatures.
+     * @param {string} key - The cache key.
+     * @param {Function} func - Called on cache miss. Use func(callback) for callbacks or async func() for promises.
+     * @param {Object} [options] - Optional settings.
+     * @param {number|Object} [options.ttl] - TTL in ms, or object with min/max properties.
+     * @param {Function} [callback] - Optional callback(err, value). Defaults to a noop.
+     */
+    this.fetch = (key, func, options = {}, callback) => {
         if (typeof options === 'function') {
             callback = options;
             options = {};
         }
 
         // Default callback is a noop
-        callback = callback || function() {};
+        callback = callback || (() => {});
 
         // Try to get value from memory cache
-        var result = getFromMemoryCache(key);
+        let result = getFromMemoryCache(key);
 
         // Return value from memory cache if it exists
         if (result.exists) {
@@ -299,8 +390,8 @@ function PettyCache() {
         const _this = this;
 
         // Double-checked locking: http://en.wikipedia.org/wiki/Double-checked_locking
-        lock(`fetch-memory-cache-lock-${key}`, function(releaseMemoryCacheLock) {
-            async.reflect(function(callback) {
+        lock(`fetch-memory-cache-lock-${key}`, (releaseMemoryCacheLock) => {
+            async.reflect((callback) => {
                 // Try to get value from memory cache
                 result = getFromMemoryCache(key);
 
@@ -310,7 +401,7 @@ function PettyCache() {
                 }
 
                 // Try to get value from Redis
-                getFromRedis(key, function(err, result) {
+                getFromRedis(key, (err, result) => {
                     if (err) {
                         return callback(err);
                     }
@@ -322,8 +413,8 @@ function PettyCache() {
                     }
 
                     // Double-checked locking: http://en.wikipedia.org/wiki/Double-checked_locking
-                    lock(`fetch-redis-lock-${key}`, function(releaseRedisLock) {
-                        async.reflect(function(callback) {
+                    lock(`fetch-redis-lock-${key}`, (releaseRedisLock) => {
+                        async.reflect((callback) => {
                             // Try to get value from memory cache
                             result = getFromMemoryCache(key);
 
@@ -333,7 +424,7 @@ function PettyCache() {
                             }
 
                             // Try to get value from Redis
-                            getFromRedis(key, async function(err, result) {
+                            getFromRedis(key, async (err, result) => {
                                 if (err) {
                                     return callback(err);
                                 }
@@ -350,7 +441,7 @@ function PettyCache() {
                                     try {
                                         const data = await func();
 
-                                        _this.set(key, data, options, function(err) {
+                                        _this.set(key, data, options, (err) => {
                                             callback(err, data);
                                         });
                                     } catch(err) {
@@ -358,18 +449,18 @@ function PettyCache() {
                                     }
                                 } else {
                                     // If the function has arguments, there was a callback provided
-                                    func(function(err, data) {
+                                    func((err, data) => {
                                         if (err) {
                                             return callback(err);
                                         }
 
-                                        _this.set(key, data, options, function(err) {
+                                        _this.set(key, data, options, (err) => {
                                             callback(err, data);
                                         });
                                     });
                                 }
                             });
-                        })(releaseRedisLock(function(err, result) {
+                        })(releaseRedisLock((err, result) => {
                             if (result.error) {
                                 return callback(result.error);
                             }
@@ -378,7 +469,7 @@ function PettyCache() {
                         }));
                     });
                 });
-            })(releaseMemoryCacheLock(function(err, result) {
+            })(releaseMemoryCacheLock((err, result) => {
                 if (result.error) {
                     return callback(result.error);
                 }
@@ -388,9 +479,16 @@ function PettyCache() {
         });
     };
 
-    this.fetchAndRefresh = function(key, func, options, callback) {
-        options = options || {};
-
+    /**
+     * Like fetch(), but also sets up a background interval to proactively refresh the cached value
+     * before it expires, preventing cache misses under sustained load.
+     * @param {string} key - The cache key.
+     * @param {Function} func - Called on cache miss and on each refresh interval: func(callback).
+     * @param {Object} [options] - Optional settings.
+     * @param {number|Object} [options.ttl] - TTL in ms, or object with min/max properties.
+     * @param {Function} [callback] - Optional callback(err, value). Defaults to a noop.
+     */
+    this.fetchAndRefresh = (key, func, options = {}, callback) => {
         if (typeof options === 'function') {
             callback = options;
             options = {};
@@ -400,22 +498,22 @@ function PettyCache() {
         const ttl = getTtl(options);
 
         // Default callback is a noop
-        callback = callback || function() {};
+        callback = callback || (() => {});
 
         const _this = this;
 
         if (!intervals[key]) {
             const delay = ttl.min / 2;
 
-            intervals[key] = setInterval(function() {
+            intervals[key] = setInterval(() => {
                 // This distributed lock prevents multiple clients from executing func at the same time
-                _this.mutex.lock(`interval-${key}`, { ttl: delay - 100 }, function(err) {
+                _this.mutex.lock(`interval-${key}`, { ttl: delay - 100 }, (err) => {
                     if (err) {
                         return;
                     }
 
                     // Execute the specified function and update cache
-                    func(function(err, data) {
+                    func((err, data) => {
                         if (err) {
                             return;
                         }
@@ -429,58 +527,83 @@ function PettyCache() {
         this.fetch(key, func, options, callback);
     };
 
-    this.get = function(key, callback) {
-        // Try to get value from memory cache
-        let result = getFromMemoryCache(key);
-
-        // Return value from memory cache if it exists
-        if (result.exists) {
-            return callback(null, result.value);
-        }
-
-        // Double-checked locking: http://en.wikipedia.org/wiki/Double-checked_locking
-        lock(`get-memory-cache-lock-${key}`, function(releaseMemoryCacheLock) {
-            async.reflect(function(callback) {
+    /**
+     * Gets a cached value. Supports both callback and promise styles.
+     * @param {string} key - The cache key.
+     * @param {Function} [callback] - Optional callback(err, value). If omitted, returns a Promise.
+     * @returns {Promise|undefined} Resolves with the cached value, or null if not found.
+     */
+    this.get = (key, callback) => {
+        const executor = () => {
+            return new Promise((resolve, reject) => {
                 // Try to get value from memory cache
-                result = getFromMemoryCache(key);
+                let result = getFromMemoryCache(key);
 
                 // Return value from memory cache if it exists
                 if (result.exists) {
-                    return callback(null, result.value);
+                    return resolve(result.value);
                 }
 
-                getFromRedis(key, function(err, result) {
-                    if (err) {
-                        return callback(err);
-                    }
+                // Double-checked locking: http://en.wikipedia.org/wiki/Double-checked_locking
+                lock(`get-memory-cache-lock-${key}`, (releaseMemoryCacheLock) => {
+                    async.reflect((callback) => {
+                        // Try to get value from memory cache
+                        result = getFromMemoryCache(key);
 
-                    if (!result.exists) {
-                        return callback(null, null);
-                    }
+                        // Return value from memory cache if it exists
+                        if (result.exists) {
+                            return callback(null, result.value);
+                        }
+
+                        getFromRedis(key, (err, result) => {
+                            if (err) {
+                                return callback(err);
+                            }
 
-                    memoryCache.put(key, result.value, random(2000, 5000));
-                    callback(null, result.value);
+                            if (!result.exists) {
+                                return callback(null, null);
+                            }
+
+                            memoryCache.put(key, result.value, random(2000, 5000));
+                            callback(null, result.value);
+                        });
+                    })(releaseMemoryCacheLock((err, result) => {
+                        if (result.error) {
+                            return reject(result.error);
+                        }
+
+                        resolve(result.value);
+                    }));
                 });
-            })(releaseMemoryCacheLock(function(err, result) {
-                if (result.error) {
-                    return callback(result.error);
-                }
+            });
+        };
 
-                callback(null, result.value);
-            }));
-        });
+        if (callback) {
+            executor().then(result => callback(null, result)).catch(callback);
+        } else {
+            return executor();
+        }
     };
 
     this.mutex = {
-        lock: (key, options, callback) => {
+        /**
+         * Acquires a distributed mutex lock in Redis. Supports both callback and promise styles.
+         * @param {string} key - The lock key.
+         * @param {Object} [options] - Optional settings.
+         * @param {number} [options.ttl=1000] - Lock TTL in ms.
+         * @param {Object} [options.retry] - Retry options.
+         * @param {number} [options.retry.times=1] - Number of acquisition attempts.
+         * @param {number} [options.retry.interval=100] - Delay between retries in ms.
+         * @param {Function} [callback] - Optional callback(err). If omitted, returns a Promise.
+         * @returns {Promise|undefined}
+         */
+        lock: (key, options = {}, callback) => {
             // Options are optional
             if (!callback && typeof options === 'function') {
                 callback = options;
                 options = {};
             }
 
-            options = options || {};
-
             options.retry = Object.hasOwn(options, 'retry') ? options.retry : {};
             options.retry.interval = Object.hasOwn(options.retry, 'interval') ? options.retry.interval : 100;
             options.retry.times = Object.hasOwn(options.retry, 'times') ? options.retry.times : 1;
@@ -489,7 +612,7 @@ function PettyCache() {
             const executor = () => {
                 return new Promise((resolve, reject) => {
                     async.retry({ interval: options.retry.interval, times: options.retry.times }, callback => {
-                        redisClient.set(key, '1', 'NX', 'PX', options.ttl, function(err, res) {
+                        redisClient.set(key, '1', 'NX', 'PX', options.ttl, (err, res) => {
                             if (err) {
                                 return callback(err);
                             }
@@ -504,7 +627,7 @@ function PettyCache() {
 
                             callback();
                         });
-                    }, function(err) {
+                    }, (err) => {
                         if (err) {
                             return reject(err);
                         }
@@ -520,10 +643,16 @@ function PettyCache() {
                 return executor();
             }
         },
+        /**
+         * Releases a distributed mutex lock in Redis. Supports both callback and promise styles.
+         * @param {string} key - The lock key to release.
+         * @param {Function} [callback] - Optional callback(err). If omitted, returns a Promise.
+         * @returns {Promise|undefined}
+         */
         unlock: (key, callback) => {
             const executor = () => {
                 return new Promise((resolve, reject) => {
-                    redisClient.del(key, function(err) {
+                    redisClient.del(key, (err) => {
                         if (err) {
                             return reject(err);
                         }
@@ -541,41 +670,75 @@ function PettyCache() {
         }
     };
 
-    this.patch = function(key, value, options, callback) {
-        if (!callback) {
+    /**
+     * Updates specific properties of a cached object without replacing the whole value.
+     * Supports both callback and promise styles.
+     * @param {string} key - The cache key of the object to patch.
+     * @param {Object} value - Properties to merge into the cached object.
+     * @param {Object} [options] - Optional settings passed to set().
+     * @param {number|Object} [options.ttl] - TTL in ms, or object with min/max properties.
+     * @param {Function} [callback] - Optional callback(err). If omitted, returns a Promise.
+     * @returns {Promise|undefined}
+     */
+    this.patch = (key, value, options = {}, callback) => {
+        if (!callback && typeof options === 'function') {
             callback = options;
             options = {};
         }
 
         const _this = this;
 
-        this.get(key, function(err, data) {
-            if (err) {
-                return callback(err);
-            }
+        const executor = () => {
+            return new Promise((resolve, reject) => {
+                _this.get(key, (err, data) => {
+                    if (err) {
+                        return reject(err);
+                    }
 
-            if (!data) {
-                return callback(new Error(`Key ${key} does not exist`));
-            }
+                    if (!data) {
+                        return reject(new Error(`Key ${key} does not exist`));
+                    }
 
-            for (var k in value) {
-                data[k] = value[k];
-            }
+                    for (let k in value) {
+                        data[k] = value[k];
+                    }
 
-            _this.set(key, data, options, callback);
-        });
+                    _this.set(key, data, options, (err) => {
+                        if (err) {
+                            return reject(err);
+                        }
+
+                        resolve();
+                    });
+                });
+            });
+        };
+
+        if (callback) {
+            executor().then(result => callback(null, result)).catch(callback);
+        } else {
+            return executor();
+        }
     };
 
     this.semaphore = {
-        acquireLock: function(key, options, callback) {
+        /**
+         * Acquires a slot in an existing semaphore pool. Retries if no slot is currently available.
+         * @param {string} key - The semaphore key.
+         * @param {Object} [options] - Optional settings.
+         * @param {number} [options.ttl=1000] - Slot TTL in ms; expired slots may be reclaimed.
+         * @param {Object} [options.retry] - Retry options.
+         * @param {number} [options.retry.times=1] - Number of acquisition attempts.
+         * @param {number} [options.retry.interval=100] - Delay between retries in ms.
+         * @param {Function} callback - callback(err, index) where index is the acquired slot number.
+         */
+        acquireLock: (key, options = {}, callback) => {
             // Options are optional
             if (!callback && typeof options === 'function') {
                 callback = options;
                 options = {};
             }
 
-            options = options || {};
-
             options.retry = Object.prototype.hasOwnProperty.call(options, 'retry') ? options.retry : {};
             options.retry.interval = Object.prototype.hasOwnProperty.call(options.retry, 'interval') ? options.retry.interval : 100;
             options.retry.times = Object.prototype.hasOwnProperty.call(options.retry, 'times') ? options.retry.times : 1;
@@ -583,14 +746,14 @@ function PettyCache() {
 
             const _this = this;
 
-            async.retry({ interval: options.retry.interval, times: options.retry.times }, function(callback) {
+            async.retry({ interval: options.retry.interval, times: options.retry.times }, (callback) => {
                 // Mutex lock around semaphore
-                _this.mutex.lock(`lock:${key}`, { retry: { times: 100 } }, function(err) {
+                _this.mutex.lock(`lock:${key}`, { retry: { times: 100 } }, (err) => {
                     if (err) {
                         return callback(err);
                     }
 
-                    redisClient.get(key, function(err, data) {
+                    redisClient.get(key, (err, data) => {
                         // If we encountered an error, unlock the mutex lock and return error
                         if (err) {
                             return _this.mutex.unlock(`lock:${key}`, () => { callback(err); });
@@ -601,10 +764,10 @@ function PettyCache() {
                             return _this.mutex.unlock(`lock:${key}`, () => { callback(new Error(`Semaphore ${key} doesn't exist.`)); });
                         }
 
-                        var pool = JSON.parse(data);
+                        const pool = JSON.parse(data);
 
                         // Try to find a slot that's available.
-                        var index = pool.findIndex(s => s.status === 'available');
+                        let index = pool.findIndex(s => s.status === 'available');
 
                         if (index === -1) {
                             index = pool.findIndex(s => s.ttl <= Date.now());
@@ -617,7 +780,7 @@ function PettyCache() {
 
                         pool[index] = { status: 'acquired', ttl: Date.now() + options.ttl };
 
-                        redisClient.set(key, JSON.stringify(pool), function(err) {
+                        redisClient.set(key, JSON.stringify(pool), (err) => {
                             if (err) {
                                 return _this.mutex.unlock(`lock:${key}`, () => { callback(err); });
                             }
@@ -628,18 +791,25 @@ function PettyCache() {
                 });
             }, callback);
         },
-        consumeLock: function(key, index, callback) {
-            callback = callback || function() {};
+        /**
+         * Permanently consumes a semaphore slot, marking it consumed rather than available.
+         * Ensures at least one slot always remains non-consumed.
+         * @param {string} key - The semaphore key.
+         * @param {number} index - The slot index to consume.
+         * @param {Function} [callback] - Optional callback(err). Defaults to a noop.
+         */
+        consumeLock: (key, index, callback) => {
+            callback = callback || (() => {});
 
             const _this = this;
 
             // Mutex lock around semaphore
-            _this.mutex.lock(`lock:${key}`, { retry: { times: 100 } }, function(err) {
+            _this.mutex.lock(`lock:${key}`, { retry: { times: 100 } }, (err) => {
                 if (err) {
                     return callback(err);
                 }
 
-                redisClient.get(key, function(err, data) {
+                redisClient.get(key, (err, data) => {
                     // If we encountered an error, unlock the mutex lock and return error
                     if (err) {
                         return _this.mutex.unlock(`lock:${key}`, () => { callback(err); });
@@ -650,7 +820,7 @@ function PettyCache() {
                         return _this.mutex.unlock(`lock:${key}`, () => { callback(new Error(`Semaphore ${key} doesn't exist.`)); });
                     }
 
-                    var pool = JSON.parse(data);
+                    const pool = JSON.parse(data);
 
                     // Ensure index exists.
                     if (pool.length <= index) {
@@ -664,7 +834,7 @@ function PettyCache() {
                         pool[index] = { status: 'available' };
                     }
 
-                    redisClient.set(key, JSON.stringify(pool), function(err) {
+                    redisClient.set(key, JSON.stringify(pool), (err) => {
                         if (err) {
                             return _this.mutex.unlock(`lock:${key}`, () => { callback(err); });
                         }
@@ -674,17 +844,23 @@ function PettyCache() {
                 });
             });
         },
-        expand: function(key, size, callback) {
-            callback = callback || function() {};
+        /**
+         * Increases the size of an existing semaphore pool. Cannot shrink a pool.
+         * @param {string} key - The semaphore key.
+         * @param {number} size - The desired pool size (must be >= current size).
+         * @param {Function} [callback] - Optional callback(err). Defaults to a noop.
+         */
+        expand: (key, size, callback) => {
+            callback = callback || (() => {});
 
             const _this = this;
 
-            _this.mutex.lock(`lock:${key}`, { retry: { times: 100 } }, function(err) {
+            _this.mutex.lock(`lock:${key}`, { retry: { times: 100 } }, (err) => {
                 if (err) {
                     return callback(err);
                 }
 
-                redisClient.get(key, function(err, data) {
+                redisClient.get(key, (err, data) => {
                     // If we encountered an error, unlock the mutex lock and return error
                     if (err) {
                         return _this.mutex.unlock(`lock:${key}`, () => { callback(err); });
@@ -695,7 +871,7 @@ function PettyCache() {
                         return _this.mutex.unlock(`lock:${key}`, () => { callback(new Error(`Semaphore ${key} doesn't exist.`)); });
                     }
 
-                    var pool = JSON.parse(data);
+                    let pool = JSON.parse(data);
 
                     if (pool.length > size) {
                         return _this.mutex.unlock(`lock:${key}`, () => { callback(new Error(`Cannot shrink pool, size is ${pool.length} and you requested a size of ${size}.`)); });
@@ -707,7 +883,7 @@ function PettyCache() {
 
                     pool = pool.concat(Array(size - pool.length).fill({ status: 'available' }));
 
-                    redisClient.set(key, JSON.stringify(pool), function(err) {
+                    redisClient.set(key, JSON.stringify(pool), (err) => {
                         if (err) {
                             return _this.mutex.unlock(`lock:${key}`, () => { callback(err); });
                         }
@@ -717,18 +893,24 @@ function PettyCache() {
                 });
             });
         },
-        releaseLock: function(key, index, callback) {
-            callback = callback || function() {};
+        /**
+         * Releases an acquired semaphore slot, marking it available again.
+         * @param {string} key - The semaphore key.
+         * @param {number} index - The slot index to release.
+         * @param {Function} [callback] - Optional callback(err). Defaults to a noop.
+         */
+        releaseLock: (key, index, callback) => {
+            callback = callback || (() => {});
 
             const _this = this;
 
             // Mutex lock around semaphore
-            _this.mutex.lock(`lock:${key}`, { retry: { times: 100 } }, function(err) {
+            _this.mutex.lock(`lock:${key}`, { retry: { times: 100 } }, (err) => {
                 if (err) {
                     return callback(err);
                 }
 
-                redisClient.get(key, function(err, data) {
+                redisClient.get(key, (err, data) => {
                     // If we encountered an error, unlock the mutex lock and return error
                     if (err) {
                         return _this.mutex.unlock(`lock:${key}`, () => { callback(err); });
@@ -739,7 +921,7 @@ function PettyCache() {
                         return _this.mutex.unlock(`lock:${key}`, () => { callback(new Error(`Semaphore ${key} doesn't exist.`)); });
                     }
 
-                    var pool = JSON.parse(data);
+                    const pool = JSON.parse(data);
 
                     // Ensure index exists.
                     if (pool.length <= index) {
@@ -748,7 +930,7 @@ function PettyCache() {
 
                     pool[index] = { status: 'available' };
 
-                    redisClient.set(key, JSON.stringify(pool), function(err) {
+                    redisClient.set(key, JSON.stringify(pool), (err) => {
                         if (err) {
                             return _this.mutex.unlock(`lock:${key}`, () => { callback(err); });
                         }
@@ -758,19 +940,24 @@ function PettyCache() {
                 });
             });
         },
-        reset: function(key, callback) {
-            callback = callback || function() {};
+        /**
+         * Resets all slots in an existing semaphore pool to available.
+         * @param {string} key - The semaphore key.
+         * @param {Function} [callback] - Optional callback(err, pool). Defaults to a noop.
+         */
+        reset: (key, callback) => {
+            callback = callback || (() => {});
 
             const _this = this;
 
             // Mutex lock around semaphore
-            this.mutex.lock(`lock:${key}`, { retry: { times: 100 } }, function(err) {
+            this.mutex.lock(`lock:${key}`, { retry: { times: 100 } }, (err) => {
                 if (err) {
                     return callback(err);
                 }
 
                 // Try to get previously created semaphore
-                redisClient.get(key, function(err, data) {
+                redisClient.get(key, (err, data) => {
                     // If we encountered an error, unlock the mutex lock and return error
                     if (err) {
                         return _this.mutex.unlock(`lock:${key}`, () => { callback(err); });
@@ -781,10 +968,10 @@ function PettyCache() {
                         return _this.mutex.unlock(`lock:${key}`, () => { callback(new Error(`Semaphore ${key} doesn't exist.`)); });
                     }
 
-                    var pool = JSON.parse(data);
+                    let pool = JSON.parse(data);
                     pool = Array(pool.length).fill({ status: 'available' });
 
-                    redisClient.set(key, JSON.stringify(pool), function(err) {
+                    redisClient.set(key, JSON.stringify(pool), (err) => {
                         if (err) {
                             return _this.mutex.unlock(`lock:${key}`, () => { callback(err); });
                         }
@@ -794,26 +981,32 @@ function PettyCache() {
                 });
             });
         },
-        retrieveOrCreate: function(key, options, callback) {
+        /**
+         * Retrieves an existing semaphore pool, or creates one if it doesn't exist.
+         * @param {string} key - The semaphore key.
+         * @param {Object} [options] - Optional settings.
+         * @param {number|Function} [options.size=1] - Pool size, or a function(callback) that resolves the size.
+         * @param {Function} [callback] - Optional callback(err, pool). Defaults to a noop.
+         */
+        retrieveOrCreate: (key, options = {}, callback) => {
             // Options are optional
             if (!callback && typeof options === 'function') {
                 callback = options;
                 options = {};
             }
 
-            callback = callback || function() {};
-            options = options || {};
+            callback = callback || (() => {});
 
             const _this = this;
 
             // Mutex lock around semaphore retrival or creation
-            this.mutex.lock(`lock:${key}`, { retry: { times: 100 } }, function(err) {
+            this.mutex.lock(`lock:${key}`, { retry: { times: 100 } }, (err) => {
                 if (err) {
                     return callback(err);
                 }
 
                 // Try to get previously created semaphore
-                redisClient.get(key, function(err, data) {
+                redisClient.get(key, (err, data) => {
                     // If we encountered an error, unlock the mutex lock and return error
                     if (err) {
                         return _this.mutex.unlock(`lock:${key}`, () => { callback(err); });
@@ -824,7 +1017,7 @@ function PettyCache() {
                         return _this.mutex.unlock(`lock:${key}`, () => { callback(null, JSON.parse(data)); });
                     }
 
-                    var getSize = function(callback) {
+                    const getSize = (callback) => {
                         if (typeof options.size === 'function') {
                             return options.size(callback);
                         }
@@ -832,15 +1025,15 @@ function PettyCache() {
                         callback(null, Object.prototype.hasOwnProperty.call(options, 'size') ? options.size : 1);
                     };
 
-                    getSize(function(err, size) {
+                    getSize((err, size) => {
                         // If we encountered an error, unlock the mutex lock and return error
                         if (err) {
                             return _this.mutex.unlock(`lock:${key}`, () => { callback(err); });
                         }
 
-                        var pool = Array(Math.max(size, 1)).fill({ status: 'available' });
+                        const pool = Array(Math.max(size, 1)).fill({ status: 'available' });
 
-                        redisClient.set(key, JSON.stringify(pool), function(err) {
+                        redisClient.set(key, JSON.stringify(pool), (err) => {
                             if (err) {
                                 return _this.mutex.unlock(`lock:${key}`, () => { callback(err); });
                             }
@@ -853,9 +1046,16 @@ function PettyCache() {
         }
     };
 
-    this.set = function(key, value, options, callback) {
-        options = options || {};
-
+    /**
+     * Stores a value in both the memory cache and Redis. Supports both callback and promise styles.
+     * @param {string} key - The cache key.
+     * @param {*} value - The value to cache.
+     * @param {Object} [options] - Optional settings.
+     * @param {number|Object} [options.ttl] - TTL in ms, or object with min/max properties.
+     * @param {Function} [callback] - Optional callback(err). If omitted, returns a Promise.
+     * @returns {Promise|undefined}
+     */
+    this.set = (key, value, options = {}, callback) => {
         if (typeof options === 'function') {
             callback = options;
             options = {};
@@ -864,22 +1064,41 @@ function PettyCache() {
         // Get TTL based on specified options
         const ttl = getTtl(options);
 
-        // Default callback is a noop
-        callback = callback || function() {};
+        const executor = () => {
+            return new Promise((resolve, reject) => {
+                // Store value in memory cache with a short expiration
+                memoryCache.put(key, value, random(2000, 5000));
 
-        // Store value in memory cache with a short expiration
-        memoryCache.put(key, value, random(2000, 5000));
+                // Store value in Redis
+                redisClient.psetex(key, random(ttl.min, ttl.max), PettyCache.stringify(value), (err) => {
+                    if (err) {
+                        return reject(err);
+                    }
 
-        // Store value is Redis
-        redisClient.psetex(key, random(ttl.min, ttl.max), PettyCache.stringify(value), callback);
+                    resolve();
+                });
+            });
+        };
+
+        if (callback) {
+            executor().then(result => callback(null, result)).catch(callback);
+        } else {
+            return executor();
+        }
     };
 
     // Semaphore functions need to be bound to the main PettyCache object
-    for (var method in this.semaphore) {
+    for (const method in this.semaphore) {
         this.semaphore[method] = this.semaphore[method].bind(this);
     }
 }
 
+/**
+ * Returns a random integer between min and max, inclusive.
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
 function random(min, max) {
     if (min === max) {
         return min;
@@ -888,8 +1107,13 @@ function random(min, max) {
     return Math.floor(Math.random() * (max - min + 1) + min);
 }
 
-PettyCache.parse = function(text) {
-    return JSON.parse(text, function(k, v) {
+/**
+ * Parses a JSON string produced by PettyCache.stringify(), restoring NaN, null, and undefined.
+ * @param {string} text
+ * @returns {*}
+ */
+PettyCache.parse = (text) => {
+    return JSON.parse(text, (k, v) => {
         if (v === '__NaN') {
             return NaN;
         } else if (v === '__null') {
@@ -902,8 +1126,14 @@ PettyCache.parse = function(text) {
     });
 };
 
-PettyCache.stringify = function(value) {
-    return JSON.stringify(value, function(k, v) {
+/**
+ * Serializes a value to JSON, encoding NaN, null, and undefined as sentinel strings
+ * so they survive a Redis round-trip and can be restored by PettyCache.parse().
+ * @param {*} value
+ * @returns {string}
+ */
+PettyCache.stringify = (value) => {
+    return JSON.stringify(value, (k, v) => {
         if (typeof v === 'number' && isNaN(v)) {
             return '__NaN';
         } else if (v === null) {