or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index-management.mdindex.mdlisting.mdreading.mdremoval.mdutilities.mdverification.mdwriting.md
tile.json

tessl/npm-cacache

Fast, fault-tolerant, cross-platform, disk-based, data-agnostic, content-addressable cache.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/cacache@20.0.x

To install, run

npx @tessl/cli install tessl/npm-cacache@20.0.0

index.mddocs/

Cacache

Cacache is a fast, fault-tolerant, cross-platform, disk-based, data-agnostic, content-addressable cache for Node.js. It provides high-performance caching with content integrity verification using Subresource Integrity (SRI) hashes, supports concurrent operations, and offers both key-based and content-based access patterns.

Package Information

  • Package Name: cacache
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install cacache

Core Imports

const cacache = require('cacache');

For ES modules:

import * as cacache from 'cacache';

Basic Usage

const cacache = require('cacache');
const path = require('path');

const cachePath = path.join(__dirname, '.cache');
const key = 'my-unique-key';
const data = 'Hello, cached world!';

// Store data in cache
const integrity = await cacache.put(cachePath, key, data);
console.log('Data cached with integrity:', integrity);

// Retrieve data from cache
const result = await cacache.get(cachePath, key);
console.log('Retrieved data:', result.data.toString());
console.log('Metadata:', result.metadata);
console.log('Integrity:', result.integrity);

// Stream data from cache
const stream = cacache.get.stream(cachePath, key);
stream.pipe(process.stdout);

// Remove data from cache
await cacache.rm.entry(cachePath, key);

Architecture

Cacache is built around several key components:

  • Content Store: Content-addressable storage using SRI hashes for data integrity
  • Key Index: Maps human-readable keys to content integrity hashes
  • Streaming API: Minipass-based streaming for efficient data processing
  • Verification System: Built-in integrity checking and cache maintenance
  • Memoization Layer: Optional in-memory LRU cache for frequently accessed data
  • Concurrent Safety: Safe for concurrent read/write operations across processes

Capabilities

Reading Operations

Core functionality for retrieving data from the cache by key or content hash, with support for streaming, direct file copying, metadata inspection, and content existence checking.

// Get cached data by key
function get(cache, key, opts = {}) => Promise<{data: Buffer, metadata: object, integrity: string, size: number}>;

// Get cached data by content integrity hash  
function get.byDigest(cache, integrity, opts = {}) => Promise<Buffer>;

// Get readable stream for cached data by key
function get.stream(cache, key, opts = {}) => ReadableStream;

// Get readable stream for cached data by integrity hash
function get.stream.byDigest(cache, integrity, opts = {}) => ReadableStream;

// Get entry information without fetching content
function get.info(cache, key, opts = {}) => Promise<EntryObject|null>;

// Copy cached content to destination file by key
function get.copy(cache, key, dest, opts = {}) => Promise<{metadata: object, size: number, integrity: string}>;

// Copy cached content to destination file by integrity hash
function get.copy.byDigest(cache, integrity, dest, opts = {}) => Promise<string>;

// Check if content exists for integrity hash
function get.hasContent(cache, integrity) => Promise<boolean>;

Reading Operations

Writing Operations

Functionality for storing data in the cache with automatic integrity hash generation and metadata support.

// Store data in cache
function put(cache, key, data, opts = {}) => Promise<string>;

// Get writable stream for storing data
function put.stream(cache, key, opts = {}) => WritableStream;

Writing Operations

Removal Operations

Operations for removing cached data, either by key or by content hash, including full cache cleanup.

// Remove cache entry by key
function rm.entry(cache, key, opts) => Promise<void>;

// Remove cached content by integrity hash
function rm.content(cache, integrity) => Promise<void>;

// Remove entire cache contents
function rm.all(cache) => Promise<void>;

Removal Operations

Listing Operations

Functionality for discovering and enumerating cache contents.

// List all cache entries
function ls(cache) => Promise<{[key: string]: EntryObject}>;

// Stream all cache entries
function ls.stream(cache) => ReadableStream;

Listing Operations

Index Management

Low-level operations for managing the cache index structure.

// Compact index by removing duplicates
function index.compact(cache, key, matchFn, opts = {}) => Promise<EntryObject[]>;

// Insert entry into index
function index.insert(cache, key, integrity, opts = {}) => Promise<EntryObject>;

Index Management

Verification and Maintenance

Cache integrity verification and maintenance operations.

// Verify and repair cache integrity
function verify(cache, opts) => Promise<VerifyStats>;

// Get timestamp of last verification
function verify.lastRun(cache) => Promise<Date>;

Verification

Utilities

Additional utilities for cache operations including memoization and temporary directories.

// Clear in-memory cache
function clearMemoized() => object;

// Create temporary directory in cache
function tmp.mkdir(cache, opts = {}) => Promise<string>;

// Execute callback with temporary directory
function tmp.withTmp(cache, opts, cb) => Promise<any>;

Utilities

Core Types

// Cache entry object
interface EntryObject {
  key: string;           // Cache key
  integrity: string;     // SRI integrity hash
  path: string;          // File system path to content
  size: number;          // Content size in bytes
  time: number;          // Timestamp (milliseconds since epoch)
  metadata: object;      // User-defined metadata
}

// Common options for cache operations
interface CacheOptions {
  algorithms?: string[];     // Hash algorithms (default: ['sha512'])
  integrity?: string;        // Expected integrity hash for verification
  metadata?: object;         // User-defined metadata
  memoize?: boolean | object; // Enable memoization
  size?: number;            // Expected content size for verification
  time?: number;            // Custom timestamp
}

// Verification statistics
interface VerifyStats {
  startTime: Date;
  endTime: Date;
  runTime: {
    total: number;
    [stepName: string]: number;
  };
  verifiedContent: number;
  reclaimedCount: number;
  reclaimedSize: number;
  badContentCount: number;
  keptSize: number;
  missingContent: number;
  rejectedEntries: number;
  totalEntries: number;
}

// Custom error for missing entries
class NotFoundError extends Error {
  code: 'ENOENT';
  cache: string;
  key: string;
}