Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/binary-person/rammerhead/llms.txt

Use this file to discover all available pages before exploring further.

When testcafe-hammerhead rewrites JavaScript it performs a significant amount of AST parsing and code generation. Rammerhead caches the rewritten output keyed by a hash of the original script so that subsequent requests for the same resource skip rewriting entirely. Two concrete cache implementations are available: an in-memory LRU cache and a disk-backed LRU cache.

​
RammerheadJSAbstractCache

The abstract base class both implementations extend. It exposes two async methods that all concrete caches must implement. You cannot instantiate this class directly. 
// Both methods are async
await cache.get(key)    // → string | undefined
await cache.set(key, value)
MethodDescription
get(key)Returns the cached rewritten JS string, or undefined on a miss.
set(key, value)Stores a rewritten JS string under the given cache key.

​
RammerheadJSMemCache

An in-memory LRU cache backed by lru-cache. Cache size is enforced in bytes. When the cache is full, the least-recently-used entry is evicted to make room for the new one. This is the default cache used by RammerheadProxy (50 MB). It is fast, requires no filesystem, and works in any deployment topology. Use it during development or when you run a single server process.
Memory cache contents are lost on process restart. In cluster deployments with multiple worker processes, each worker has its own independent memory cache, so the effective hit rate is lower than with a shared disk cache.

​
Constructor

const cache = new RammerheadJSMemCache(maxSize);
​
maxSize
number
required
Maximum total size of cached values in bytes. When the size limit is exceeded, LRU entries are evicted. The size of each entry is calculated as the byte length of the cached string.Common values:
  • 50 * 1024 * 1024 — 50 MB (default in RammerheadProxy)
  • 100 * 1024 * 1024 — 100 MB
  • 200 * 1024 * 1024 — 200 MB

​
Methods

​
get

cache.get(key)
​
key
string
required
Cache key (the hash of the original script).
In the current implementation, RammerheadJSMemCache.get() calls this.lru.get(key) but does not return the result. Cache reads silently return undefined regardless of whether a hit occurs. The disk-backed RammerheadJSFileCache does not have this issue and correctly returns cached content.

​
set

cache.set(key, value)
​
key
string
required
Cache key.
​
value
string
required
Rewritten JavaScript string to cache.

​
RammerheadJSFileCache

A disk-backed LRU cache backed by lru-cache. Each cached script is written to a file named by its cache key inside a configured directory. The LRU marker is kept in memory; the actual content lives on disk. When an entry is evicted from the LRU, the corresponding file is deleted. RammerheadJSFileCache supports an optional worker mode for cluster deployments where multiple Node.js workers share a single cache directory. In worker mode, only the master process writes to disk and maintains the LRU marker; workers send IPC messages to ask the master whether a key exists and to submit new entries.
Use RammerheadJSFileCache in production when you run multiple worker processes or when you want the JS cache to survive server restarts. Worker mode (enableWorkers: true) prevents cache corruption from concurrent writes.

​
Constructor

const cache = new RammerheadJSFileCache(directory, maxSize, maxFiles, enableWorkers);
​
directory
string
required
Absolute path to an existing directory where cached script files are stored. The directory must exist before the cache is constructed — the constructor throws TypeError if it does not.
​
maxSize
number
required
Maximum total size of cached files in bytes. Enforced by the LRU marker using each file’s byte length.
​
maxFiles
number
required
Maximum number of cached files. When this limit is reached, the least-recently-used file is deleted.
​
enableWorkers
boolean
required
When true, enables cluster worker mode. The master process owns all disk I/O and LRU state. Worker processes communicate via IPC. Set to false when running a single process.

​
Methods

​
get

const result = await cache.get(key)
In worker mode, the worker sends an IPC request to the master and awaits a response before checking the file. In non-worker mode, the LRU marker is checked directly.
​
key
string
required
Cache key.
​
returns
Promise<string | undefined>
The cached script content, or undefined on a miss.

​
set

cache.set(key, value)
In worker mode, the worker sends the key and value to the master via IPC. The master writes the file and updates the LRU marker. In non-worker mode, the file is written synchronously.
​
key
string
required
Cache key.
​
value
string
required
Rewritten JavaScript string to persist.

​
Choosing the right cache

RammerheadJSMemCacheRammerheadJSFileCache
PersistenceNone — lost on restartSurvives restarts
Multi-workerEach worker has its own cacheShared via IPC (worker mode)
SpeedFastestSlightly slower (disk I/O)
SetupNo config neededNeeds an existing directory
Best forDevelopment, single processProduction, clusters

​
Configuration examples

const { RammerheadProxy, RammerheadJSMemCache } = require('rammerhead');

const proxy = new RammerheadProxy({
  port: 8080,
  // Default: 50 MB memory cache. Increase for high-traffic deployments.
  jsCache: new RammerheadJSMemCache(100 * 1024 * 1024) // 100 MB
});

Build docs developers (and LLMs) love

Get started for freeTalk to us