Registry / storage / simple-on-disk-cache

simple-on-disk-cache

library1.7.6jsnpmunverified

A lightweight on-disk caching library for Node.js (v1.7.6) supporting locally mounted filesystems and remote filesystems like AWS S3. It provides time-based expiration policies with configurable default and per-item TTL. The library is ESM-only, ships TypeScript type definitions, and is actively maintained with a simple API. Alternatives like node-cache-manager or lru-cache offer in-memory or more complex caching, while this package focuses on simplicity and filesystem persistence.

storage

npm install simple-on-disk-cache

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SIMPLE-ON-DISK-CAC

simple-on-disk-cache

storagejavascriptv1.7.6

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.

createCache

✓ import { createCache } from 'simple-on-disk-cache'

✗ const { createCache } = require('simple-on-disk-cache')

The package is ESM-only and does not support CommonJS require. Will throw if used with require().

createCache

✓ import { createCache } from 'simple-on-disk-cache'

✗ import createCache from 'simple-on-disk-cache'

The default export is not available; you must use named import.

type CacheEntry

✓ import type { CacheEntry } from 'simple-on-disk-cache'

✗ import { CacheEntry } from 'simple-on-disk-cache'

CacheEntry is exported as a type, not a value. Use 'import type' for TypeScript.

Demonstrates creating a cache on a locally mounted filesystem, setting and getting a value, and using custom expiration.

import { createCache } from 'simple-on-disk-cache'; const { set, get } = createCache({ directoryToPersistTo: { mounted: { path: `${__dirname}/tmp`, }, }, }); set('greeting', 'Hello, World!'); const greeting = get('greeting'); console.log(greeting); // 'Hello, World!' // With custom expiration import { createCache } from 'simple-on-disk-cache'; const { set: set2, get: get2 } = createCache({ directoryToPersistTo: { mounted: { path: `${__dirname}/tmp` }, }, defaultSecondsUntilExpiration: 600, // 10 minutes }); set2('key', 'value', { secondsUntilExpiration: Infinity }); // never expire const value = get2('key'); console.log(value); // 'value'

Debug

Known issues

gotchaThe cache directory must already exist. createCache does not create the directory automatically.

fix

Create the directory before calling createCache, e.g., with fs.mkdirSync.

affects: >=1.0.0

gotchaCache entries are serialized with JSON.stringify, which cannot serialize functions, undefined, or circular references.

fix

Only store JSON-serializable values.

affects: >=1.0.0

gotchaThe get method returns undefined for expired or missing entries, not null. TypeScript strict null checks may require handling undefined explicitly.

fix

Check for undefined: const result = get('key'); if (result === undefined) { /* not found or expired */ }

affects: >=1.0.0

gotchaThe S3 configuration requires AWS credentials to be set in environment variables or ~/.aws/credentials. It does not accept explicit credentials in the config.

fix

Ensure AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and optionally AWS_REGION are available.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot destructure property 'set' of (intermediate value)(...) as it is undefined.

Using CommonJS require with ESM-only package.

fix

Use import { createCache } from 'simple-on-disk-cache' instead of require.

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

The directory specified in directoryToPersistTo.mounted.path does not exist.

fix

Create the directory before creating the cache, e.g., with fs.mkdirSync('/path/to/dir', { recursive: true }).

TypeError: Converting circular structure to JSON

Attempting to cache an object with circular references.

fix

Ensure the value is JSON-serializable. Avoid storing functions or objects with circular references.

CredentialsError: Missing credentials in config

AWS credentials not configured for S3 cache.

fix

Set environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, or configure AWS CLI with aws configure.

Upgrade

Version history

1.7.6latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

19 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/ehmpathy/simple-on-disk-cache ↗

packagesimple-on-disk-cache ↗

homepagehttps://github.com/ehmpathy/simple-on-disk-cache ↗