Find Cache DirAPI Reference

API Reference

Complete API documentation for @visulima/find-cache-dir

Last updated:

API Reference

Complete reference for all functions in the @visulima/find-cache-dir package.

Functions

findCacheDir

Find the cache directory asynchronously.

Signature:

function findCacheDir(name: string, options?: Options): Promise<string | undefined>

Parameters:

  • name (string, required) - Application name (should match your package name)
  • options (Options, optional) - Configuration options

Returns: Promise<string | undefined> - Path to cache directory, or undefined if not found

Example:

import { findCacheDir } from "@visulima/find-cache-dir";

const cacheDir = await findCacheDir("my-app");
console.log(cacheDir);
// macOS: /Users/username/Library/Caches/my-app
// Linux: /home/username/.cache/my-app
// Windows: C:\Users\username\AppData\Local\my-app

findCacheDirSync

Find the cache directory synchronously.

Signature:

function findCacheDirSync(name: string, options?: Options): string | undefined

Parameters:

  • name (string, required) - Application name (should match your package name)
  • options (Options, optional) - Configuration options

Returns: string | undefined - Path to cache directory, or undefined if not found

Example:

import { findCacheDirSync } from "@visulima/find-cache-dir";

const cacheDir = findCacheDirSync("my-app");
console.log(cacheDir);

Options

Options Interface

Configuration options for cache directory lookup.

Type Definition:

interface Options {
  cwd?: string;
  create?: boolean;
  throwError?: boolean;
}

Properties:

cwd

Starting directory for searching.

  • Type: string
  • Default: process.cwd()
  • Description: Directory to start searching for package.json

Example:

import { findCacheDir } from "@visulima/find-cache-dir";

const cacheDir = await findCacheDir("my-app", {
  cwd: "/path/to/project"
});

create

Create the directory if it doesn't exist.

  • Type: boolean
  • Default: false
  • Description: Automatically create the cache directory

Example:

import { findCacheDir } from "@visulima/find-cache-dir";

const cacheDir = await findCacheDir("my-app", {
  create: true
});
// Directory is guaranteed to exist

throwError

Throw an error if cache directory not found.

  • Type: boolean
  • Default: false
  • Description: Throw error instead of returning undefined

Example:

import { findCacheDir } from "@visulima/find-cache-dir";

try {
  const cacheDir = await findCacheDir("my-app", {
    throwError: true
  });
  console.log("Found:", cacheDir);
} catch (error) {
  console.error("Cache directory not found");
}

Cache Directory Locations

Platform-Specific Paths

The package finds platform-specific cache directories:

macOS:

~/Library/Caches/<name>
/Users/username/Library/Caches/my-app

Linux:

~/.cache/<name>
/home/username/.cache/my-app

# Or if XDG_CACHE_HOME is set:
$XDG_CACHE_HOME/<name>

Windows:

%LOCALAPPDATA%\<name>
C:\Users\username\AppData\Local\my-app

# Fallback:
%USERPROFILE%\AppData\Local\<name>

Project-Local Cache

If in a Node.js project with node_modules, uses:

<project>/node_modules/.cache/<name>

Environment Variables

CACHE_DIR

Override the cache directory location:

CACHE_DIR=/tmp/custom-cache node script.js
import { findCacheDir } from "@visulima/find-cache-dir";

// Will use /tmp/custom-cache/<name> if CACHE_DIR is set
const cacheDir = await findCacheDir("my-app");

Use Cases:

  • Testing environments
  • CI/CD pipelines
  • Docker containers
  • Custom deployment scenarios

Return Values

Success

Returns absolute path to cache directory:

import { findCacheDir } from "@visulima/find-cache-dir";

const cacheDir = await findCacheDir("my-app");
// "/Users/username/Library/Caches/my-app"

Not Found (default)

Returns undefined if no cache directory found:

import { findCacheDir } from "@visulima/find-cache-dir";

const cacheDir = await findCacheDir("my-app");
if (cacheDir === undefined) {
  console.log("No cache directory available");
}

Not Found (with throwError)

Throws error if cache directory not found:

import { findCacheDir } from "@visulima/find-cache-dir";

try {
  const cacheDir = await findCacheDir("my-app", { throwError: true });
} catch (error) {
  console.error(error.message);
  // "Could not find cache directory"
}

TypeScript Types

Type Exports

import type { Options } from "@visulima/find-cache-dir";

const options: Options = {
  cwd: process.cwd(),
  create: true,
  throwError: false
};

Type Definitions

// Function signatures
type FindCacheDir = (
  name: string,
  options?: Options
) => Promise<string | undefined>;

type FindCacheDirSync = (
  name: string,
  options?: Options
) => string | undefined;

// Options
interface Options {
  cwd?: string;
  create?: boolean;
  throwError?: boolean;
}

Error Handling

Common Error Scenarios

No package.json found:

const cacheDir = await findCacheDir("my-app", { throwError: true });
// Error: Could not find package.json

No cache directory available:

const cacheDir = await findCacheDir("my-app", { throwError: true });
// Error: Could not determine cache directory

Permission denied:

const cacheDir = await findCacheDir("my-app", { create: true });
// Error: EACCES: permission denied

Best Practices

Handle errors gracefully:

import { findCacheDir } from "@visulima/find-cache-dir";
import { tmpdir } from "os";
import { join } from "path";

async function getCacheDir(name: string): Promise<string> {
  try {
    const cacheDir = await findCacheDir(name, { create: true });
    if (cacheDir) return cacheDir;
  } catch (error) {
    console.warn("Failed to find cache directory:", error);
  }

  // Fallback to temp directory
  return join(tmpdir(), name);
}

Function Comparison

Async vs Sync

FeaturefindCacheDirfindCacheDirSync
ExecutionAsync (Promise)Sync (blocking)
Use CaseModern async codeLegacy sync code
PerformanceNon-blockingBlocking
Error Handlingtry/catch or .catch()try/catch

When to use async:

// In async functions
async function build() {
  const cache = await findCacheDir("builder");
  // ...
}

// In Promise chains
findCacheDir("app")
  .then(cache => {
    // Use cache
  });

When to use sync:

// In synchronous initialization
const cache = findCacheDirSync("app");

// In scripts without async context
function setupCache() {
  return findCacheDirSync("tool", { create: true });
}

Next Steps

Usage Guide

Learn how to use the package with examples

Back to Overview

Return to package overview

Edit on GitHub

On this page

API Reference
Functions
findCacheDir
findCacheDirSync
Options
Options Interface
cwd
create
throwError
Cache Directory Locations
Platform-Specific Paths
Project-Local Cache
Environment Variables
CACHE_DIR
Return Values
Success
Not Found (default)
Not Found (with throwError)
TypeScript Types
Type Exports
Type Definitions
Error Handling
Common Error Scenarios
Best Practices
Function Comparison
Async vs Sync
Next Steps
Support

Contribute to our work and keep us going

Community is the heart of open source. The success of our packages wouldn't be possible without the incredible contributions of users, testers, and developers who collaborate with us every day.Want to get involved? Here are some tips on how you can make a meaningful impact on our open source projects.

Ready to help us out?

Be sure to check out the package's contribution guidelines first. They'll walk you through the process on how to properly submit an issue or pull request to our repositories.

Submit a pull request

Found something to improve? Fork the repo, make your changes, and open a PR. We review every contribution and provide feedback to help you get merged.

Good first issues

Simple issues suited for people new to open source development, and often a good place to start working on a package.
View good first issues