tessl/npm-metro-cache

Cache layers for Metro bundler with multi-layered caching system supporting local file storage and remote HTTP caching

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

File Storage

Name: tessl/npm-metro-cache
Author: tessl

Local file system cache stores with support for both basic file storage and automatic cleanup of expired cache entries. Provides reliable local caching with hierarchical directory organization.

Capabilities

FileStore

Basic file-based cache store that persists cached values to the local file system with JSON and binary data support.

/**
 * Local file-based cache store with JSON and binary support
 * Organizes cache files in a hierarchical directory structure for performance
 * @template T - Type of cached values
 */
class FileStore<T> {
  /**
   * Create a new file store instance
   * @param options - Configuration options for the file store
   */
  constructor(options: FileOptions);
  
  /**
   * Read cached value from file system
   * @param key - Cache key as Buffer
   * @returns Promise resolving to cached value or null if not found/corrupted
   */
  get(key: Buffer): Promise<T | null>;
  
  /**
   * Write value to file system with automatic directory creation
   * @param key - Cache key as Buffer
   * @param value - Value to cache (JSON serializable or Buffer)
   * @returns Promise that resolves when write is complete
   */
  set(key: Buffer, value: T): Promise<void>;
  
  /**
   * Clear all cached files by removing all cache directories
   * @returns void (synchronous operation)
   */
  clear(): void;
}

/**
 * Configuration options for FileStore
 */
interface FileOptions {
  /**
   * Root directory path where cache files will be stored
   */
  root: string;
}

Usage Examples:

const { FileStore, stableHash } = require("metro-cache");

// Create file store
const fileStore = new FileStore({ root: "./build-cache" });

// Cache JavaScript compilation result
const sourceKey = stableHash({ file: "app.js", transforms: ["babel", "minify"] });
const compiledCode = "/* compiled code */";

await fileStore.set(sourceKey, compiledCode);

// Retrieve cached result
const cached = await fileStore.get(sourceKey);
if (cached !== null) {
  console.log("Cache hit:", cached);
}

// Cache binary data (like source maps)
const mapKey = stableHash({ file: "app.js.map" });
const sourceMapBuffer = Buffer.from("source map content");

await fileStore.set(mapKey, sourceMapBuffer);

AutoCleanFileStore

File store with automatic cleanup of old cached files based on configurable age thresholds and cleanup intervals.

/**
 * File store that automatically cleans up old cached files
 * Extends FileStore with periodic cleanup functionality
 * @template T - Type of cached values
 */
class AutoCleanFileStore<T> extends FileStore<T> {
  /**
   * Create a new auto-cleaning file store instance
   * @param options - Configuration options including cleanup settings
   */
  constructor(options: CleanOptions);
}

/**
 * Configuration options for AutoCleanFileStore
 */
interface CleanOptions extends FileOptions {
  /**
   * Cleanup interval in milliseconds (default: 10 minutes)
   */
  intervalMs?: number;
  
  /**
   * Age threshold for file cleanup in milliseconds (default: 3 days)
   */
  cleanupThresholdMs?: number;
}

Usage Examples:

const { AutoCleanFileStore } = require("metro-cache");

// Create auto-cleaning file store
const autoCleanStore = new AutoCleanFileStore({
  root: "./temp-cache",
  intervalMs: 5 * 60 * 1000,        // Clean every 5 minutes
  cleanupThresholdMs: 24 * 60 * 60 * 1000  // Delete files older than 1 day
});

// Use normally - cleanup happens automatically in background
await autoCleanStore.set(key, value);
const result = await autoCleanStore.get(key);

File Organization

Both FileStore implementations use a hierarchical directory structure for optimal file system performance:

Root Directory: Specified in options.root
First Level: First byte of cache key as hex (00-FF, creating 256 subdirectories)
File Name: Remaining bytes of cache key as hex

Example file path for key Buffer.from([0x12, 0x34, 0x56, 0x78]):

{root}/12/3456789...

Data Serialization

File stores handle different data types automatically:

JavaScript Objects: Serialized as JSON
Buffer Data: Stored as binary with null byte (0x00) prefix for identification
Primitive Values: Serialized as JSON

Error Handling

File stores provide robust error handling:

Read Errors: ENOENT (file not found) and SyntaxError (corrupted JSON) return null
Write Errors: ENOENT triggers automatic parent directory creation and retry
Cleanup Errors: AutoCleanFileStore logs warnings but continues operation