flat-cache

library6.1.22jsnpmunverified

A simple key/value cache that persists data to files, backed by an in-memory cache (CacheableMemory). Version 6.1.22 is the current stable release. Part of the Cacheable ecosystem, it combines in-memory speed with file persistence, supporting TTL, LRU eviction, expiration intervals, and automatic save intervals. Replaces the v5 prune method with built-in eviction from CacheableMemory. Ships ESM and CommonJS with TypeScript typings. Notable changes in v6: removed global functions (use imports), replaced prune with ttl/lruSize, changed save() behavior (no longer needs prune option), and introduced new options like serialize/deserialize.

storage

npm install flat-cache

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FLAT-CACHE

flat-cache

storagejavascriptv6.1.22

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.

FlatCache

✓ import { FlatCache } from 'flat-cache'

✗ const FlatCache = require('flat-cache')

ESM import is preferred. CommonJS require is still supported but may not use named exports correctly in all bundlers.

createFromFile

✓ import { createFromFile } from 'flat-cache'

✗ import createFromFile from 'flat-cache'

createFromFile is a named export, not default. In v6 it replaces the old global createFromFile function.

FlatCacheOptions

✓ import { FlatCacheOptions } from 'flat-cache'

✗ import FlatCacheOptions from 'flat-cache'

Type import for TypeScript. Not a runtime value.

Creates a FlatCache with TTL, LRU, expiration check, and persistence at intervals. Sets, gets, and removes a value.

import { FlatCache } from 'flat-cache'; const cache = new FlatCache({ ttl: 60 * 60 * 1000, // 1 hour lruSize: 10000, expirationInterval: 5 * 60 * 1000, // 5 minutes persistInterval: 5 * 60 * 1000, // 5 minutes }); cache.setKey('greeting', 'Hello, world!'); // Wait for persistInterval to save automatically, or manually: cache.save(); console.log(cache.getKey('greeting')); // 'Hello, world!' cache.removeKey('greeting'); console.log(cache.getKey('greeting')); // undefined

Debug

Known issues

breakingBreaking change in v6: removed global functions (like `load()`, `clearAll()`). Use named imports from package instead.

fix

Replace global calls with imported ones: e.g., use `import { createFromFile } from 'flat-cache'` instead of global `createFromFile`.

affects: >=6.0.0

breakingBreaking change in v6: prune() method removed. Use ttl and lruSize options to manage cache eviction.

fix

Remove calls to cache.prune(). Configure eviction via options `ttl`, `lruSize` in FlatCache constructor.

affects: >=6.0.0

breakingBreaking change in v6: save() no longer accepts a prune option. Cache automatically prunes based on ttl/lruSize.

fix

Remove prune boolean from save() calls. Use constructor options for eviction.

affects: >=6.0.0

deprecatedThe `load` function on FlatCache instance is deprecated in favor of `createFromFile`.

fix

Use `createFromFile(path)` to load an existing cache from disk.

affects: >=6.0.0

gotchaIf `serialize` and `deserialize` options are not provided, the default uses `flatted` which can handle circular references. Using custom serializers may break compatibility with files written by default serialization.

fix

Either stick with default flatted serialization or ensure custom serializer/deserializer are consistent across create and load.

affects: >=6.0.0

Errors

Common errors & fixes

Cannot find module 'flat-cache' or its corresponding type declarations.

Missing or incomplete installation, or TypeScript unable to resolve types.

fix

Install the package: npm install flat-cache. Ensure your tsconfig.json includes 'node' moduleResolution or use 'bundler' for ESM.

TypeError: flatCache.load is not a function

In v6, global `load` function is removed. Loading is done via `createFromFile` function or instance method `load` (deprecated).

fix

Use `import { createFromFile } from 'flat-cache'` and call `createFromFile('./cacheDir')`.

TypeError: cache.prune is not a function

prune() was removed in v6. Eviction is handled automatically via ttl and lruSize options.

fix

Remove any calls to `cache.prune()`. Set ttl and lruSize in constructor options.

Error: Invalid cache ID format. Must be a string without path separators.

cache ID (first argument to createFromFile or load) contains slashes or dots.

fix

Use a simple identifier (e.g., 'myCache') and specify the directory separately via `cacheDir` option.

Upgrade

Version history

6.1.22latest on npm

Audit

Dependencies

cacheablerequiredUses CacheableMemory as in-memory backend

flattedrequiredDefault serializer/deserializer for file I/O

hookifiedrequiredProvides event system for hooks

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/jaredwray/cacheable ↗

packageflat-cache ↗

homepagehttps://github.com/jaredwray/cacheable#readme ↗