or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-find-cache-directory

Finds the common standard cache directory location for Node.js projects

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/find-cache-directory@6.0.x

To install, run

npx @tessl/cli install tessl/npm-find-cache-directory@6.0.0

index.mddocs/

Find Cache Directory

Find Cache Directory locates the standardized cache directory path for Node.js projects following the common pattern adopted by tools like nyc and AVA. It provides a consistent caching solution across different project structures and environments.

Package Information

  • Package Name: find-cache-directory
  • Package Type: npm
  • Language: JavaScript (ESM modules with TypeScript definitions)
  • Installation: npm install find-cache-directory

Core Imports

import findCacheDirectory from "find-cache-directory";

For TypeScript:

import findCacheDirectory, { type Options } from "find-cache-directory";

Basic Usage

import findCacheDirectory from "find-cache-directory";

// Find cache directory for your project
const cacheDir = findCacheDirectory({ name: 'my-app' });
//=> '/user/path/node_modules/.cache/my-app'

// Create the cache directory if it doesn't exist
const cacheDirCreated = findCacheDirectory({ 
  name: 'my-app', 
  create: true 
});

// Specify custom working directory
const customCacheDir = findCacheDirectory({ 
  name: 'my-app',
  cwd: '/path/to/project'
});

// Find common cache directory from multiple files
const filesCacheDir = findCacheDirectory({
  name: 'my-app',
  files: ['/path/to/file1.js', '/path/to/file2.js']
});

Algorithm

The cache directory resolution follows this algorithm:

  1. Environment Variable: Checks CACHE_DIR environment variable (ignores values 'true', 'false', '1', '0')
  2. Project Discovery: Finds the nearest package.json file starting from the working directory
  3. Path Construction: Returns {projectRoot}/node_modules/.cache/{name}
  4. Permission Validation: Ensures the cache directory location is writable
  5. Optional Creation: Creates directory if create: true option is specified

Capabilities

Find Cache Directory

The main function that locates or creates a standardized cache directory path.

/**
 * Finds the cache directory using the given options.
 * 
 * The algorithm checks for the CACHE_DIR environmental variable and uses it 
 * if it is not set to 'true', 'false', '1' or '0'. If one is not found, it 
 * tries to find a package.json file, searching every parent directory of the 
 * cwd specified (or implied from other options). It returns a string containing 
 * the absolute path to the cache directory, or undefined if package.json was 
 * never found or if the node_modules directory is unwritable.
 * 
 * @param options - Configuration options for cache directory resolution
 * @returns Absolute path to cache directory or undefined if not resolvable
 */
export default function findCacheDirectory(options: Options): string | undefined;

Types

interface Options {
  /**
   * Should be the same as your project name in package.json.
   * Used as the subdirectory name within .cache/
   */
  readonly name: string;

  /**
   * An array of files that will be searched for a common parent directory.
   * This common parent directory will be used in lieu of the cwd option below.
   */
  readonly files?: string[];

  /**
   * The directory to start searching for a package.json from.
   * 
   * @default process.cwd()
   */
  readonly cwd?: string;

  /**
   * Create the directory synchronously before returning.
   * 
   * @default false
   */
  readonly create?: boolean;
}

Environment Variables

  • CACHE_DIR: When set to a directory path (not 'true', 'false', '1', '0'), overrides the default cache location algorithm. The cache directory will be ${CACHE_DIR}/${name}.

Error Handling

The function handles errors gracefully:

  • TypeError: Thrown if files option is provided but is not an array
  • Returns undefined when:
    • No package.json file is found in the directory tree
    • The node_modules directory is not writable
    • Directory permissions prevent access to the cache location

Usage Examples

Testing with Custom Cache Directory

// Set environment variable for testing
process.env.CACHE_DIR = '/tmp/test-cache';
const testCacheDir = findCacheDirectory({ name: 'test-app' });
//=> '/tmp/test-cache/test-app'

Working with Multiple Files

// Find common parent directory for multiple files
const files = [
  '/project/src/component1.js',
  '/project/src/component2.js',
  '/project/tests/test1.js'
];

const cacheDir = findCacheDirectory({
  name: 'build-cache',
  files: files
});
//=> '/project/node_modules/.cache/build-cache'

Creating Cache Directory

// Ensure cache directory exists
const cacheDir = findCacheDirectory({
  name: 'my-tool',
  create: true  // Creates directory if it doesn't exist
});

if (cacheDir) {
  // Cache directory is ready to use
  console.log(`Cache directory: ${cacheDir}`);
} else {
  console.log('Could not resolve cache directory');
}