CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-medusajs--cache-inmemory

In-memory caching module for Medusa with TTL support and wildcard invalidation

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

Medusa Cache In-memory

Medusa in-memory cache module provides a simple, Map-based cache store with TTL (time-to-live) functionality for the Medusa e-commerce framework. Designed for development and testing environments, it offers automatic expiration management and pattern-based cache invalidation.

Package Information

  • Package Name: @medusajs/cache-inmemory
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @medusajs/cache-inmemory
  • Node.js: >=20

Core Imports

import { initialize } from "@medusajs/cache-inmemory";

For CommonJS:

const { initialize } = require("@medusajs/cache-inmemory");

Basic Usage

import { initialize } from "@medusajs/cache-inmemory";

// Initialize cache service with default 30-second TTL
const cache = await initialize({});

// Initialize cache service with custom TTL
const customCache = await initialize({ ttl: 60 });

// Basic operations
await cache.set("user:123", { name: "Alice", age: 30 });
const user = await cache.get("user:123"); // { name: "Alice", age: 30 }

// TTL-based expiration (data expires after TTL seconds)
await cache.set("temp:data", "temporary", 5); // expires in 5 seconds

// Pattern-based invalidation
await cache.set("products:electronics:1", { name: "Laptop" });
await cache.set("products:electronics:2", { name: "Phone" });
await cache.set("products:books:1", { name: "Novel" });

// Remove all electronics products
await cache.invalidate("products:electronics:*");

// Clear entire cache
await cache.clear();

Architecture

The in-memory cache is built around these key components:

  • Map-based Storage: Uses native JavaScript Map for efficient key-value storage
  • TTL Management: Automatic expiration using Node.js timers with cleanup
  • Pattern Matching: Wildcard support for bulk cache invalidation
  • Medusa Integration: Implements ICacheService interface for framework compatibility
  • Memory Efficiency: Automatic cleanup of expired entries and timeout references

Capabilities

Cache Storage and Retrieval

Core functionality for storing and retrieving cached data with automatic expiration.

/**
 * Main cache service class implementing ICacheService interface
 */
class InMemoryCacheService {
  constructor(
    deps: InjectedDependencies,
    options?: InMemoryCacheModuleOptions
  );

  /**
   * Retrieve data from the cache
   * @param key - Cache key to retrieve
   * @returns Promise resolving to cached data or null if not found/expired
   */
  get<T>(key: string): Promise<T | null>;

  /**
   * Store data in the cache with optional TTL
   * @param key - Cache key under which to store the data
   * @param data - Data to be stored in the cache
   * @param ttl - Time to live in seconds (defaults to configured TTL). If 0, operation is ignored.
   */
  set<T>(key: string, data: T, ttl?: number): Promise<void>;
}

Cache Invalidation

Remove specific cache entries or bulk invalidation using wildcard patterns.

/**
 * Delete data from the cache
 * Supports wildcard (*) pattern matching for bulk operations
 * @param key - Cache key or pattern (e.g., "user:*", "*:active")
 */
invalidate(key: string): Promise<void>;

/**
 * Delete the entire cache
 * Clears all stored data and timeout references
 */
clear(): Promise<void>;

Module Initialization

Bootstrap the cache module within the Medusa framework.

/**
 * Initialize the cache module with optional configuration
 * @param options - Module configuration options or external module declaration
 * @returns Promise resolving to ICacheService instance
 */
function initialize(
  options?: InMemoryCacheModuleOptions | ExternalModuleDeclaration
): Promise<ICacheService>;

Types

/**
 * Configuration options for the in-memory cache module
 */
interface InMemoryCacheModuleOptions {
  /** Time to keep data in cache (in seconds) */
  ttl?: number;
}

/**
 * Internal cache record structure
 */
interface CacheRecord<T> {
  /** The cached data */
  data: T;
  /** Expiration timestamp in milliseconds */
  expire: number;
}

/**
 * Dependency injection container (empty for this module)
 */
type InjectedDependencies = {}

Usage Examples

Basic Caching

import { initialize } from "@medusajs/cache-inmemory";

const cache = await initialize({ ttl: 300 }); // 5-minute TTL

// Store user data
await cache.set("user:alice", {
  id: "alice",
  name: "Alice Johnson",
  preferences: { theme: "dark" }
});

// Retrieve user data
const user = await cache.get<User>("user:alice");
if (user) {
  console.log(`Welcome back, ${user.name}!`);
}

Custom TTL

import { initialize } from "@medusajs/cache-inmemory";

const cache = await initialize({});

// Store temporary data with custom expiration
await cache.set("session:abc123", { userId: "alice" }, 3600); // 1 hour
await cache.set("rate-limit:api", { count: 1 }, 60); // 1 minute

Pattern-based Invalidation

import { initialize } from "@medusajs/cache-inmemory";

const cache = await initialize({});

// Store related data
await cache.set("products:category:electronics:1", laptop);
await cache.set("products:category:electronics:2", phone);
await cache.set("products:category:books:1", novel);
await cache.set("products:featured:electronics:1", laptop);

// Invalidate all electronics products
await cache.invalidate("products:category:electronics:*");

// Invalidate all featured items
await cache.invalidate("products:featured:*");

// Invalidate specific pattern
await cache.invalidate("products:*:electronics:*");

Framework Integration

import { initialize } from "@medusajs/cache-inmemory";

// Initialize as Medusa module
const cacheService = await initialize({
  ttl: 600 // 10-minute default TTL
});

// Use in your Medusa service
class MyService {
  constructor({ cacheService }) {
    this.cache = cacheService;
  }

  async getCachedData(key: string) {
    return await this.cache.get(key);
  }
}

Error Handling

The cache methods are designed to fail gracefully:

  • get() returns null for non-existent or expired keys
  • set() with TTL of 0 is ignored (no-op)
  • invalidate() safely handles non-existent keys
  • Pattern matching uses JavaScript RegExp, invalid patterns may throw

Performance Considerations

  • Memory Usage: All data is stored in memory; suitable for development/testing
  • TTL Cleanup: Expired entries are cleaned up automatically via setTimeout
  • Pattern Matching: Wildcard invalidation scans all keys; performance depends on total cache size
  • Production: Recommended to use Redis-based cache module for production environments

docs

index.md

tile.json