Cachio

A simple JSON-based caching utility with CLI and API support.

Cachio is a lightweight utility for managing key-value JSON caches in Node.js, with support for custom file paths, TypeScript, and a command-line interface.

Features ✨

• 🔹 Simple API: Manage key-value pairs with methods like set, get, delete, and more.
• 🚀 CLI Ready: Control the cache via terminal with commands like --set, --get, and --clear.
• 🔄 Configurable Storage: Customize cache file name and directory via a config file.
• 🌐 Cross-Platform: Works in modern Node.js environments with TypeScript support.
• ⚡ Fast & Minimal: Async I/O operations with robust error handling and type validation.

Installation 💿

# Using npm
npm install cachio

# Using pnpm
pnpm add cachio

# Using yarn
yarn add cachio

Usage 📦

API </>

The cachio module provides a simple API for managing a key-value cache stored as a JSON file. Below are the available functions with JSDoc documentation.

import * as cachio from 'cachio';

// Access the cache Map
console.log(cachio.cache); // Map {}

// Add or update a key-value pair
await cachio.set('name', 'John');
console.log(cachio.cache); // Map { 'name' => 'John' }

await cachio.set('age', 30);
await cachio.set('active', true);
console.log(cachio.cache); // Map { 'name' => 'John', 'age' => 30, 'active' => true }

// Retrieve a value by key
console.log(cachio.get('name')); // 'John'
console.log(cachio.get('unknown')); // undefined

// Remove a key
await cachio.delete('age');
console.log(cachio.cache); // Map { 'name' => 'John', 'active' => true }

// Check if a key exists
console.log(cachio.has('name')); // true
console.log(cachio.has('age')); // false

// Clear the entire cache
await cachio.clear();
console.log(cachio.cache); // Map {}

// Get all key-value pairs
await cachio.set('name', 'John');
await cachio.set('age', 30);
console.log([...cachio.entries()]); // [['name', 'John'], ['age', 30]]

// Iterate over the cache
cachio.forEach((value, key) => console.log(`${key}: ${value}`));
// Output:
// name: John
// age: 30

// Get all keys
console.log([...cachio.keys()]); // ['name', 'age']

// Get all values
console.log([...cachio.values()]); // ['John', 30]

// Get the cache size
console.log(cachio.size()); // 2

CLI 🖥️

#!/usr/bin/env node
cachio [command] [options]

Example Commands

# Add or update a key-value pair
cachio --set name=John
cachio --set age=30
cachio --set active=true

# Retrieve a value by key
cachio --get name

# Remove a key
cachio --delete age

# Check if a key exists
cachio --has name

# Display the entire cache
cachio --cache

# Clear the entire cache
cachio --clear

# List all keys
cachio --keys

# List all values
cachio --values

# List all key-value pairs
cachio --entries

# Display the cache size
cachio --size

# Iterate and print key-value pairs
cachio --forEach

# Show help
cachio --help

# Show version
cachio --version

CLI Options

  --set <key>=<value>      Add or update a key-value pair in the cache
  --get <key>              Retrieve a value by key
  --delete <key>           Remove a key from the cache
  --has <key>              Check if a key exists in the cache
  --cache                  Display the entire cache
  --clear                  Clear the entire cache
  --keys                   List all keys in the cache
  --values                 List all values in the cache
  --entries                List all key-value pairs in the cache
  --size                   Display the number of items in the cache
  --forEach                Iterate over the cache and print key-value pairs
  --help                   Show this help message
  --version                Show version

Configuration

Create a cachio.config.mjs file in your project root to customize the cache file name and storage path:

import { defineConfig } from 'cachio/config';

export default defineConfig({
  name: 'my-cache',
  directory: './cache',
});

License 📄

MIT License – see LICENSE for details.

Author: Estarlin R (estarlincito.com)