or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

Find Cache Dir

Find Cache Dir provides a utility for finding the common standard cache directory location in Node.js projects. It implements the standardized cache directory structure used by popular tools like nyc, AVA, Storybook, and babel-loader, automatically locating the appropriate cache directory and handling directory creation with proper write permission checks.

Package Information

Package Name: find-cache-dir
Package Type: npm
Language: JavaScript (ES Module)
Installation: npm install find-cache-dir

Core Imports

import findCacheDirectory from "find-cache-dir";

For CommonJS projects:

// Note: This package is ES Module only. CommonJS usage requires dynamic import
const { default: findCacheDirectory } = await import("find-cache-dir");

Basic Usage

import findCacheDirectory from "find-cache-dir";

// Basic usage - finds cache directory for your package
const cacheDir = findCacheDirectory({ name: "my-package" });
console.log(cacheDir);
// => "/user/project/node_modules/.cache/my-package"

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

// Override with environment variable
process.env.CACHE_DIR = "/custom/cache";
const cacheDir = findCacheDirectory({ name: "my-package" });
// => "/custom/cache/my-package"

Capabilities

Cache Directory Resolution

Finds the cache directory using the given options, following the standardized cache directory structure.

/**
 * 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 found
 */
function findCacheDirectory(options: Options): string | undefined;

interface Options {
  /** Should be the same as your project name in package.json (required) */
  readonly name: string;
  
  /** 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 */
  readonly files?: string[];
  
  /** 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;
}

Usage Examples:

import findCacheDirectory from "find-cache-dir";

// Basic usage with package name
const cacheDir = findCacheDirectory({ name: "unicorns" });
// => "/user/path/node_modules/.cache/unicorns"

// Search from specific files for common parent
const cacheDir = findCacheDirectory({
  name: "my-tool",
  files: ["src/index.js", "test/test.js", "lib/utils.js"]
});
// Uses common parent directory of the provided files

// Start search from custom directory
const cacheDir = findCacheDirectory({
  name: "my-tool",
  cwd: "/custom/project/path"
});

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

// Environment variable override
process.env.CACHE_DIR = "/tmp/custom-cache";
const cacheDir = findCacheDirectory({ name: "my-tool" });
// => "/tmp/custom-cache/my-tool"

Algorithm Details

The cache directory resolution follows this algorithm:

Environment Variable Check: If CACHE_DIR environment variable is set and not equal to 'true', 'false', '1', or '0', uses $CACHE_DIR/{name} as the cache directory
Working Directory Resolution: Determines the working directory from:
- Common parent directory of files array (if provided)
- cwd option (if provided)
- process.cwd() (default)
Package Directory Search: Searches upward from working directory to find nearest package.json file
Node Modules Validation: Checks that node_modules directory exists or can be created with write permissions
Cache Path Construction: Returns {packageDir}/node_modules/.cache/{name}

Error Handling

// Function throws TypeError for invalid files option
// Returns undefined for various failure conditions:
// - No package.json found in parent directories
// - node_modules directory is not writable
// - node_modules cannot be created due to permissions

The function throws a TypeError if the files option is provided but is not an array, with the message: Expected \files` option to be an array, got `${typeof files}`.. It returns undefined` (rather than throwing) when:

No package.json file is found by searching parent directories
The node_modules directory exists but is not writable
The node_modules directory doesn't exist and cannot be created due to permissions

Environment Variables

// CACHE_DIR: Override cache directory location
// Ignored if set to 'true', 'false', '1', or '0'

The CACHE_DIR environment variable provides a way to override the cache directory location. When set to a valid path (not 'true', 'false', '1', or '0'), the function will use $CACHE_DIR/{name} as the cache directory instead of the standard node_modules/.cache/{name} location.

Types

interface Options {
  readonly name: string;
  readonly files?: string[];
  readonly cwd?: string;
  readonly create?: boolean;
}