Policy-driven leveled caching for TypeScript applications. levelcache stores Buffer cache entries across selectable cache levels: memory, disk, and S3. Levels represent persistence and write-pressure tradeoffs, not automatic size buckets.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

pnpm add @push.rocks/levelcache

Level Model

levelcache supports three cache levels:

Level	Persistence	Write pressure	Typical use
`memory`	Current process only	No disk/network writes	Hot values, high-churn data, short TTLs, request dedupe
`disk`	Survives process restart and machine reboot if local disk survives	Local disk writes	Expensive recomputable artifacts, local warm cache
`s3`	Survives machine loss and can warm multiple machines	Network/object-storage writes	Shared artifact cache, multi-node warm cache

The default policy is memory-only. This avoids surprise disk writes and makes memory a first-class level for write-sparing workloads.

Size limits are capacity constraints for selected levels. They do not choose durability. Policies choose where reads and writes go.

Quick Start

import { LevelCache, CacheEntry } from '@push.rocks/levelcache';

const cache = new LevelCache({
  cacheId: 'my-cache',
});
await cache.ready;

await cache.storeCacheEntryByKey(
  'greeting',
  new CacheEntry({
    contents: Buffer.from('Hello cache'),
    ttl: 60_000,
  }),
);

const cached = await cache.retrieveCacheEntryByKey('greeting');
console.log(cached?.contents.toString());

This stores and reads from memory only unless you provide a different policy.

Policy-Driven Caching

Policies control how cache levels are used:

import type { ICachePolicy } from '@push.rocks/levelcache';

const memoryAndDisk: ICachePolicy = {
  readOrder: ['memory', 'disk'],
  writeTargets: ['memory', 'disk'],
  promoteOnRead: ['memory'],
  requireWriteSuccess: ['memory', 'disk'],
};

const cache = new LevelCache({
  cacheId: 'artifacts',
  defaultPolicy: memoryAndDisk,
});
await cache.ready;

Policy fields:

Field	Meaning
`readOrder`	Levels to check, in order
`writeTargets`	Levels that receive writes
`promoteOnRead`	Levels that receive a copy after a hit in another level
`requireWriteSuccess`	Write targets that must succeed for the operation to succeed

You can override policy per operation:

await cache.storeCacheEntryByKey('asset:logo', entry, {
  policy: {
    writeTargets: ['memory', 's3'],
    requireWriteSuccess: ['memory', 's3'],
  },
});

const result = await cache.retrieveCacheEntryByKey('asset:logo', {
  policy: {
    readOrder: ['memory', 's3'],
    promoteOnRead: ['memory'],
  },
});

Skipped levels are not touched. A memory + s3 policy does not write to disk.

Common Recipes

Memory Only

Best for write-sparing, short-lived, high-churn data.

const cache = new LevelCache({
  cacheId: 'hot-values',
});

Memory + Disk

Best for local warm caches that should survive process restarts.

const cache = new LevelCache({
  cacheId: 'local-artifacts',
  defaultPolicy: {
    readOrder: ['memory', 'disk'],
    writeTargets: ['memory', 'disk'],
    promoteOnRead: ['memory'],
    requireWriteSuccess: ['memory', 'disk'],
  },
});

You can also use persistentCache: true as a shorthand for memory + disk behavior.

Memory + S3, Skipping Disk

Best for hot local reads plus machine-loss survival or cross-node cache warming, without local disk writes.

const cache = new LevelCache({
  cacheId: 'shared-artifacts',
  s3Config: {
    endpoint: 's3.amazonaws.com',
    accessKey: process.env.AWS_ACCESS_KEY_ID,
    accessSecret: process.env.AWS_SECRET_ACCESS_KEY,
    region: 'us-east-1',
    useSsl: true,
  },
  s3BucketName: 'my-cache-bucket',
  defaultPolicy: {
    readOrder: ['memory', 's3'],
    writeTargets: ['memory', 's3'],
    promoteOnRead: ['memory'],
    requireWriteSuccess: ['memory', 's3'],
  },
});

