Documentation

Cachetron - Documentation

A pluggable caching abstraction layer with ML-powered TTL prediction.

Docs Menu

Home Introduction Overview Key Features Installation Getting Started Core Operations Cache Admin Config Route Metrics & ML Monitoring CLI Demo

Introduction - Overview

Modern applications depend heavily on caching to deliver fast, scalable, and efficient performance. However, integrating directly with a specific caching technology - such as Redis or Memcached - often results in tight coupling, making it difficult to switch providers or extend the system over time. Developers also face the challenge of manually setting TTL (Time-To-Live) values, which can lead to poor cache utilization, wasted memory, and inconsistent performance across the application. This tool addresses these challenges by introducing a pluggable caching abstraction layer combined with intelligent, machine-learning-based TTL prediction. It provides a unified and flexible approach to caching that adapts to application behavior, reduces manual effort, and improves overall system efficiency.

Key Features

Pluggable Caching Abstraction Layer
Decoupled Cache Architecture
ML-Powered TTL Prediction
Reduced Manual Configuration
Optimized Performance & Scalability
Easy Integration

Installation

Install Cachetron

npm install -g cachetron

The -g flag installs Cachetron globally so you can run its commands from anywhere. You may also install locally with npm install cachetron.

Initialize Cachetron

cachetron init

Runs the CLI initializer which creates a cachetron.json configuration file for your project.

Auto-Generated Configuration File

After running cachetron init, Cachetron creates a default cachetron.json. Example for Memcached:

cachetron.json

{
  "type": "memcache",
  "url": "localhost:11211",
  "autoTTL": true
}

Switching backend: change the type field to "redis", or "memcache".

Manual TTL: set "autoTTL": false if you prefer to manage TTLs yourself.

Switching Cache Backend

To switch backends, update cachetron.json:

cachetron.json

{
  "type": "redis",
  "url": "localhost:6379",
  "autoTTL": true
}

Manual TTL (Disable AutoTTL)

If you prefer manual TTL control, set autoTTL to false:

cachetron.json

{
  "type": "memcache",
  "url": "localhost:11211",
  "autoTTL": false
}

When autoTTL is disabled, set TTL in code: cache.set("user1", data, 120).

Getting Started

Import Cachetron and create a proxy-backed instance (example):

Import & Create Instance

import { cachetron, updateCacheConfig } from "cachetron";

Core Operations

Set / Get / Delete

Set

await cache.set("key", value, ttl);

Get

const data = await cache.get("key");

Delete

await cache.delete("key");

Clear / Keys / HasKey

Clear

await cache.clear();

Keys

const allKeys = await cache.keys();

HasKey

const exists = await cache.hasKey("key");

Cache Admin Config Route

This route allows you to update Cachetron configuration at runtime. You can modify cache providers, connection URLs and TTLs.

Cache Admin Config Route

app.post("/cache/admin/config", (req, res) => {
  try {
    updateCacheConfig(req.body);
    res.send("updated config");
  } catch (error) {
    console.log("error", error);
  }
});

Metrics & ML

After running node index.js Cachetron automatically creates a metrics.json file when your server runs. This file is used internally and you do not need to edit it.

What it contains

time - timestamp of metric
hitRatio / missRatio - current interval
hitRatioLifetime / missRatioLifetime - lifetime values
cacheSize - memory used
dataChangeRate - how often data changes
keyCount - number of cached keys
avgKeySize - average entry size

How ML Uses metrics.json

If "autoTTL": true, Cachetron's ML model reads metrics.json to learn usage patterns (access frequency, data-change rate, hit/miss ratios, memory usage) and predicts an optimal TTL for each key. This happens automatically - you don't need to set TTL manually.

Monitoring - Dashboard

Dashboard

cachetron dashboard

CLI Commands

CLI

npm install cachetron

CLI

cachetron init

CLI

cachetron dashboard

Cachetron Server Demo

A minimal Express server demonstrating how to use Cachetron with dynamic configuration updates and simple get/set operations.

Demo

import express, { json } from "express";
import cors from "cors";
import { cachetron, updateCacheConfig } from "cachetron";

const app = express();
app.use(cors());
app.use(json());

app.get("/", async (req, res) => {
  res.send("This is a simple cache server using cachetron");
});

app.post("/cache/admin/config", (req, res) => {
  try {
    updateCacheConfig(req.body);
    res.send("updated config");
  } catch (error) {
    console.log("error", error);
  }
});

app.post("/set", async (req, res) => {
  // ...
});

app.get("/get", async (req, res) => {
  // ...
});

const PORT = 3001;
app.listen(PORT, () =>
  console.log(`Server running at http://localhost:${PORT}`)
);