ioredis-cache
Version:
A promise-based cache package for Nodejs using IORedis
668 lines (667 loc) • 29.5 kB
JavaScript
"use strict";
var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
return new (P || (P = Promise))(function (resolve, reject) {
function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
step((generator = generator.apply(thisArg, _arguments || [])).next());
});
};
var __generator = (this && this.__generator) || function (thisArg, body) {
var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
function verb(n) { return function (v) { return step([n, v]); }; }
function step(op) {
if (f) throw new TypeError("Generator is already executing.");
while (_) try {
if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
if (y = 0, t) op = [op[0] & 2, t.value];
switch (op[0]) {
case 0: case 1: t = op; break;
case 4: _.label++; return { value: op[1], done: false };
case 5: _.label++; y = op[1]; op = [0]; continue;
case 7: op = _.ops.pop(); _.trys.pop(); continue;
default:
if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
if (t[2]) _.ops.pop();
_.trys.pop(); continue;
}
op = body.call(thisArg, _);
} catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
}
};
var __asyncValues = (this && this.__asyncValues) || function (o) {
if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
var m = o[Symbol.asyncIterator], i;
return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
};
var __spreadArrays = (this && this.__spreadArrays) || function () {
for (var s = 0, i = 0, il = arguments.length; i < il; i++) s += arguments[i].length;
for (var r = Array(s), k = 0, i = 0; i < il; i++)
for (var a = arguments[i], j = 0, jl = a.length; j < jl; j++, k++)
r[k] = a[j];
return r;
};
Object.defineProperty(exports, "__esModule", { value: true });
var Acquire_1 = require("./Acquire");
var LuaAcquire_1 = require("./LuaAcquire");
var NOT_FOUND_VALUE = undefined;
var SET_PARAM_SIZE = 2;
var INVALID_REDIS_INSTANCE_MESSAGE = 'Cache requires an ioredis instance';
var DEFAULT_ACQUIRE_TYPE = 'lua';
var REQUIRED_REDIS_COMMANDS = [
'set',
'get',
'setex',
'mget',
'pipeline',
'del',
'hset',
'get',
'hdel',
];
/**
* Type guard that checks if an object is an ioredis instance by verifying the
* presence of required Redis commands (set, get, setex, mget, pipeline, del,
* hset, hdel) as functions on the object.
*/
var isRedis = function (obj) {
if (obj === null || typeof obj !== 'object') {
return false;
}
var redis = obj;
return REQUIRED_REDIS_COMMANDS.every(function (name) { return typeof redis[name] === 'function'; });
};
var Cache = /** @class */ (function () {
/**
* @param options - Either an ioredis instance directly or a CacheOptions object
* with a `redis` property plus optional `parser`, `acquire`, and
* `acquireType`. Throws if the redis instance doesn't satisfy the ioredis
* interface check.
*/
function Cache(options) {
var _this = this;
var _a;
this.parser = JSON;
/**
* Converts a value map into a flat array of `[key, stringifiedValue, key,
* stringifiedValue, ...]` suitable for `MSET` / `HMSET`. Entries whose
* value is `NOT_FOUND_VALUE` are skipped.
*/
this._buildSetParams = function (valueMap) {
var params = [];
for (var _i = 0, _a = Object.entries(valueMap); _i < _a.length; _i++) {
var _b = _a[_i], key = _b[0], value = _b[1];
if (value === NOT_FOUND_VALUE) {
continue;
}
params.push(key, _this.parser.stringify(value));
}
return params;
};
var config = (isRedis(options) ? { redis: options } : options);
if (!isRedis(config.redis)) {
throw new TypeError(INVALID_REDIS_INSTANCE_MESSAGE);
}
this.redis = config.redis;
this.acquireHelper = this.createAcquireHelper(config.acquire, (_a = config.acquireType) !== null && _a !== void 0 ? _a : DEFAULT_ACQUIRE_TYPE);
this.prefix = this.redis.options.keyPrefix || '';
if (config.parser !== undefined) {
this.parser = config.parser;
}
}
Cache.prototype.createAcquireHelper = function (acquire, acquireType) {
if (acquire !== undefined) {
return acquire;
}
if (acquireType === 'pipeline') {
return new Acquire_1.Acquire(this.redis);
}
return new LuaAcquire_1.LuaAcquire(this.redis);
};
/**
* Binds all prototype methods of Cache to a target instance so they can be
* destructured and called without losing the `this` context.
*
* @returns The same target instance after binding.
*/
Cache.bindAll = function (target) {
var targetMethods = target;
for (var _i = 0, _a = Object.getOwnPropertyNames(Cache.prototype); _i < _a.length; _i++) {
var name = _a[_i];
if (name === 'constructor') {
continue;
}
var method = targetMethods[name];
if (typeof method === 'function') {
targetMethods[name] = method.bind(target);
}
}
return target;
};
/**
* Read-through cache for a single key. Checks the cache first; if the value
* is missing, calls `fn` to produce it, stores the result, and returns it.
*
* @param key - Cache key to look up.
* @param fn - Factory function invoked on cache miss.
* @param ttl - Optional TTL in seconds. If omitted the value is stored
* without expiry.
*/
Cache.prototype.cache = function (key, fn, ttl) {
return __awaiter(this, void 0, void 0, function () {
var value;
return __generator(this, function (_a) {
switch (_a.label) {
case 0: return [4 /*yield*/, this.getCache(key)];
case 1:
value = _a.sent();
if (value !== NOT_FOUND_VALUE) {
return [2 /*return*/, value];
}
return [4 /*yield*/, fn()];
case 2:
value = _a.sent();
if (!(value !== NOT_FOUND_VALUE)) return [3 /*break*/, 4];
return [4 /*yield*/, this.setCache(key, value, ttl)];
case 3:
_a.sent();
_a.label = 4;
case 4: return [2 /*return*/, value];
}
});
});
};
/**
* Retrieves a single cached value by key. Returns `undefined` when the key
* is not found (the `NOT_FOUND_VALUE` sentinel), making it safe to
* distinguish a cache miss from a stored value.
*/
Cache.prototype.getCache = function (key) {
return __awaiter(this, void 0, void 0, function () {
var data;
return __generator(this, function (_a) {
switch (_a.label) {
case 0: return [4 /*yield*/, this.redis.get(key)];
case 1:
data = _a.sent();
return [2 /*return*/, data === null ? NOT_FOUND_VALUE : this.parser.parse(data)];
}
});
});
};
/**
* Stores a single value in the cache. The value is serialized through the
* configured parser (default: JSON).
*
* @param ttl - Optional TTL in seconds. Uses `SETEX` when provided, plain
* `SET` otherwise.
*/
Cache.prototype.setCache = function (key, value, ttl) {
return __awaiter(this, void 0, void 0, function () {
var data;
return __generator(this, function (_a) {
data = this.parser.stringify(value);
return [2 /*return*/, ttl !== undefined
? this.redis.setex(key, ttl, data)
: this.redis.set(key, data)];
});
});
};
/**
* Read-through cache for multiple keys in a single batch. Executes a single
* `MGET` for all keys, then calls `fn` for any missing keys and stores the
* result via `MSET` (or pipelined `SETEX` when TTL is provided).
*
* @param keys - List of logical keys to fetch.
* @param fn - Factory invoked with the subset of keys that were not cached.
* Must return values in the same order as the supplied keys.
* @param prefix - Optional string (or number) prepended to every key before
* interacting with Redis. The prefix is stripped from cached results.
* @param ttl - Optional TTL in seconds for newly stored values.
*/
Cache.prototype.manyCache = function (keys, fn, prefix, ttl) {
if (prefix === void 0) { prefix = ''; }
return __awaiter(this, void 0, void 0, function () {
var fullKeys, cachedValues, uncachedKeys, uncachedValues, uncachedValueMap, fullKeyUncachedValueMap;
return __generator(this, function (_a) {
switch (_a.label) {
case 0:
fullKeys = keys.map(function (key) { return "" + prefix + key; });
return [4 /*yield*/, this.getManyCache(fullKeys)];
case 1:
cachedValues = _a.sent();
uncachedKeys = this._getUncachedKeys(keys, cachedValues);
if (!uncachedKeys.length) return [3 /*break*/, 4];
return [4 /*yield*/, fn(uncachedKeys)];
case 2:
uncachedValues = _a.sent();
uncachedValueMap = this._buildValueMap(uncachedKeys, uncachedValues);
fullKeyUncachedValueMap = this._prefixValueMap(uncachedValueMap, prefix);
return [4 /*yield*/, this.setManyCache(fullKeyUncachedValueMap, ttl)];
case 3:
_a.sent();
return [2 /*return*/, this._mergeCacheValues(cachedValues, keys, uncachedValueMap)];
case 4: return [2 /*return*/, cachedValues];
}
});
});
};
/**
* Retrieves multiple cached values by their keys using `MGET`. Returns an
* array aligned with the input keys where missing entries are `undefined`
* (the `NOT_FOUND_VALUE` sentinel).
*/
Cache.prototype.getManyCache = function (keys) {
return __awaiter(this, void 0, void 0, function () {
var data;
var _this = this;
return __generator(this, function (_a) {
switch (_a.label) {
case 0:
if (keys.length <= 0) {
return [2 /*return*/, []];
}
return [4 /*yield*/, this.redis.mget(keys)];
case 1:
data = _a.sent();
return [2 /*return*/, data.map(function (e) {
return e === null ? NOT_FOUND_VALUE : _this.parser.parse(e);
})];
}
});
});
};
/**
* Stores multiple key-value pairs atomically. Uses `MSET` when no TTL is
* given; otherwise uses a pipeline of `MSET` + per-key `EXPIRE` commands.
*
* @param valueMap - A plain object mapping string keys to serialisable values.
* @param ttl - Optional TTL in seconds applied to every key in the batch.
*/
Cache.prototype.setManyCache = function (valueMap, ttl) {
return __awaiter(this, void 0, void 0, function () {
var params, pipeline, i, key;
return __generator(this, function (_a) {
params = this._buildSetParams(valueMap);
if (params.length <= 0) {
return [2 /*return*/, []];
}
if (ttl === undefined) {
return [2 /*return*/, this.redis.mset(params)];
}
pipeline = this.redis.pipeline();
pipeline.mset(params);
for (i = 0; i < params.length; i += SET_PARAM_SIZE) {
key = params[i];
pipeline.expire(key, ttl);
}
return [2 /*return*/, pipeline.exec()];
});
});
};
/**
* Deletes one or more keys from the cache.
*
* @returns The number of keys that were actually removed.
*/
Cache.prototype.deleteCache = function () {
var keys = [];
for (var _i = 0; _i < arguments.length; _i++) {
keys[_i] = arguments[_i];
}
return __awaiter(this, void 0, void 0, function () {
var _a;
return __generator(this, function (_b) {
return [2 /*return*/, (_a = this.redis).del.apply(_a, keys)];
});
});
};
/**
* Deletes all keys matching a glob pattern by iterating with `SCAN` in
* batches. The `keyPrefix` configured on the ioredis instance is
* automatically prepended to the pattern so callers don't need to include it.
*
* @param pattern - Redis glob pattern (e.g. `user:*`).
* @param batch - Number of keys to scan and delete per pipeline (default 100).
*/
Cache.prototype.deletePattern = function (pattern, batch) {
var e_1, _a;
if (batch === void 0) { batch = 100; }
return __awaiter(this, void 0, void 0, function () {
var jobs, length, pipeline, _b, _c, keys, _i, keys_1, key, e_1_1;
return __generator(this, function (_d) {
switch (_d.label) {
case 0:
jobs = [];
length = this.prefix.length;
pipeline = this.redis.pipeline();
_d.label = 1;
case 1:
_d.trys.push([1, 6, 7, 12]);
_b = __asyncValues(this.redis.scanStream({
match: "" + this.prefix + pattern,
count: batch,
}));
_d.label = 2;
case 2: return [4 /*yield*/, _b.next()];
case 3:
if (!(_c = _d.sent(), !_c.done)) return [3 /*break*/, 5];
keys = _c.value;
for (_i = 0, keys_1 = keys; _i < keys_1.length; _i++) {
key = keys_1[_i];
pipeline.del(key.substring(length));
}
if (pipeline.length >= batch) {
jobs.push(pipeline.exec());
pipeline = this.redis.pipeline();
}
_d.label = 4;
case 4: return [3 /*break*/, 2];
case 5: return [3 /*break*/, 12];
case 6:
e_1_1 = _d.sent();
e_1 = { error: e_1_1 };
return [3 /*break*/, 12];
case 7:
_d.trys.push([7, , 10, 11]);
if (!(_c && !_c.done && (_a = _b.return))) return [3 /*break*/, 9];
return [4 /*yield*/, _a.call(_b)];
case 8:
_d.sent();
_d.label = 9;
case 9: return [3 /*break*/, 11];
case 10:
if (e_1) throw e_1.error;
return [7 /*endfinally*/];
case 11: return [7 /*endfinally*/];
case 12:
jobs.push(pipeline.exec());
return [4 /*yield*/, Promise.all(jobs)];
case 13:
_d.sent();
return [2 /*return*/];
}
});
});
};
/**
* Read-through cache for a single field inside a Redis hash. Checks the hash
* first; on miss calls `fn`, stores the result, and returns it.
*
* @param key - The Redis hash key.
* @param id - The field name within the hash.
* @param fn - Factory function invoked on cache miss.
*/
Cache.prototype.hashCache = function (key, id, fn) {
return __awaiter(this, void 0, void 0, function () {
var value;
return __generator(this, function (_a) {
switch (_a.label) {
case 0: return [4 /*yield*/, this.getHashCache(key, id)];
case 1:
value = _a.sent();
if (value !== NOT_FOUND_VALUE) {
return [2 /*return*/, value];
}
return [4 /*yield*/, fn()];
case 2:
value = _a.sent();
if (!(value !== NOT_FOUND_VALUE)) return [3 /*break*/, 4];
return [4 /*yield*/, this.setHashCache(key, id, value)];
case 3:
_a.sent();
_a.label = 4;
case 4: return [2 /*return*/, value];
}
});
});
};
/**
* Retrieves a single field from a Redis hash. Returns `undefined` (the
* `NOT_FOUND_VALUE` sentinel) when the field does not exist.
*/
Cache.prototype.getHashCache = function (key, id) {
return __awaiter(this, void 0, void 0, function () {
var data;
return __generator(this, function (_a) {
switch (_a.label) {
case 0: return [4 /*yield*/, this.redis.hget(key, id)];
case 1:
data = _a.sent();
return [2 /*return*/, data === null ? NOT_FOUND_VALUE : this.parser.parse(data)];
}
});
});
};
/**
* Stores a single field in a Redis hash. The value is serialised through the
* configured parser.
*/
Cache.prototype.setHashCache = function (key, id, value) {
return __awaiter(this, void 0, void 0, function () {
var data;
return __generator(this, function (_a) {
data = this.parser.stringify(value);
return [2 /*return*/, this.redis.hset(key, id, data)];
});
});
};
/**
* Read-through cache for multiple fields within a single Redis hash. Issues
* a single `HMGET`, calls `fn` for any missing fields, persists them with
* `HMSET`, and returns the merged result aligned with the input `ids`.
*
* @param key - The Redis hash key.
* @param ids - Field names to fetch.
* @param fn - Factory invoked with the subset of field names that are not
* cached. Must return values in the same order.
*/
Cache.prototype.hashManyCache = function (key, ids, fn) {
return __awaiter(this, void 0, void 0, function () {
var cachedValues, uncachedIds, uncachedValues, uncachedValueMap;
return __generator(this, function (_a) {
switch (_a.label) {
case 0: return [4 /*yield*/, this.getHashManyCache(key, ids)];
case 1:
cachedValues = _a.sent();
uncachedIds = this._getUncachedKeys(ids, cachedValues);
if (!uncachedIds.length) return [3 /*break*/, 4];
return [4 /*yield*/, fn(uncachedIds)];
case 2:
uncachedValues = _a.sent();
uncachedValueMap = this._buildValueMap(uncachedIds, uncachedValues);
return [4 /*yield*/, this.setHashManyCache(key, uncachedValueMap)];
case 3:
_a.sent();
return [2 /*return*/, this._mergeCacheValues(cachedValues, ids, uncachedValueMap)];
case 4: return [2 /*return*/, cachedValues];
}
});
});
};
/**
* Retrieves multiple fields from a Redis hash using `HMGET`. Returns an
* array aligned with the input `ids` where missing fields are `undefined`
* (the `NOT_FOUND_VALUE` sentinel).
*/
Cache.prototype.getHashManyCache = function (key, ids) {
return __awaiter(this, void 0, void 0, function () {
var data;
var _a;
var _this = this;
return __generator(this, function (_b) {
switch (_b.label) {
case 0:
if (ids.length <= 0) {
return [2 /*return*/, []];
}
return [4 /*yield*/, (_a = this.redis).hmget.apply(_a, __spreadArrays([key], ids))];
case 1:
data = _b.sent();
return [2 /*return*/, data.map(function (e) {
return e === null ? NOT_FOUND_VALUE : _this.parser.parse(e);
})];
}
});
});
};
/**
* Stores multiple fields in a Redis hash atomically using `HMSET`.
*
* @param key - The Redis hash key.
* @param valueMap - A plain object mapping field names to serialisable values.
*/
Cache.prototype.setHashManyCache = function (key, valueMap) {
return __awaiter(this, void 0, void 0, function () {
var params;
return __generator(this, function (_a) {
params = this._buildSetParams(valueMap);
if (params.length <= 0) {
return [2 /*return*/, []];
}
return [2 /*return*/, this.redis.hmset(key, params)];
});
});
};
/**
* Deletes one or more fields from a Redis hash.
*
* @returns The number of fields that were actually removed.
*/
Cache.prototype.deleteHashCache = function (key) {
var ids = [];
for (var _i = 1; _i < arguments.length; _i++) {
ids[_i - 1] = arguments[_i];
}
return __awaiter(this, void 0, void 0, function () {
var _a;
return __generator(this, function (_b) {
return [2 /*return*/, (_a = this.redis).hdel.apply(_a, __spreadArrays([key], ids))];
});
});
};
/**
* Atomically increments (or decrements) a Redis key and invokes `fn` with
* the updated value. On failure the increment is automatically rolled back.
*
* @param key - Redis key holding the counter.
* @param amount - Amount to add (use a negative number to decrement).
* @param fn - Callback receiving current, acquired, and lacking amounts.
* @param options - When `float` is true uses `INCRBYFLOAT`; `limit` caps
* how much can be acquired.
*/
Cache.prototype.acquire = function (key, amount, fn, options) {
return __awaiter(this, void 0, void 0, function () {
return __generator(this, function (_a) {
return [2 /*return*/, this.acquireHelper.acquire(key, amount, fn, options)];
});
});
};
/**
* Atomically increments (or decrements) a field inside a Redis hash and
* invokes `fn` with the updated value.
*
* @param key - The Redis hash key.
* @param id - The field name within the hash.
* @param amount - Amount to add.
* @param fn - Callback receiving current, acquired, and lacking amounts.
* @param options - When `float` is true uses `HINCRBYFLOAT`; `limit` caps
* how much can be acquired.
*/
Cache.prototype.hashAcquire = function (key, id, amount, fn, options) {
return __awaiter(this, void 0, void 0, function () {
return __generator(this, function (_a) {
return [2 /*return*/, this.acquireHelper.hashAcquire(key, id, amount, fn, options)];
});
});
};
/**
* Atomically modifies multiple counters through the configured acquire
* helper. Each desired change is specified as an `AcquireDesire` item; `fn`
* receives the final values.
*/
Cache.prototype.acquireMany = function (items, fn, options) {
return __awaiter(this, void 0, void 0, function () {
return __generator(this, function (_a) {
return [2 /*return*/, this.acquireHelper.acquireMany(items, fn, options)];
});
});
};
/**
* Atomically modifies multiple fields inside a single Redis hash counter
* through the configured acquire helper.
*
* @param hashKey - The Redis hash key containing the counters.
* @param items - Desired changes for each field.
* @param fn - Callback receiving the array of results.
*/
Cache.prototype.hashAcquireMany = function (hashKey, items, fn, options) {
return __awaiter(this, void 0, void 0, function () {
return __generator(this, function (_a) {
return [2 /*return*/, this.acquireHelper.hashAcquireMany(hashKey, items, fn, options)];
});
});
};
/**
* Filters the input `keys` down to those whose corresponding entry in
* `cachedValues` is `NOT_FOUND_VALUE`.
*/
Cache.prototype._getUncachedKeys = function (keys, cachedValues) {
return keys.filter(function (_, index) { return cachedValues[index] === NOT_FOUND_VALUE; });
};
/**
* Merges a set of cached values with a map of uncached values. Where a
* cached entry is `NOT_FOUND_VALUE`, the corresponding value is looked up
* from `uncachedValueMap` by key.
*/
Cache.prototype._mergeCacheValues = function (cachedValues, keys, uncachedValueMap) {
return cachedValues.map(function (value, index) {
if (value !== NOT_FOUND_VALUE) {
return value;
}
return uncachedValueMap[String(keys[index])];
});
};
/**
* Returns a new map with every key prefixed by `prefix`. Used internally
* by `manyCache` to apply the configured prefix before storing.
*/
Cache.prototype._prefixValueMap = function (valueMap, prefix) {
var prefixedMap = {};
for (var _i = 0, _a = Object.entries(valueMap); _i < _a.length; _i++) {
var _b = _a[_i], key = _b[0], value = _b[1];
prefixedMap["" + prefix + key] = value;
}
return prefixedMap;
};
/**
* Normalises a `ValueSource` (array, `Map`, or plain object) into a uniform
* `ValueMap` keyed by the string representation of each id. Array and `Map`
* sources are aligned with `ids` by position.
*/
Cache.prototype._buildValueMap = function (ids, valueMap) {
if (Array.isArray(valueMap)) {
return ids.reduce(function (cacheMap, id, index) {
cacheMap[String(id)] = valueMap[index];
return cacheMap;
}, {});
}
if (valueMap instanceof Map) {
return ids.reduce(function (cacheMap, id) {
cacheMap[String(id)] = valueMap.get(id);
return cacheMap;
}, {});
}
return valueMap;
};
return Cache;
}());
exports.default = Cache;