Disk Only

const cache = new LevelCache({
  cacheId: 'disk-cache',
  forceLevel: 'disk',
});

S3 Only

const cache = new LevelCache({
  cacheId: 'remote-cache',
  forceLevel: 's3',
  s3Config,
  s3BucketName: 'my-cache-bucket',
});

Cache Entries

const entry = new CacheEntry({
  contents: Buffer.from(JSON.stringify({ ok: true })),
  ttl: 5 * 60 * 1000,
  typeInfo: 'application/json',
});

CacheEntry stores:

Field	Description
`contents`	Required `Buffer` payload
`ttl`	Required time-to-live in milliseconds
`typeInfo`	Optional content type or caller metadata
`key`	Set during storage
`createdAt`	Set during construction/storage
`lastAccessedAt`	Updated by memory reads and writes

Persisted entries are rehydrated with contents as a Buffer.

Constructor Options

Option	Type	Default	Description
`cacheId`	`string`	required	Unique cache namespace
`maxMemoryStorageInMB`	`number`	`0.5`	Memory capacity constraint
`maxDiskStorageInMB`	`number`	`10`	Disk capacity constraint
`maxS3StorageInMB`	`number`	`50`	S3 max-entry constraint; total remote accounting is intentionally conservative
`diskStoragePath`	`string`	package `.nogit`	Disk cache parent directory
`s3Config`	`IStorageDescriptor`	undefined	S3-compatible storage configuration
`s3BucketName`	`string`	undefined	Required for `s3` level activation
`defaultPolicy`	`Partial<ICachePolicy>`	memory-only	Default read/write/promote policy
`forceLevel`	`'memory' \| 'disk' \| 's3'`	undefined	Shorthand for single-level read/write behavior
`immutableCache`	`boolean`	`false`	Prevent overwriting existing entries in write targets
`persistentCache`	`boolean`	`false`	Shorthand for memory + disk policy

Public API

storeCacheEntryByKey(key, entry, options?)
retrieveCacheEntryByKey(key, options?)
checkKeyPresence(key, options?)
deleteCacheEntryByKey(key, options?)
cleanOutdated(options?)
cleanAll(options?)
listCacheKeys()
getApproximateSizeInBytes()
getEntryCount()
enforceCapacity()
getStats()
getStatus()

options is ICacheOperationOptions:

interface ICacheOperationOptions {
  policy?: Partial<ICachePolicy>;
  levels?: ('memory' | 'disk' | 's3')[];
}

Use levels to scope maintenance operations such as cleanAll({ levels: ['memory'] }).

cleanOutdated() returns the number of removed entries.

Stats And Status

const stats = cache.getStats();
const status = await cache.getStatus();

Stats include per-level hits, misses, writes, deletes, promotions, evictions, expired entries, corrupt entries, and errors.

Status includes active levels, default policy, approximate size, entry count, and configured max size per level.

Error Handling

Operations throw LevelCacheError for explicit cache errors. Error codes include:

Code	Meaning
`E_CACHE_LEVEL_INACTIVE`	A required level is not configured or active
`E_CACHE_ENTRY_TOO_LARGE`	Entry exceeds a selected level's max entry/capacity constraint
`E_CACHE_ENTRY_CORRUPT`	A persisted cache entry could not be parsed and was removed
`E_CACHE_IMMUTABLE`	`immutableCache` prevented an overwrite
`E_CACHE_INVALID_OPTIONS`	Invalid constructor or operation options
`E_CACHE_WRITE_FAILED`	No selected write target accepted the entry

Notes On S3

The S3 level is initialized lazily: constructing a memory-only cache does not touch S3. Read/write operations use S3 only when the policy, levels, or forceLevel targets s3 and both s3Config and s3BucketName are provided. Maintenance and presence methods initialize S3 when they are scoped to S3 or when broad cleanup is requested.

S3 total size accounting is intentionally conservative to avoid expensive full-cache object downloads during normal writes and status checks. TTL cleanup for S3 is explicit through cleanOutdated().

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@push.rocks/levelcache