Registry / storage / dirt-simple-file-cache

dirt-simple-file-cache

library0.4.0jsnpmunverified

A lightweight file caching library that uses file modification times (mtime) to determine cache staleness. Current stable version is 0.4.0, released occasionally with minimal maintenance. It provides both persistent file-based caching and optional in-memory caching. Differentiators: dirt-simple API with just init, add, get, and clear methods; uses OS temp directory for persistence; TypeScript typings included. Ideal for simple build tool caches or any scenario where fast, zero-config file caching is needed.

storage

npm install dirt-simple-file-cache

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DIRT-SIMPLE-FILE-C

dirt-simple-file-cache

storagejavascriptv0.4.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

DirtSimpleFileCache

✓ import { DirtSimpleFileCache } from 'dirt-simple-file-cache'

✗ const DirtSimpleFileCache = require('dirt-simple-file-cache')

Package exports a class; named import required. CJS require would give an object, not the class directly.

DirtSimpleFileCache

✓ const { DirtSimpleFileCache } = require('dirt-simple-file-cache')

✗ const DirtSimpleFileCache = require('dirt-simple-file-cache').default

For CJS, destructure the class from the exports object. There is no default export.

DirtSimpleFileCache

✓ import type { DirtSimpleFileCache } from 'dirt-simple-file-cache'

Type import is valid for TypeScript, but the class is also a value, so both type and value imports are fine.

Initializes a cache instance, adds an entry, retrieves it, and verifies missed cache returns null.

import path from 'path'; import { strict as assert } from 'assert'; import { DirtSimpleFileCache } from 'dirt-simple-file-cache'; async function example() { const cacheDir = '/tmp/my-cache'; // Or use project root const cache = await DirtSimpleFileCache.init(cacheDir); await cache.clear(); const filePath = path.join(cacheDir, 'test.txt'); const data = 'cached content'; cache.add(filePath, data); const retrieved = cache.get(filePath); assert(retrieved === data); const missing = cache.get('/nonexistent'); assert(missing == null); } example().catch(console.error);

Debug

Known issues

gotchaIn-memory cache does not check for staleness; file cache uses mtime but may be slower.

fix

Do not use keepInMemoryCache if source files may change during runtime. For correctness, always use file-based cache.

affects: >=0.0.0

gotchaCache persists to a tmp folder by default, not configurable via init; uses os.tmpdir().

fix

If you need a custom cache directory, pass a specific root path to init (e.g., projectRoot). The library uses that root directory for caching.

affects: 0.4.0

gotchaclear() is async; failing to await it may leave stale data.

fix

Always await cache.clear() in async contexts.

affects: >=0.0.0

deprecatedNo major deprecations known; library is simple and stable.

fix

N/A

affects: 0.4.0

Errors

Common errors & fixes

TypeError: DirtSimpleFileCache is not a constructor

Incorrect import or require; CJS require gave an object without destructuring.

fix

Use const { DirtSimpleFileCache } = require('dirt-simple-file-cache') or import { DirtSimpleFileCache } from 'dirt-simple-file-cache'

TypeError: Cannot read properties of undefined (reading 'get')

Forgetting to await init() or calling get on uninitialized instance.

fix

Ensure cache = await DirtSimpleFileCache.init(...) before using get/add/clear.

Error: ENOENT: no such file or directory, open '...'

The cache directory does not exist or permissions issue.

fix

Ensure the directory passed to init exists and is writable. The library does not create intermediate directories automatically.

Upgrade

Version history

0.4.0latest on npm

Audit

Dependencies

fsoptionalFile system operations for reading/writing cache and checking mtime

pathoptionalPath manipulation for cache file paths

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubssh://git@github.com/thlorenz/dirt-simple-file-cache ↗

packagedirt-simple-file-cache ↗

homepagehttps://github.com/thlorenz/dirt-simple-file-cache#readme ↗