Простое и быстрое внутреннее кеширование для NodeJS
Простой модуль кеширования, который имеет методы set
, get
и delete
и работает немного как memcached. Ключи могут иметь тайм-аут (ttl
), после которого они истекают и удаляются из кеша. Все ключи хранятся в одном объекте, поэтому практический предел составляет около 1 миллиона ключей.
Заявление о непродаже
Мы получили множество запросов в прошлом, чтобы передать этот проект новому мейнтейнеру, чтобы его можно было возродить и вернуть к жизни. Многие из этих запросов также предлагали деньги, чтобы фактически "купить" проект (или его репутацию и базу пользователей).
Эти запросы представляют высокий риск для текущих пользователей этого проекта, особенно в условиях xz-backdoor и мысли о передаче доверия пользовательской базы (которая была почти полностью построена [@mpneuried](https://github.com/mpneuried) и спонсирована [Team Centric Software](https://www.tcs.de/)), кажется, что мы бы вас обманули. Передача ключей от этого проекта (особенно разрешения на публикацию новых версий пакета на npm) кому-то новому включает передачу доверия, которое наша пользовательская база вкладывает в пакет.
Поэтому **мы клянемся не продавать этот проект и его 2,886,264 еженедельных загрузок (по данным npm на 29 мая 2024 года)**.
Да, этот проект, по-видимому, не поддерживается. Если вы хотите взять на себя эту задачу, не стесняйтесь создать форк и начать поддерживать его там. Если сообщество захочет, оно последует за вами.
КРИТИЧЕСКИЙ МАЖОРНЫЙ ВЫПУСК v5.x
Недавний выпуск 5.x:
- прекратил поддержку версий node до 8.x!
- удалил API на основе обратных вызовов из всех методов (вы можете снова включить их с помощью опции
enableLegacyCallbacks
)
КРИТИЧЕСКИЙ МАЖОРНЫЙ ВЫПУСК v6.x ПРЕДСТОЯЩИЙ
Хотя это и не является критическим по определению, наш переписанный на TypeScript код изменит внутренние функции и их имена. Пожалуйста, свяжитесь с нами, если вы используете некоторые части внутреннего API node-cache, чтобы мы могли что-то придумать!
Установка
npm install node-cache --save
Или просто подключите файл node_cache.js
, чтобы получить суперкласс
Примеры:
Инициализация (INIT):
const NodeCache = require("node-cache");
const myCache = new NodeCache();
Опции
stdTTL
: (по умолчанию:0
) стандартный ttl в секундах для каждого созданного элемента кеша.0
= неограниченноcheckperiod
: (по умолчанию:600
) Период в секундах, используемый для автоматического интервала проверки удаления.0
= без периодической проверки.useClones
: (по умолчанию:true
) включить/отключить клонирование переменных. Еслиtrue
, вы получите копию кешированной переменной. Еслиfalse
, вы сохраните и получите только ссылку.deleteOnExpire
: (по умолчанию:true
) будут ли переменные автоматически удаляться при истечении срока их действия. Еслиtrue
, переменная будет удалена. Еслиfalse
, переменная останется. Вам рекомендуется обрабатывать переменную при событииexpired
самостоятельно.enableLegacyCallbacks
: (по умолчанию:false
) повторно включает использование обратных вызовов вместо синхронных функций. Добавляет дополнительный аргументcb
к каждой функции, который разрешается в(err, result)
. Будет удалено в node-cache v6.x.maxKeys
: (по умолчанию:-1
) указывает максимальное количество ключей, которые могут быть сохранены в кеше. Если новый элемент установлен, а кеш заполнен, будет выброшена ошибка, и ключ не будет сохранен в кеше.-1
отключает ограничение ключей.
Сохранение ключа (SET):
myCache.set(key, val, [ttl])
Устанавливает пару key
value
. Возможно определить ttl
(в секундах). Возвращает true
при успехе.
obj = { my: "Special", variable: 42 };
success = myCache.set("myKey", obj, 10000);
// true
Примечание: Если ключ истекает на основе своего ttl
, он будет полностью удален из внутреннего объекта данных.
Сохранение нескольких ключей (MSET):
myCache.mset(Array<{key, val, ttl?}>)
Устанавливает несколько пар key
val
. Возможно определить ttl
(в секундах). Возвращает true
при успехе.
const obj = { my: "Special", variable: 42 };
const obj2 = { my: "other special", variable: 1337 };
const success = myCache.mset([
{key: "myKey", val: obj, ttl: 10000},
{key: "myKey2", val: obj2},
])
Получение ключа (GET):
myCache.get(key)
Получает сохраненное значение из кеша. Возвращает undefined
, если не найдено или истекло. Если значение найдено, возвращает value
.
value = myCache.get("myKey");
if (value == undefined) {
// обработка промаха!
}
// { my: "Special", variable: 42 }
Получение и удаление ключа (TAKE):
myCache.take(key)
Получает кешированное значение и удаляет ключ из кеша. Эквивалентно вызову get(key)
+ del(key)
. Полезно для реализации механизма "одноразового использования", такого как OTP, где после чтения значение становится устаревшим.
myCache.set("myKey", "myValue")
myCache.has("myKey") // возвращает true, потому что ключ сейчас кеширован
value = myCache.take("myKey") // value === "myValue"; это также удаляет ключ
myCache.has("myKey") // возвращает false, потому что ключ был удален
Получение нескольких ключей (MGET):
myCache.mget([key1, key2, ..., keyn])
Получает несколько сохраненных значений из кеша. Возвращает пустой объект {}
, если не найдено или истекло. Если значение найдено, возвращает объект с парой key
value
.
value = myCache.mget(["myKeyA", "myKeyB"]);
/*
{
"myKeyA": { my: "Special", variable: 123 },
"myKeyB": { the: "Glory", answer: 42 }
}
*/
Удаление ключа (DEL):
myCache.del(key)
Удаляет ключ. Возвращает количество удаленных записей. Удаление никогда не завершится неудачей.
value = myCache.del("A");
// 1
Удаление нескольких ключей (MDEL):
myCache.del([key1, key2, ..., keyn])
Удаляет несколько ключей. Возвращает количество удаленных записей. Удаление никогда не завершится неудачей.
value = myCache.del("A");
// 1
value = myCache.del(["B", "C"]);
// 2
value = myCache.del(["A", "B", "C", "D"]);
// 1 - потому что A, B и C не существуют
Изменение TTL (TTL):
myCache.ttl(key, ttl)
Переопределяет ttl ключа. Возвращает true
, если ключ найден и изменен. В противном случае возвращает false
. Если аргумент ttl
не передан, будет использован стандартный TTL.
Ключ будет удален при передаче ttl < 0
.
myCache = new NodeCache({ stdTTL: 100 })
changed = myCache.ttl("existentKey", 100)
// true
changed2 = myCache.ttl("missingKey", 100)
// false
changed3 = myCache.ttl("existentKey")
// true
Получение TTL (getTTL):
myCache.getTtl(key)
Получает ttl ключа. Вы получите:
undefined
, если ключ не существует0
, если у этого ключа нет ttl- метку времени в мс, представляющую время, когда ключ истечет
myCache = new NodeCache({ stdTTL: 100 })
// Date.now() = 1456000500000
myCache.set("ttlKey", "MyExpireData")
myCache.set("noTtlKey", "NonExpireData", 0)
ts = myCache.getTtl("ttlKey")
// ts будет примерно 1456000600000
ts = myCache.getTtl("ttlKey")
// ts будет примерно 1456000600000
ts = myCache.getTtl("noTtlKey")
// ts = 0
ts = myCache.getTtl("unknownKey")
// ts = undefined
Список ключей (KEYS)
myCache.keys()
Возвращает массив всех существующих ключей.
mykeys = myCache.keys();
console.log(mykeys);
// ["all", "my", "keys", "foo", "bar"]
Наличие ключа (HAS)
myCache.has(key)
Возвращает булево значение, указывающее, кеширован ли ключ.
exists = myCache.has('myKey');
console.log(exists);
Статистика (STATS):
myCache.getStats()
Возвращает статистику.
myCache.getStats();
/*
{
keys: 0, // общее количество ключей
hits: 0, // общее количество попаданий
misses: 0, // общее количество промахов
ksize: 0, // общий размер ключей в приблизительных байтах
vsize: 0 // общий размер значений в приблизительных байтах
}
*/
Очистка всех данных (FLUSH):
myCache.flushAll()
Очистка всех данных.
myCache.flushAll();
myCache.getStats();
/*
{
keys: 0, // общее количество ключей
hits: 0, // общее количество попаданий
misses: 0, // общее количество промахов
ksize: 0, // общий размер ключей в приблизительных байтах
vsize: 0 // общий размер значений в приблизительных байтах
}
*/
Очистка статистики (FLUSH STATS):
myCache.flushStats()
Очистка статистики.
myCache.flushStats();
myCache.getStats();
/*
{
keys: 0, // общее количество ключей
hits: 0, // общее количество попаданий
misses: 0, // общее количество промахов
ksize: 0, // общий размер ключей в приблизительных байтах
vsize: 0 // общий размер значений в приблизительных байтах
}
*/
Закрытие кеша:
myCache.close()
Это очистит интервал тайм-аута, который установлен на опцию периода проверки.
myCache.close();
События
set
Вызывается, когда ключ был добавлен или изменен. Вы получите key
и value
в качестве аргументов обратного вызова.
myCache.on("set", function(key, value) {
// ... что-то делаем ...
});
del
Вызывается, когда ключ был удален вручную или из-за истечения срока действия. Вы получите key
и удаленное value
в качестве аргументов обратного вызова.
myCache.on("del", function(key, value) {
// ... что-то делаем ...
});
expired
Вызывается, когда ключ истекает. Вы получите key
и value
в качестве аргументов обратного вызова.
myCache.on("expired", function(key, value) {
// ... что-то делаем ...
});
flush
Вызывается, когда кеш был очищен.
myCache.on("flush", function() {
// ... что-то делаем ...
});
flush_stats
Вызывается, когда статистика кеша была очищена.
myCache.on("flush_stats", function() {
// ... что-то делаем ...
});
Изменения, нарушающие совместимость
версия 2.x
Из-за Issue #11 формат возврата метода .get()
был изменен!
Вместо возврата объекта с ключом { "myKey": "myValue" }
он возвращает само значение "myValue"
.
версия 3.x
Из-за Issue #30 и Issue #27 переменные теперь будут клонироваться. Это может нарушить ваш код, потому что для некоторых типов переменных (например, Promise) их невозможно клонировать. Вы можете отключить клонирование, установив опцию useClones: false
. В этом случае это будет совместимо с версией 2.x.