📦 KeyNest

🇬🇧 English | 🇺🇦 Українська

🇬🇧 English version

🔑 What is KeyNest?

KeyNest is a lightweight in-memory key-value store library for TypeScript with support for:

• TTL (time-to-live): automatic record expiration
• Global cleanup: remove items not accessed for 2+ hours
• Events (EventEmitter): listen to data removal (TTL expiration or cleanup)
• Generics: fully typed keys and values

A “smart cache” for Node.js, backend apps, or IoT projects.

👨‍💻 Who is it for?

• Node.js developers for simple caching or session storage
• Full-stack engineers for temporary data persistence without a database
• IoT/Edge developers to store sensor data temporarily
• API developers to cache responses with TTL

🛠 Use cases

| Use Case | Description | |----------------------------------|--------------------------------------| | Caching API responses | Time-based expiration | | Session storage for users | Temporary persistence | | Rate limiting / Throttling | Request limiting | | IoT devices | Temporary storage for sensors | | Data with limited lifetime | Any similar scenario |

🚀 Installation

npm install keynest-store

📖 Usage

1. Create a store

import KNStore from "keynest-store";

const kv = new KNStore<string, number>({
    cleanupEnabled: true,
    cleanupIntervalMs: 1000 * 60 * 60, // 1 hour
    staleThresholdMs: 1000 * 60 * 60 * 2 // 2 hours
});

| Parameter | Description | |---------------------|--------------------------------------------------------| | cleanupEnabled | enables automatic cleanup of inactive records | | cleanupIntervalMs | interval between cleanup checks | | staleThresholdMs | time after which a record is considered stale |

2. Set with TTL

kv.set("session:123", 42, 5000); // expires in 5 seconds

3. Listen for TTL expiration

kv.on("expired", (key, value) => {
  console.log(`Key=${key} expired due to TTL`);
});

4. Listen for global cleanup

kv.on("prune", (list) => {
  console.log(`Pruned items count: ${list.length}`);
});

5. Listen for manual deletion

kv.on("deleted", (key, value) => {
  console.log(`Запис із ключем ${key} видалено вручну`);
});

6. Using with Generics

interface User {
  id: number;
  name: string;
}

const userStore = new KVStore<string, User>();
userStore.set("u1", { id: 1, name: "Alice" }, 10000);

✅ Advantages

• Simple API (set, get, has, delete)
• Automatic data expiration
• Strong typing (Generics)
• Event support
• Lightweight, zero dependencies

Українська

🔑 Що таке KeyNest?

KeyNest — легка in-memory бібліотека для роботи з key-value сховищем на TypeScript з підтримкою:

• TTL (time-to-live): автоматичне видалення даних після вказаного часу
• Глобальне очищення: видалення записів, які не використовувалися понад 2 години
• Події (EventEmitter): відстеження видалення даних через TTL або глобальне очищення
• Дженеріки: повна типізація ключів і значень

«Розумний кеш» для веб, бекенду чи IoT-проєктів.

👨‍💻 Кому знадобиться?

• Node.js розробникам для кешування або сесійного сховища
• Full-stack інженерам для тимчасового зберігання даних без бази
• IoT/Edge розробникам для збереження даних із сенсорів
• API-фахівцям для кешування відповідей з TTL

🛠 Де можна використовувати?

| Сценарій | Опис | |----------------------------------|--------------------------------------| | Кешування API-відповідей | Заданий час життя | | Зберігання сесій користувачів | Тимчасове зберігання | | Rate limiting / Throttle | Обмеження запитів | | IoT-пристрої | Тимчасове сховище для сенсорів | | Дані з обмеженим часом життя | Будь-які подібні сценарії |

🚀 Встановлення

npm install keynest-store

📖 Використання

1. Створення сховища

import KNStore from "keynest-store";

const kv = new KNStore<string, number>({
    cleanupEnabled: true,
    cleanupIntervalMs: 1000 * 60 * 60, // (1 година)
    staleThresholdMs: 1000 * 60 * 60 * 2 // (2 години)
});

| Параметр | Опис | |------------------------------|-----------------------------------------------------| | cleanupEnabled | вмикає автоматичне очищення неактивних записів | | cleanupIntervalMs | інтервал між перевірками очищення | | staleThresholdMs | час, після якого запис вважається застарілим |

2. Запис з TTL

kv.set("session:123", 42, 5000); // 5 секунд

3. Події TTL

kv.on("expired", (key, value) => {
  console.log(`Запис із ключем ${key} видалено через TTL`);
});

4. Події глобального очищення

kv.on("prune", (list) => {
  console.log(`Видалено записів: ${list.length}`);
});

5. Події видалення запису

kv.on("deleted", (key, value) => {
  console.log(`Запис із ключем ${key} видалено вручну`);
});

6. Використання з дженеріками

interface User {
  id: number;
  name: string;
}

const userStore = new KVStore<string, User>();
userStore.set("u1", { id: 1, name: "Alice" }, 10000);

✅ Переваги

• Простий API (set, get, has, delete)
• Автоматичне видалення старих даних
• Гнучка типізація (Generics)
• Підтримка подій
• Мінімальний розмір, без зовнішніх залежностей

💡 From developers who got tired of searching for simple tools.