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

reading.mddocs/

Reading Operations

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

Capabilities

Get Data by Key

Retrieves cached data by key, returning data along with metadata and integrity information.

/**
 * Retrieves cached data by key
 * @param {string} cache - Path to cache directory
 * @param {string} key - Cache key to retrieve
 * @param {object} opts - Options object
 * @param {string} [opts.integrity] - Expected integrity hash for verification
 * @param {boolean|object} [opts.memoize] - Enable memoization (default: true)
 * @param {number} [opts.size] - Expected content size for verification
 * @returns {Promise<object>} Promise resolving to {data, metadata, integrity, size}
 */
function get(cache, key, opts = {});

Usage Examples:

const cacache = require('cacache');

// Basic retrieval
const result = await cacache.get('./cache', 'my-key');
console.log(result.data.toString());
console.log(result.metadata);
console.log(result.integrity);
console.log(result.size);

// With verification
const result = await cacache.get('./cache', 'my-key', {
  integrity: 'sha512-abc123...',
  size: 1024
});

// Without memoization
const result = await cacache.get('./cache', 'my-key', {
  memoize: false
});

Get Data by Content Hash

Retrieves cached data directly by content integrity hash, bypassing the key index.

/**
 * Retrieves cached data by content integrity hash
 * @param {string} cache - Path to cache directory
 * @param {string} integrity - Content integrity hash (SRI format)
 * @param {object} opts - Options object
 * @param {string} [opts.integrity] - Additional integrity hash for verification
 * @param {boolean|object} [opts.memoize] - Enable memoization (default: true)  
 * @param {number} [opts.size] - Expected content size for verification
 * @returns {Promise<Buffer>} Promise resolving to content data
 */
function get.byDigest(cache, integrity, opts = {});

Usage Examples:

// Direct content retrieval by hash
const data = await cacache.get.byDigest('./cache', 'sha512-abc123...');
console.log(data.toString());

// With size verification
const data = await cacache.get.byDigest('./cache', 'sha512-abc123...', {
  size: 1024
});

Stream Data by Key

Returns a readable stream for cached data by key, with events for metadata and integrity information.

/**
 * Returns readable stream for cached data by key
 * @param {string} cache - Path to cache directory
 * @param {string} key - Cache key to retrieve
 * @param {object} opts - Options object
 * @param {boolean|object} [opts.memoize] - Enable memoization (default: true)
 * @param {number} [opts.size] - Expected content size for verification
 * @returns {ReadableStream} Readable stream with events: metadata, integrity, size
 */
function get.stream(cache, key, opts = {});

The returned stream emits the following events:

  • metadata - Entry metadata object
  • integrity - Content integrity hash
  • size - Content size in bytes
  • error - Error if retrieval fails

Usage Examples:

const fs = require('fs');

// Stream to file
const stream = cacache.get.stream('./cache', 'my-key');
stream.pipe(fs.createWriteStream('./output.txt'));

// Listen for metadata
const stream = cacache.get.stream('./cache', 'my-key');
stream.on('metadata', (metadata) => {
  console.log('Entry metadata:', metadata);
});
stream.on('integrity', (integrity) => {
  console.log('Content integrity:', integrity);
});
stream.on('size', (size) => {
  console.log('Content size:', size);
});

// Collect stream data
const { PassThrough } = require('stream');
const collect = require('minipass-collect');

const stream = cacache.get.stream('./cache', 'my-key');
const data = await stream.collect();
console.log(data.toString());

Stream Data by Content Hash

Returns a readable stream for cached data by content integrity hash.

/**
 * Returns readable stream for cached data by integrity hash
 * @param {string} cache - Path to cache directory
 * @param {string} integrity - Content integrity hash (SRI format)
 * @param {object} opts - Options object
 * @param {boolean|object} [opts.memoize] - Enable memoization (default: true)
 * @returns {ReadableStream} Readable stream of content data
 */
