fs-memo-async

Persistent async function memoization for Node.js using the filesystem.

What is it?

fs-memo-async is a TypeScript/JavaScript utility for Node.js that allows you to memoize (cache) the results of asynchronous functions to the filesystem. This means that expensive computations or API calls can be cached across process restarts, with full control over serialization, hashing, and storage.

• Persistent: Results are stored in files, not just in memory.
• Customizable: Plug in your own serialization, hashing, or filesystem logic.
• Simple API: Just wrap your async function and get persistent memoization.

Installation

npm install fs-memo-async

Usage

Basic Example

import { FsMemoAsync } from 'fs-memo-async';

const fsMemo = new FsMemoAsync();

async function slowDouble(x: number) {
  // Simulate slow computation
  await new Promise(r => setTimeout(r, 1000));
  return x * 2;
}

const memoizedDouble = fsMemo.memoize(slowDouble, 'double');

(async () => {
  console.time('first');
  console.log(await memoizedDouble(5)); // Slow, computes and caches
  console.timeEnd('first');

  console.time('second');
  console.log(await memoizedDouble(5)); // Fast, loads from cache
  console.timeEnd('second');
})();

Customization

You can customize the cache directory, filesystem module, serialization, parsing, and hashing:

import { FsMemoAsync } from 'fs-memo-async';
import * as fs from 'fs/promises';
import * as crypto from 'crypto';

const fsMemo = new FsMemoAsync({
  cacheDir: '/my/custom/cache',
  fs, // Use your own fs-like module if needed
  stringify: (data) => JSON.stringify(data, null, 2),
  parse: (str) => JSON.parse(str),
  hash: (args) => crypto.createHash('sha256').update(JSON.stringify(args)).digest('hex'),
});

API

new FsMemoAsync(options?)

• cacheDir (string): Directory for cache files. Default: /tmp/nodejs/fs-memo-async
• fs (object): Filesystem module with mkdir, readFile, writeFile. Default: fs.promises
• stringify (function): Function to serialize data. Default: JSON.stringify
• parse (function): Function to parse data. Default: JSON.parse
• hash (function): Function to hash arguments. Default: md5(JSON.stringify(args)) via Node's crypto

fsMemo.memoize(fn, name)

• fn: An async function to memoize.
• name: A string identifier for the function (used as a subdirectory in the cache).

Returns: a new async function with the same signature as fn, but with persistent memoization.

How does it work?

• When you call the memoized function, it computes a hash of the arguments.
• It checks for a file at cacheDir/name/hash.
• If the file exists, it loads and returns the cached result.
• If not, it calls the original function, saves the result, and returns it.
• Each cache file contains:

  {
    "arguments": [...],
    "result": ...,
    "timestamp": 1680000000000
  }

Use Cases

• Caching results of expensive computations.
• Caching API responses between process restarts.
• Sharing cache between multiple Node.js processes (with care).