@dephub/cache 💾

Simple file-based and in-memory cache for Node.js applications

Features ✨

• 💾 Persistent Storage - File-based cache that survives process restarts
• 🚀 Simple API - Easy-to-use get/set/delete operations
• 📦 Type Safe - Full TypeScript support with strict value types
• ⚡ Dual Mode - Both file-based and in-memory caching
• 🔍 CLI Support - Command-line interface for cache operations
• 🎯 Runtime Validation - Type checking at runtime for added safety

Installation 💿

# Using npm
npm install @dephub/cache

# Using pnpm
pnpm add @dephub/cache

# Using yarn
yarn add @dephub/cache

Usage 🎉

CLI

# Set a value (automatically detects type)
cache set username "john_doe"
cache set score 100
cache set active true

# Get a value
cache get username

# List all entries
cache list

# Delete an entry
cache delete username

# Clear all cache
cache clear

Programmatic - File Cache (Persistent)

import { FileCache, createCache } from '@dephub/cache';

// Using constructor
const cache = new FileCache({
  name: 'my-app-cache.json',
  directory: './cache',
});

// Using factory function
const cache = createCache('file', {
  name: 'my-app-cache.json',
});

// Set values (all methods are async)
await cache.set('username', 'john_doe');
await cache.set('score', 100);
await cache.set('active', true);

// Get values
const username = await cache.get('username'); // 'john_doe'
const score = await cache.get('score'); // 100

// Check existence
const hasUser = await cache.has('username'); // true

// List all entries
const entries = await cache.entries();

// Get size
const size = await cache.size();

Programmatic - Memory Cache (In-Memory)

import { MemoryCache, createCache } from '@dephub/cache';

// Using constructor
const cache = new MemoryCache();

// Using factory function
const cache = createCache('memory');

// Set values (all methods are synchronous)
cache.set('username', 'john_doe');
cache.set('score', 100);
cache.set('active', true);

// Get values
const username = cache.get('username'); // 'john_doe'

// Check existence
const hasUser = cache.has('username'); // true

API Reference 📚

Factory Function

import { createCache } from '@dephub/cache';

// File cache with options
const fileCache = createCache('file', {
  name: 'custom-cache.json',
  directory: './storage',
});

// Memory cache
const memoryCache = createCache('memory');

// Default (file cache)
const defaultCache = createCache();

FileCache Class

Persistent file-based cache with asynchronous operations.

Constructor

new FileCache(options?: CacheOptions)

Options:

• name - Cache file name (default: 'cache.json')
• directory - Cache directory path (default: './cache')

Methods

All methods return Promises:

• set(key: string, value: CacheValue): Promise<this> - Set value with persistence
• get(key: string): Promise<CacheValue | undefined> - Get value
• has(key: string): Promise<boolean> - Check key existence
• delete(key: string): Promise<boolean> - Delete key with persistence
• clear(): Promise<void> - Clear all entries and remove file
• size(): Promise<number> - Get entry count
• keys(): Promise<string[]> - Get all keys
• values(): Promise<CacheValue[]> - Get all values
• entries(): Promise<[string, CacheValue][]> - Get all entries
• forEach(callback: (value: CacheValue, key: string) => void): Promise<void> - Iterate over entries

MemoryCache Class

In-memory cache with synchronous operations, extends Map<string, CacheValue>.

Constructor

new MemoryCache();

Methods

All methods are synchronous:

• set(key: string, value: CacheValue): this - Set value with type validation
• Inherits all Map methods: get, has, delete, clear, size, keys, values, entries, forEach

Types

type CacheValue = string | number | boolean;

interface CacheOptions {
  name?: string;
  directory?: string;
}

type Mode = 'memory' | 'file';

Value Types 🔢

The cache supports three primitive value types:

• Strings: "hello world"
• Numbers: 42, 3.14
• Booleans: true, false

Note: Complex types like objects, arrays, and null are not supported and will throw validation errors.

Error Handling ⚠️

Both cache implementations validate inputs and throw errors for:

• Non-string keys
• Invalid value types (objects, arrays, null, etc.)
• File system errors (FileCache only)

try {
  await cache.set('key', { object: 'not allowed' }); // Throws Error
} catch (err) {
  console.error(err.message); // "Cache value must be string, number, or boolean"
}

CLI Commands 🖥️

| Command | Usage | Description | | -------- | ------------------------- | ------------------------------------- | | set | cache set <key> <value> | Set a cache value (auto-detects type) | | get | cache get <key> | Get a cache value | | delete | cache delete <key> | Delete a cache entry | | list | cache list | List all cache entries | | clear | cache clear | Clear all cache entries |

License 📄

MIT License - see LICENSE for details.

Author: Estarlin R (estarlincito.com)