Simple File-Based Cache

1.0.2 verified Sat Apr 25 auth: no javascript abandoned

node-file-cache is a straightforward, file-based caching module for Node.js, currently at version 1.0.2. It leverages `lowdb` for persistent storage, allowing developers to store key-value pairs with optional lifespans and tags for granular expiry. Its design emphasizes simplicity over advanced features or high-throughput performance. Given its age and the explicit mention of Node.js 4.4.5 as a minimum requirement (a version from 2016), it appears to be an unmaintained package with an irregular or non-existent release cadence. It's best suited for small-scale applications where a simple, durable, local cache is sufficient and high concurrency or complex cache invalidation strategies are not required.

Common errors

error TypeError: (0, _nodeFileCache.create) is not a function ↓

cause Attempting to use ES module `import` syntax (`import { create } from 'node-file-cache';`) with this CommonJS-only package.

fix

Change your import statement to const cache = require('node-file-cache').create();

error ReferenceError: require is not defined ↓

cause Attempting to use `require()` in an ES module context (`'type': 'module'` in package.json or `.mjs` file).

fix

This package is not compatible with pure ES module environments. You would either need to transpile your code, convert your project to CommonJS, or use a different caching library that supports ES modules.

error Error: Cannot find module 'node-file-cache' ↓

cause The package `node-file-cache` has not been installed or is not resolvable from the current working directory.

fix

Run npm install node-file-cache --save in your project directory.

Warnings

breaking The module explicitly requires Node.js version 4.4.5 or higher due to its use of ES6 features. Running it on significantly older Node.js versions will result in syntax errors. ↓

fix Upgrade Node.js to at least version 4.4.5. However, due to the package's age, it's recommended to use a modern caching solution for current Node.js applications.

gotcha This package appears to be unmaintained. The README states 'Since the github repository is not ready yet', implying it was never actively hosted or updated for a long period. This means no bug fixes, security patches, or compatibility updates for newer Node.js versions. ↓

fix Evaluate modern, actively maintained caching libraries (e.g., `node-cache`, `cache-manager`, `ioredis` for Redis-based) for new projects or when migrating existing applications.

gotcha Being a file-based cache using `lowdb`, `node-file-cache` may not be suitable for high-concurrency environments or applications requiring high performance. Concurrent writes could lead to race conditions, data corruption, or significant I/O bottlenecks. ↓

fix For high-performance or concurrent caching needs, consider in-memory caches or external cache services like Redis or Memcached.

gotcha The package only supports CommonJS `require()` syntax. Attempting to import it using ES module `import` statements will result in runtime errors. ↓

fix Always use `const cache = require('node-file-cache').create();` to import and instantiate the cache module.

Install

npm install node-file-cache

yarn add node-file-cache

pnpm add node-file-cache

Imports

create

wrong

import { create } from 'node-file-cache'; // Not supported, CommonJS only

correct

const cache = require('node-file-cache').create();

The module exports a `create` factory function directly from the `require` call. It does not support ES modules.

createWithOptions

wrong

const { create } = require('node-file-cache')(); // Incorrect destructuring and invocation, `create` is a function itself

correct

const cache = require('node-file-cache').create({ file: 'my-cache.json', life: 7200 });

Configuration options are passed directly to the `create` factory function upon instantiation.

CacheInstance

wrong

const cache = require('node-file-cache');
cache.set('key', 'value'); // Missing the .create() invocation to get an instance

correct

const cache = require('node-file-cache').create();
cache.set('key', 'value');

The `require` call itself does not return the cache instance; you must call the `create()` method on the result.

Quickstart

Demonstrates initializing the cache, setting a record with options (lifespan, tags), retrieving it, and then explicitly expiring it by key.

const cache = require('node-file-cache').create(); // default configuration

const key = 'my-cache-key';
const item = {
    name: 'my cache item'
};
const options = {
    life: 60,   // set lifespan of one minute
    tags: [ 'my-cache-tag', 'another-tag' ]
};

cache.set(key, item, options);

const cachedItem = cache.get(key); // depending on context this can either return cached data or null

if (cachedItem) {
    console.log(`Cached item: ${cachedItem.name}`);
}

// To demonstrate removal
setTimeout(() => {
    cache.expire(key); // removes item with particular key
    console.log(`Cache size after expiry: ${cache.size()}`);
}, 1000); // Wait a bit to ensure async operation completes and cache is still there before expiry