Redson

Redson = Redis-like + JSON persistence
A tiny, zero-dependency, file-based key-value store with in-memory TTL caching for Node.js.

• Persists data to a JSON file
• In-memory cache with configurable TTL (time-to-live)
• Simple Redis-inspired API (get, set, delete)
• Automatic file creation & directory handling
• Very lightweight (~150 LOC)

Perfect for small projects, CLI tools, bots, Electron apps, or any situation where you want Redis-like semantics without running a server.

Features

• TTL-based expiration (per key)
• Memory-first read pattern → fast repeated access
• Atomic file writes with pretty-printed JSON
• Async/await friendly
• No external dependencies
• Works in Node.js ≥ 18

Installation

npm install redson

Usage

import Redson from 'redson';

const db = new Redson({
  path: './data/store.json',     // default: ./data/cache.json
  cacheTime: 300,                // default: 60 seconds
});

await db.init();                 // must call once before using

// Basic operations
await db.set('user:123', { name: 'Alice', score: 420 });
const user = await db.get('user:123');
console.log(user);               // → { name: 'Alice', score: 420 }

await db.delete('user:123');

// TTL example (expires after cacheTime seconds)
await db.set('temp-token', 'xyz789', { ttl: 3600 }); // overrides global cacheTime

// Manual cache cleanup (optional)
db.prune();

You can also pass TTL per operation (overrides global setting):

await db.set('session:abc', { userId: 7 }, { ttl: 1800 }); // 30 minutes

API

class Redson {
  constructor(config?: { path?: string; cacheTime?: number });

  async init(): Promise<void>;
  // Must be called once before using the store

  async get(key: string): Promise<any | null>;
  async set(key: string, value: any, options?: { ttl?: number }): Promise<void>;
  async delete(key: string): Promise<void>;

  prune(): void;
  // Removes expired entries from memory cache (does not affect persisted data)
}

Configuration

new Redson({
  path: './storage/myapp-data.json',   // where to save the data
  cacheTime: 600                       // default TTL in seconds (10 min)
});

Important Notes

• init() must be called before any get/set/delete operations
• Values are serialized with JSON.stringify → only JSON-serializable data is supported
• The file is not append-only — every set/delete rewrites the whole file
• Not suitable for high write throughput (> few writes/second)
• Not atomic across multiple instances (file locking not implemented)

When to use Redson

✅ Good for

• Configuration storage
• Rate limiting counters
• Session data in small apps
• Caching API responses
• Development / prototyping
• Low-traffic bots & CLIs

❌ Probably not suitable for

• High concurrency / many writes
• Large datasets (> few MB)
• Production systems that need strong durability guarantees
• Multi-process or clustered environments

License

MIT

Similar Projects

• lowdb
• node-json-db
• better-sqlite3 (when you need more power)

Enjoy simple persistence! "