Skip to content

Latest commit

 

History

History
186 lines (123 loc) · 10.3 KB

README.md

File metadata and controls

186 lines (123 loc) · 10.3 KB

🚀 Kvotis — KEY-VALUE CACHE

Node.js TypeScript Docker

License: MIT PRs Welcome Maintenance

A high-performance, in-memory Key-Value cache built with Node.js & TypeScript, supporting multiple eviction policies, lazy TTL expiration, and Redis-inspired persistence (AOF & AOF Rewrite).
Designed to explore core cache internals and system design fundamentals.

📑 Table of Contents

⭐ Features

✔ In-memory Key-Value store
✔ Configurable memory limit (bytes-based)
✔ Multiple eviction policies
✔ Lazy TTL expiration
✔ Append-Only File (AOF) persistence
✔ AOF Rewrite (compaction)
✔ Modular, pluggable architecture
✔ Dockerized for local testing

🔮 Future Additions

  • Active TTL expiration (background cleaner)
  • Snapshot-based persistence
  • Replication support
  • Sharding & partitioning
  • Metrics & observability
  • Networked cache protocol (Redis-like)

🛠 Tech Stack

Node.js • TypeScript • Docker

🧩 Architecture Overview

  • Core storage uses an in-memory Map
  • Eviction & persistence are pluggable components
  • TTL is enforced on access (lazy expiration)

🧠 Eviction Policies

Kvotis supports multiple eviction strategies, configurable at runtime.

1️⃣ LRU — Least Recently Used

  • Evicts the key that has not been accessed recently
  • Updated on every GET and SET
  • Commonly used in production caches

2️⃣ LFU — Least Frequently Used

  • Evicts the key with the lowest access frequency
  • Suitable for workloads with hot keys

3️⃣ FIFO — First In First Out

  • Evicts keys in insertion order
  • Simple and predictable

4️⃣ NONE — No Eviction

  • Cache throws OOM error when memory limit is reached
  • Useful for testing and strict memory enforcement

⏱ TTL (Time-To-Live)

Kvotis uses lazy TTL expiration.

✔ How It Works

  • Each key can have an optional TTL
  • Expiration timestamp is stored with the value
  • TTL is checked only on access (GET)

✔ Behavior

  • Expired keys are removed when accessed
  • Prevents unnecessary background CPU usage
  • Ensures correctness without active scanning

This mirrors Redis’s lazy expiration strategy (partial implementation).

💾 Persistence

Kvotis implements Redis-inspired persistence mechanisms.

1️⃣ Append-Only File (AOF)

  • Every mutating operation (SET, DELETE) is appended to a log
  • On restart, cache state is reconstructed by replaying the log
  • Guarantees durability of writes

2️⃣ AOF Rewrite (Compaction)

  • Periodically rewrites the AOF file
  • Removes redundant commands
  • Keeps only the minimal command set to rebuild current state
  • Prevents unbounded AOF growth

Setup And Installation

Clone the repository

git clone https://github.com/Anshikakalpana/kvotis

Build & run

docker compose up --build

npm run start

🧭 Roadmap

  • Active TTL expiration

  • Snapshot persistence

  • Replication

  • Metrics endpoint

  • Network protocol support

📄 License

MIT License — free for personal & commercial use.

🤝 Contributing

Contributions, issues, and feature requests are welcome!
Feel free to check the issues page.

⭐ Show Your Support

Give a ⭐️ if this project helped you!

Made with ❤️ by Anshika Kalpana