function get.stream.byDigest(cache, integrity, opts = {});

Usage Examples:

// Stream content by hash
const stream = cacache.get.stream.byDigest('./cache', 'sha512-abc123...');
stream.pipe(process.stdout);

// With custom memoization
const customCache = new Map();
const stream = cacache.get.stream.byDigest('./cache', 'sha512-abc123...', {
  memoize: customCache
});

Copy Data to File by Key

Copies cached content directly to a destination file by key, without loading into memory.

/**
 * Copies cached content to destination file by key
 * @param {string} cache - Path to cache directory
 * @param {string} key - Cache key to copy
 * @param {string} dest - Destination file path
 * @param {object} opts - Options object
 * @returns {Promise<object>} Promise resolving to {metadata, size, integrity}
 */
function get.copy(cache, key, dest, opts = {});

Usage Examples:

// Copy cached file
const result = await cacache.get.copy('./cache', 'my-key', './output.txt');
console.log('Copied file with integrity:', result.integrity);
console.log('File size:', result.size);

// Access metadata
console.log('Original metadata:', result.metadata);

Copy Data to File by Content Hash

Copies cached content directly to a destination file by content integrity hash.

/**
 * Copies cached content to destination file by integrity hash
 * @param {string} cache - Path to cache directory
 * @param {string} integrity - Content integrity hash (SRI format)
 * @param {string} dest - Destination file path
 * @param {object} opts - Options object
 * @returns {Promise<string>} Promise resolving to the integrity hash
 */
function get.copy.byDigest(cache, integrity, dest, opts = {});

Usage Examples:

// Copy by content hash
const integrity = await cacache.get.copy.byDigest(
  './cache', 
  'sha512-abc123...', 
  './output.txt'
);
console.log('Copied content with integrity:', integrity);

Get Entry Information

Retrieves metadata and information about a cache entry without fetching the actual content.

/**
 * Gets metadata about a cache entry
 * @param {string} cache - Path to cache directory
 * @param {string} key - Cache key to inspect
 * @param {object} opts - Options object
 * @param {boolean|object} [opts.memoize] - Enable memoization lookup
 * @returns {Promise<EntryObject|null>} Promise resolving to entry object or null if not found
 */
function get.info(cache, key, opts = {});

Usage Examples:

// Get entry info
const info = await cacache.get.info('./cache', 'my-key');
if (info) {
  console.log('Key:', info.key);
  console.log('Integrity:', info.integrity);
  console.log('Size:', info.size);
  console.log('Timestamp:', new Date(info.time));
  console.log('Metadata:', info.metadata);
  console.log('Content path:', info.path);
} else {
  console.log('Entry not found');
}

Check Content Existence

Checks if content exists for a given integrity hash without retrieving it.

/**
 * Checks if content exists for integrity hash
 * @param {string} cache - Path to cache directory
 * @param {string} integrity - Content integrity hash (SRI format)
 * @returns {Promise<boolean>} Promise resolving to true if content exists
 */
function get.hasContent(cache, integrity);

Usage Examples:

// Check if content exists
const exists = await cacache.get.hasContent('./cache', 'sha512-abc123...');
if (exists) {
  console.log('Content is available in cache');
} else {
  console.log('Content not found in cache');
}

// Use before attempting retrieval
if (await cacache.get.hasContent('./cache', integrity)) {
  const data = await cacache.get.byDigest('./cache', integrity);
  console.log('Retrieved data:', data.toString());
}

Error Handling

Reading operations may throw the following errors:

  • NotFoundError - When a cache entry or content is not found
  • IntegrityError - When content fails integrity verification
  • SizeError - When content size doesn't match expected size
  • Standard filesystem errors (ENOENT, EACCES, etc.)
try {
  const result = await cacache.get('./cache', 'nonexistent-key');
} catch (error) {
  if (error.code === 'ENOENT') {
    console.log('Cache entry not found');
  } else {
    console.error('Unexpected error:', error);
  }
}