or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cache-operations.mdconfiguration.mderror-handling.mdindex.md
tile.json

tessl/npm-actions--cache

Functions necessary for caching dependencies and build outputs to improve workflow execution time

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@actions/cache@4.0.x

To install, run

npx @tessl/cli install tessl/npm-actions--cache@4.0.0

index.mddocs/

Actions Cache

Actions Cache provides essential caching functionality for GitHub Actions workflows, enabling developers to cache dependencies and build outputs to significantly improve workflow execution time. It offers functions for saving and restoring caches using keys and restore keys, with automatic compression using zstandard or gzip algorithms.

Package Information

  • Package Name: @actions/cache
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @actions/cache

Core Imports

import { 
  restoreCache, 
  saveCache, 
  isFeatureAvailable,
  getUploadOptions,
  getDownloadOptions,
  ValidationError,
  ReserveCacheError,
  type UploadOptions,
  type DownloadOptions
} from '@actions/cache';

For CommonJS:

const { 
  restoreCache, 
  saveCache, 
  isFeatureAvailable,
  getUploadOptions,
  getDownloadOptions,
  ValidationError,
  ReserveCacheError
} = require('@actions/cache');

Basic Usage

import { restoreCache, saveCache } from '@actions/cache';

// Define paths and cache key
const paths = [
  'node_modules',
  'packages/*/node_modules/'
];
const key = 'npm-deps-' + hashFiles('**/package-lock.json');
const restoreKeys = [
  'npm-deps-',
  'npm-'
];

// Restore cache if it exists
const cacheKey = await restoreCache(paths, key, restoreKeys);
if (cacheKey) {
  console.log(`Cache restored from key: ${cacheKey}`);
} else {
  console.log('No cache found');
}

// Install dependencies if cache miss
if (!cacheKey) {
  // ... run npm install or similar
  
  // Save cache for future runs
  const cacheId = await saveCache(paths, key);
  console.log(`Cache saved with ID: ${cacheId}`);
}

Architecture

Actions Cache is built around several key components:

  • Cache Service Integration: Supports both legacy (v1) and new (v2) GitHub cache services with automatic version detection
  • Compression: Automatic compression using zstandard (preferred) or gzip algorithms for optimal storage
  • Cross-Platform Support: Enables caches created on one OS to be restored on different platforms
  • Segmented Downloads: Large caches are downloaded in segments with timeout protection to prevent stuck workflows
  • Azure SDK Integration: Uses Azure Blob Storage SDK for improved reliability and performance in v2 service

Capabilities

Cache Operations

Core cache functionality for saving and restoring files using GitHub's caching service.

function restoreCache(
  paths: string[],
  primaryKey: string,
  restoreKeys?: string[],
  options?: DownloadOptions,
  enableCrossOsArchive?: boolean = false
): Promise<string | undefined>;

function saveCache(
  paths: string[],
  key: string,
  options?: UploadOptions,
  enableCrossOsArchive?: boolean = false
): Promise<number>;

function isFeatureAvailable(): boolean;

Cache Operations

Configuration Options

Upload and download options for controlling cache behavior, compression, timeouts, and Azure SDK usage.

interface UploadOptions {
  useAzureSdk?: boolean;
  uploadConcurrency?: number;
  uploadChunkSize?: number;
  archiveSizeBytes?: number;
}

interface DownloadOptions {
  useAzureSdk?: boolean;
  downloadConcurrency?: number;
  concurrentBlobDownloads?: boolean;
  timeoutInMs?: number;
  segmentTimeoutInMs?: number;
  lookupOnly?: boolean;
}

function getUploadOptions(copy?: UploadOptions): UploadOptions;
function getDownloadOptions(copy?: DownloadOptions): DownloadOptions;

Configuration Options

Error Handling

Custom error types for validation failures and cache reservation conflicts.

class ValidationError extends Error {
  constructor(message: string);
}

class ReserveCacheError extends Error {
  constructor(message: string);
}

Error Handling

Constants and Enums

enum CompressionMethod {
  Gzip = 'gzip',
  ZstdWithoutLong = 'zstd-without-long',
  Zstd = 'zstd'
}

enum CacheFilename {
  Gzip = 'cache.tgz',
  Zstd = 'cache.tzst'
}

enum ArchiveToolType {
  GNU = 'gnu',
  BSD = 'bsd'
}

const CacheFileSizeLimit = 10737418240; // 10 * Math.pow(1024, 3) - 10GiB per repository
const DefaultRetryAttempts = 2;
const DefaultRetryDelay = 5000; // 5000ms
const SocketTimeout = 5000; // 5000ms
const TarFilename = 'cache.tar';
const ManifestFilename = 'manifest.txt';