@sunacchi/cache-kit-fs

Filesystem cache adapter for @sunacchi/cache-kit. Stores each cache entry as an individual file on disk.

Part of the Cache Kit monorepo.

Install

npm install @sunacchi/cache-kit @sunacchi/cache-kit-fs

Usage

import { Cache } from '@sunacchi/cache-kit';
import { FsAdapter } from '@sunacchi/cache-kit-fs';

const cache = new Cache<string>({
  adapter: new FsAdapter({ directory: './.cache' }),
  defaultTtl: 300_000, // 5 minutes
});

await cache.set('config', JSON.stringify({ theme: 'dark' }));
const config = await cache.get('config');

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | directory | string | (required) | Path to the directory where cache files are stored. Created automatically if it doesn't exist. | | extension | string | '.cache' | File extension for cache files. |

const adapter = new FsAdapter({
  directory: './data/cache',
  extension: '.json', // use .json instead of .cache
});

How It Works

• Each key is stored as a separate file: <URL-encoded key><extension>
• The directory is created automatically on first use (mkdir -p)
• Keys with special characters (slashes, colons, unicode) are safely URL-encoded in filenames
• clear() removes and recreates the directory
• All operations are async using node:fs/promises

Supported Runtimes

| Runtime | Status | |---------|--------| | Node.js | Supported | | Bun | Supported | | Deno | Supported (v1.28+ with npm compatibility) |

Example

import { Cache } from '@sunacchi/cache-kit';
import { FsAdapter } from '@sunacchi/cache-kit-fs';

const cache = new Cache<Record<string, unknown>>({
  adapter: new FsAdapter({ directory: './.cache/api-responses' }),
  defaultTtl: 60_000,
  maxSize: 100,
  eviction: 'fifo',
});

const data = await cache.getOrCreate('weather:london', async () => {
  const res = await fetch('https://api.example.com/weather/london');
  return await res.json();
}, { ttl: 120_000 });

Exports

export { FsAdapter } from './fs-adapter.js';
export type { FsAdapterOptions } from './fs-adapter.js';

License

MIT