@humanspeak/memory-cache

A lightweight, zero-dependency in-memory cache for TypeScript and JavaScript

A powerful, feature-rich in-memory caching solution with TTL expiration, LRU-style eviction, wildcard pattern deletion, and a @cached decorator for effortless method-level memoization. Perfect for API response caching, session storage, expensive computation caching, and performance optimization.

Visit the documentation for detailed API reference and examples.

Features

• Zero Dependencies - Lightweight and fast
• TTL Expiration - Automatic cache entry expiration
• Size-Based Eviction - LRU-style eviction when cache is full
• Wildcard Deletion - Delete entries by prefix or wildcard patterns
• Full TypeScript Support - Complete type definitions included
• Method Decorator - @cached decorator for automatic memoization
• Null/Undefined Support - Properly caches falsy values

Installation

npm install @humanspeak/memory-cache

pnpm add @humanspeak/memory-cache

yarn add @humanspeak/memory-cache

Quick Start

Basic Usage

import { MemoryCache } from '@humanspeak/memory-cache'

// Create a cache with default options (100 entries, 5 minute TTL)
const cache = new MemoryCache<string>()

// Or customize the options
const cache = new MemoryCache<string>({
    maxSize: 1000,        // Maximum entries before eviction
    ttl: 10 * 60 * 1000   // 10 minutes TTL
})

// Store and retrieve values
cache.set('user:123', 'John Doe')
const name = cache.get('user:123') // 'John Doe'

// Check if key exists
if (cache.has('user:123')) {
    // Key exists and hasn't expired
}

// Delete entries
cache.delete('user:123')
cache.clear() // Remove all entries

Wildcard Pattern Deletion

const cache = new MemoryCache<string>()

cache.set('user:123:name', 'John')
cache.set('user:123:email', 'john@example.com')
cache.set('user:456:name', 'Jane')
cache.set('post:789', 'Hello World')

// Delete by prefix
cache.deleteByPrefix('user:123:') // Removes user:123:name and user:123:email

// Delete by wildcard pattern
cache.deleteByMagicString('user:*:name') // Removes all user names
cache.deleteByMagicString('*:123:*')     // Removes all entries with :123:

Method Decorator

import { cached } from '@humanspeak/memory-cache'

class UserService {
    @cached<User>({ ttl: 60000, maxSize: 100 })
    async getUser(id: string): Promise<User> {
        // This expensive operation will be cached
        return await database.findUser(id)
    }

    @cached<string[]>()
    getUserPermissions(userId: string, role: string): string[] {
        // Results are cached per unique argument combination
        return computePermissions(userId, role)
    }
}

const service = new UserService()

// First call - executes the method
await service.getUser('123')

// Second call - returns cached result
await service.getUser('123')

API Reference

MemoryCache<T>

Constructor Options

Option	Type	Default	Description
maxSize	number	100	Maximum entries before eviction (0 = unlimited)
ttl	number	300000	Time-to-live in milliseconds (0 = no expiration)

Methods

Method	Description
get(key)	Retrieves a value from the cache
set(key, value)	Stores a value in the cache
has(key)	Checks if a key exists (useful for cached undefined)
delete(key)	Removes a specific entry
deleteAsync(key)	Async version of delete
clear()	Removes all entries
deleteByPrefix(prefix)	Removes entries starting with prefix
deleteByMagicString(pattern)	Removes entries matching wildcard pattern

@cached<T>(options?)

A method decorator for automatic result caching.

@cached<ReturnType>({ ttl: 60000, maxSize: 100 })
methodName(args): ReturnType { ... }

Configuration Examples

// High-traffic API cache
const apiCache = new MemoryCache<Response>({
    maxSize: 10000,
    ttl: 5 * 60 * 1000  // 5 minutes
})

// Session storage (longer TTL, smaller size)
const sessionCache = new MemoryCache<Session>({
    maxSize: 1000,
    ttl: 30 * 60 * 1000  // 30 minutes
})

// Computation cache (no TTL, size-limited)
const computeCache = new MemoryCache<Result>({
    maxSize: 500,
    ttl: 0  // No expiration
})

// Unlimited cache (use with caution)
const unlimitedCache = new MemoryCache<Data>({
    maxSize: 0,  // No size limit
    ttl: 0       // No expiration
})

Documentation

For complete documentation, examples, and API reference, visit memory.svelte.page.

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.