flat-cache 6.0.0 → 6.1.1

package/README.md

@@ -1,4 +1,4 @@
-[<img align="center" src="https://cacheable.org/logo.svg" alt="Cacheable" />](https://github.com/jaredwray/cacheable)
+[<img align="center" src="https://cacheable.org/symbol.svg" alt="Cacheable" />](https://github.com/jaredwray/cacheable)
 
 # flat-cache
 > A simple key/value storage using files to persist the data
@@ -7,16 +7,30 @@
 [![tests](https://github.com/jaredwray/cacheable/actions/workflows/tests.yml/badge.svg)](https://github.com/jaredwray/cacheable/actions/workflows/tests.yml)
 [![npm](https://img.shields.io/npm/dm/flat-cache.svg)](https://www.npmjs.com/package/flat-cache)
 [![npm](https://img.shields.io/npm/v/flat-cache)](https://www.npmjs.com/package/flat-cache)
-[![GitHub](https://img.shields.io/github/license/jaredwray/cacheable)](https://github.com/jaredwray/cacheable/blob/main/LICENSE)
+[![license](https://img.shields.io/github/license/jaredwray/cacheable)](https://github.com/jaredwray/cacheable/blob/main/LICENSE)
 
 # Features
 - A simple key/value storage using files to persist the data
 - Uses a in-memory cache (via `CacheableMemory`) as the primary storage and then persists the data to disk
 - Automatically saves the data to disk via `persistInterval` setting. Off By Default
-- Easily Loads the data from disk and into memory
+- Uses `expirationInterval` to check for expired items in the cache. If it is not set it will do a lazy check on `get` or `getKey`
+- Easily Loads the data from disk and into memory with `load` or `loadFile`
 - Uses `ttl` and `lruSize` to manage the cache and persist the data
 - Only saves the data to disk if the data has changed even when using `persistInterval` or calling `save()`
-- Uses `flatted` to parse and stringify the data by default but can be overridden
+- Uses `flatted` to parse and stringify the data by default but can be overridden using `parse` and `stringify` in options
+- ESM and CommonJS support with TypeScript typings and maintained regularly!
+
+# Table of Contents
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [Breaking Changes from v5 to v6](#breaking-changes-from-v5-to-v6)
+- [Global Functions](#global-functions)
+- [FlatCache Options (FlatCacheOptions)](#flatcache-options-flatcacheoptions)
+- [API](#api)
+- [Events (FlatCacheEvents)](#events-flatcacheevents)
+- [Parse and Stringify for File Caching](#parse-and-stringify-for-file-caching)
+- [How to Contribute](#how-to-contribute)
+- [License and Copyright](#license-and-copyright)
 
 # Installation
 ```bash
@@ -43,16 +57,70 @@ const cache = new FlatCache({
 cache.setKey('key', 'value');
 ```
 
-This will save the data to disk every 5 minutes and will remove any data that has not been accessed in 1 hour or if the cache has more than 10,000 items.
+This will save the data to disk every 5 minutes and will remove any data that has not been accessed in 1 hour or if the cache has more than 10,000 items. The `expirationInterval` will check every 5 minutes for expired items and evict them. This is replacement to the `save()` method with a `prune` option as it is no longer needed due to the fact that the in-memory cache handles pruning by `ttl` expiration or `lruSize` which will keep the most recent there.
+
+here is an example doing load from already existing persisted cache
+
+```javascript
+import { load } from 'flat-cache';
+const cache = load('cache1', './cacheAltDirectory');
+```
+
+This will load the cache from the `./cacheAltDirectory` directory with the `cache1` id. If it doesnt exist it will not throw an error but will just return an empty cache.
+
+# Breaking Changes from v5 to v6
+
+There have been many features added and changes made to the `FlatCache` class. Here are the main changes:
+- `FlatCache` is now a class and not a function which you can create instances of or using legacy method `load`, `loadFile`, or `create`
+- `FlatCache` now uses `CacheableMemory` as the primary storage and then persists the data to disk
+- `FlatCache` now uses `ttl` and `lruSize` to manage the cache and persist the data
+- `FlatCache` now uses `expirationInterval` to check for expired items in the cache. If it is not set it will do a lazy check on `get` or `getKey`
+- `getKey` still exists but is now is an alias to `get` and will be removed in the future
+- `setKey` still exists but is now is an alias to `set` and will be removed in the future
+- `removeKey` still exists but is now is an alias to `delete` and will be removed in the future
+
+Here is an example of the legacy method `load`:
+```javascript
+const flatCache = require('flat-cache');
+// loads the cache, if one does not exists for the given
+// Id a new one will be prepared to be created
+const cache = flatCache.load('cacheId');
+```
+
+Now you can use the `load` method and ES6 imports:
+```javascript
+import { FlatCache } from 'flat-cache';
+const cache = new FlatCache();
+cache.load('cacheId');
+```
+If you do not specify a `cacheId` it will default to what was set in `FlatCacheOptions` or the default property `cacheId` of `cache1` and default `cacheDir` of `./cache`.
+
+If you want to create a new cache and load from disk if it exists you can use the `create` method:
+```javascript
+import { create } from 'flat-cache';
+const cache = create({ cacheId: 'myCacheId', cacheDir: './mycache', ttl: 60 * 60 * 1000 });
+```
+
+# Global Functions
+
+In version 6 we attempted to keep as much as the functionality as possible which includes these functions:
+
+- `create(options?: FlatCacheOptions)` - Creates a new cache and will load the data from disk if it exists
+- `createFromFile(filePath, options?: FlatCacheOptions)` - Creates a new cache from a file
+- `clearByCacheId(cacheId: string, cacheDir?: string)` - Clears the cache by the cacheId
+- `clearAll(cacheDirectory?: string)` - Clears all the caches
 
-# FlatCache Options
-- `ttl` - The time to live for the cache in milliseconds. Default is `0` which means no expiration
-- `lruSize` - The number of items to keep in the cache. Default is `0` which means no limit
-- `useClone` - If `true` it will clone the data before returning it. Default is `false`
-- `expirationInterval` - The interval to check for expired items in the cache. Default is `0` which means no expiration
-- `persistInterval` - The interval to save the data to disk. Default is `0` which means no persistence
-- `cacheDir` - The directory to save the cache files. Default is `./cache`
-- `cacheId` - The id of the cache. Default is `cache1`
+
+# FlatCache Options (FlatCacheOptions)
+- `ttl?` - The time to live for the cache in milliseconds. Default is `0` which means no expiration
+- `lruSize?` - The number of items to keep in the cache. Default is `0` which means no limit
+- `useClone?` - If `true` it will clone the data before returning it. Default is `false`
+- `expirationInterval?` - The interval to check for expired items in the cache. Default is `0` which means no expiration
+- `persistInterval?` - The interval to save the data to disk. Default is `0` which means no persistence
+- `cacheDir?` - The directory to save the cache files. Default is `./cache`
+- `cacheId?` - The id of the cache. Default is `cache1`
+- `serialize?` - The function to parse the data. Default is `flatted.parse`
+- `deserialize?` - The function to stringify the data. Default is `flatted.stringify`
 
 # API
 
@@ -62,6 +130,7 @@ This will save the data to disk every 5 minutes and will remove any data that ha
 - `cacheFilePath` - The full path to the cache file
 - `cacheDirPath` - The full path to the cache directory
 - `persistInterval` - The interval to save the data to disk
+- `changesSinceLastSave` - If there have been changes since the last save
 - `load(cacheId: string, cacheDir?: string)` - Loads the data from disk
 - `loadFile(pathToFile: string)` - Loads the data from disk
 - `all()` - Gets all the data in the cache
@@ -74,9 +143,48 @@ This will save the data to disk every 5 minutes and will remove any data that ha
 - `removeKey(key: string)` - Removes the key from the cache
 - `delete(key: string)` - Removes the key from the cache
 - `clear()` - Clears the cache
-- `save()` - Saves the data to disk
+- `save(force? boolean)` - Saves the data to disk. If `force` is `true` it will save even if `changesSinceLastSave` is `false`
 - `destroy()` - Destroys the cache and remove files
 
+# Events (FlatCacheEvents)
+
+Events have been added since v6 to allow for more control and visibility into the cache. Here are the events that are available:
+
+- `on(event: 'save', listener: () => void)` - Emitted when the cache is saved
+- `on(event: 'load', listener: () => void)` - Emitted when the cache is loaded
+- `on(event: 'delete', listener: (key: string) => void)` - Emitted when the cache is changed
+- `on(event: 'clear', listener: () => void)` - Emitted when the cache is cleared
+- `on(event: 'destroy', listener: () => void)` - Emitted when the cache is destroyed
+- `on(event: 'error', listener: (error: Error) => void)` - Emitted when there is an error
+
+Here is an example of how to use the `error` events:
+
+```javascript
+import { FlatCache, FlatCacheEvents } from 'flat-cache';
+const cache = new FlatCache();
+cache.on(FlatCacheEvents.error, (error) => {
+  console.error(error);
+});
+```
+
+`FlatCacheEvents` is an enum that contains the event names for the `on` method. You do not have to use it but makes it easier to know what events are available.
+
+# Parse and Stringify for File Caching
+
+By default `flat-cache` uses `flatted` to parse and stringify the data. This is to allow for more complex data structures to be saved to disk. If you want to override this you can pass in your own `parse` and `stringify` functions. Here is an example:
+
+```javascript
+import { FlatCache } from 'flat-cache';
+const cache = new FlatCache({
+  parse: JSON.parse,
+  stringify: JSON.stringify,
+});
+```
+
+This will use `JSON.parse` and `JSON.stringify` to parse and stringify the data. This is useful if you want to use a different library or have a custom way of parsing and stringifying the data.
+
+**NOTE: This could cause issues if you are trying to load data that was saved with a different parser or stringifier.** 
+
 # How to Contribute
 
 You can contribute by forking the repo and submitting a pull request. Please make sure to add tests and update the documentation. To learn more about how to contribute go to our main README [https://github.com/jaredwray/cacheable](https://github.com/jaredwray/cacheable). This will talk about how to `Open a Pull Request`, `Ask a Question`, or `Post an Issue`.

package/dist/index.cjs

@@ -31,23 +31,40 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   FlatCache: () => FlatCache,
+  FlatCacheEvents: () => FlatCacheEvents,
   clearAll: () => clearAll,
   clearCacheById: () => clearCacheById,
   create: () => create,
-  createFromFile: () => createFromFile
+  createFromFile: () => createFromFile,
+  default: () => FlatCacheDefault
 });
 module.exports = __toCommonJS(src_exports);
 var import_node_path = __toESM(require("path"), 1);
 var import_node_fs = __toESM(require("fs"), 1);
 var import_cacheable = require("cacheable");
 var import_flatted = require("flatted");
-var FlatCache = class {
+var import_hookified = require("hookified");
+var FlatCacheEvents = /* @__PURE__ */ ((FlatCacheEvents2) => {
+  FlatCacheEvents2["SAVE"] = "save";
+  FlatCacheEvents2["LOAD"] = "load";
+  FlatCacheEvents2["DELETE"] = "delete";
+  FlatCacheEvents2["CLEAR"] = "clear";
+  FlatCacheEvents2["DESTROY"] = "destroy";
+  FlatCacheEvents2["ERROR"] = "error";
+  FlatCacheEvents2["EXPIRED"] = "expired";
+  return FlatCacheEvents2;
+})(FlatCacheEvents || {});
+var FlatCache = class extends import_hookified.Hookified {
   _cache = new import_cacheable.CacheableMemory();
   _cacheDir = ".cache";
   _cacheId = "cache1";
   _persistInterval = 0;
   _persistTimer;
+  _changesSinceLastSave = false;
+  _parse = import_flatted.parse;
+  _stringify = import_flatted.stringify;
   constructor(options) {
+    super();
     if (options) {
       this._cache = new import_cacheable.CacheableMemory({
         ttl: options.ttl,
@@ -66,6 +83,12 @@ var FlatCache = class {
       this._persistInterval = options.persistInterval;
       this.startAutoPersist();
     }
+    if (options?.deserialize) {
+      this._parse = options.deserialize;
+    }
+    if (options?.serialize) {
+      this._stringify = options.serialize;
+    }
   }
   /**
    * The cache object
@@ -111,6 +134,15 @@ var FlatCache = class {
   set cacheId(value) {
     this._cacheId = value;
   }
+  /**
+   * The flag to indicate if there are changes since the last save
+   * @property changesSinceLastSave
+   * @type {Boolean}
+   * @default false
+   */
+  get changesSinceLastSave() {
+    return this._changesSinceLastSave;
+  }
   /**
    * The interval to persist the cache to disk. 0 means no timed persistence
    * @property persistInterval
@@ -135,13 +167,18 @@ var FlatCache = class {
    * then the cache module directory `.cacheDir` will be used instead
    *
    * @method load
-   * @param docId {String} the id of the cache, would also be used as the name of the file cache
-   * @param [cacheDir] {String} directory for the cache entry
+   * @param cacheId {String} the id of the cache, would also be used as the name of the file cache
+   * @param cacheDir {String} directory for the cache entry
    */
   // eslint-disable-next-line unicorn/prevent-abbreviations
-  load(documentId, cacheDir) {
-    const filePath = import_node_path.default.resolve(`${cacheDir ?? this._cacheDir}/${documentId}`);
-    this.loadFile(filePath);
+  load(cacheId, cacheDir) {
+    try {
+      const filePath = import_node_path.default.resolve(`${cacheDir ?? this._cacheDir}/${cacheId ?? this._cacheId}`);
+      this.loadFile(filePath);
+      this.emit("load" /* LOAD */);
+    } catch (error) {
+      this.emit("error" /* ERROR */, error);
+    }
   }
   /**
    * Load the cache from the provided file
@@ -151,10 +188,11 @@ var FlatCache = class {
   loadFile(pathToFile) {
     if (import_node_fs.default.existsSync(pathToFile)) {
       const data = import_node_fs.default.readFileSync(pathToFile, "utf8");
-      const items = (0, import_flatted.parse)(data);
+      const items = this._parse(data);
       for (const key of Object.keys(items)) {
         this._cache.set(key, items[key]);
       }
+      this._changesSinceLastSave = true;
     }
   }
   /**
@@ -209,7 +247,7 @@ var FlatCache = class {
    * @param value {object} the value of the key. Could be any object that can be serialized with JSON.stringify
    */
   setKey(key, value, ttl) {
-    this._cache.set(key, value, ttl);
+    this.set(key, value, ttl);
   }
   /**
    * Sets a key to a given value
@@ -220,6 +258,7 @@ var FlatCache = class {
    */
   set(key, value, ttl) {
     this._cache.set(key, value, ttl);
+    this._changesSinceLastSave = true;
   }
   /**
    * (Legacy) Remove a given key from the cache. This method will be deprecated in the future
@@ -227,7 +266,7 @@ var FlatCache = class {
    * @param key {String} the key to remove from the object
    */
   removeKey(key) {
-    this._cache.delete(key);
+    this.delete(key);
   }
   /**
    * Remove a given key from the cache
@@ -236,6 +275,8 @@ var FlatCache = class {
    */
   delete(key) {
     this._cache.delete(key);
+    this._changesSinceLastSave = true;
+    this.emit("delete" /* DELETE */, key);
   }
   /**
   * (Legacy) Return the value of the provided key. This method will be deprecated in the future
@@ -256,25 +297,40 @@ var FlatCache = class {
     return this._cache.get(key);
   }
   /**
-   * Clear the cache
+   * Clear the cache and save the state to disk
    * @method clear
    */
   clear() {
-    this._cache.clear();
+    try {
+      this._cache.clear();
+      this._changesSinceLastSave = true;
+      this.save();
+      this.emit("clear" /* CLEAR */);
+    } catch (error) {
+      this.emit("error" /* ERROR */, error);
+    }
   }
   /**
    * Save the state of the cache identified by the docId to disk
    * as a JSON structure
    * @method save
    */
-  save() {
-    const filePath = this.cacheFilePath;
-    const items = this.all();
-    const data = (0, import_flatted.stringify)(items);
-    if (!import_node_fs.default.existsSync(this._cacheDir)) {
-      import_node_fs.default.mkdirSync(this._cacheDir, { recursive: true });
+  save(force = false) {
+    try {
+      if (this._changesSinceLastSave || force) {
+        const filePath = this.cacheFilePath;
+        const items = this.all();
+        const data = this._stringify(items);
+        if (!import_node_fs.default.existsSync(this._cacheDir)) {
+          import_node_fs.default.mkdirSync(this._cacheDir, { recursive: true });
+        }
+        import_node_fs.default.writeFileSync(filePath, data);
+        this._changesSinceLastSave = false;
+        this.emit("save" /* SAVE */);
+      }
+    } catch (error) {
+      this.emit("error" /* ERROR */, error);
     }
-    import_node_fs.default.writeFileSync(filePath, data);
   }
   /**
    * Remove the file where the cache is persisted
@@ -282,9 +338,13 @@ var FlatCache = class {
    * @return {Boolean} true or false if the file was successfully deleted
    */
   removeCacheFile() {
-    if (import_node_fs.default.existsSync(this.cacheFilePath)) {
-      import_node_fs.default.rmSync(this.cacheFilePath);
-      return true;
+    try {
+      if (import_node_fs.default.existsSync(this.cacheFilePath)) {
+        import_node_fs.default.rmSync(this.cacheFilePath);
+        return true;
+      }
+    } catch (error) {
+      this.emit("error" /* ERROR */, error);
     }
     return false;
   }
@@ -295,12 +355,18 @@ var FlatCache = class {
    * @return {undefined}
    */
   destroy(includeCacheDirectory = false) {
-    this._cache.clear();
-    this.stopAutoPersist();
-    if (includeCacheDirectory) {
-      import_node_fs.default.rmSync(this.cacheDirPath, { recursive: true, force: true });
-    } else {
-      import_node_fs.default.rmSync(this.cacheFilePath, { recursive: true, force: true });
+    try {
+      this._cache.clear();
+      this.stopAutoPersist();
+      if (includeCacheDirectory) {
+        import_node_fs.default.rmSync(this.cacheDirPath, { recursive: true, force: true });
+      } else {
+        import_node_fs.default.rmSync(this.cacheFilePath, { recursive: true, force: true });
+      }
+      this._changesSinceLastSave = false;
+      this.emit("destroy" /* DESTROY */);
+    } catch (error) {
+      this.emit("error" /* ERROR */, error);
     }
   }
   /**
@@ -329,13 +395,15 @@ var FlatCache = class {
     }
   }
 };
-function create(documentId, cacheDirectory, options) {
+var FlatCacheDefault = class {
+  static create = create;
+  static createFromFile = createFromFile;
+  static clearCacheById = clearCacheById;
+  static clearAll = clearAll;
+};
+function create(options) {
   const cache = new FlatCache(options);
-  cache.cacheId = documentId;
-  if (cacheDirectory) {
-    cache.cacheDir = cacheDirectory;
-  }
-  cache.load(documentId, cacheDirectory);
+  cache.load();
   return cache;
 }
 function createFromFile(filePath, options) {
@@ -353,6 +421,7 @@ function clearAll(cacheDirectory) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   FlatCache,
+  FlatCacheEvents,
   clearAll,
   clearCacheById,
   create,

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { CacheableMemory } from 'cacheable';
+import { Hookified } from 'hookified';
 
 type FlatCacheOptions = {
     ttl?: number | string;
@@ -8,13 +9,27 @@ type FlatCacheOptions = {
     persistInterval?: number;
     cacheDir?: string;
     cacheId?: string;
+    deserialize?: (data: string) => any;
+    serialize?: (data: any) => string;
 };
-declare class FlatCache {
+declare enum FlatCacheEvents {
+    SAVE = "save",
+    LOAD = "load",
+    DELETE = "delete",
+    CLEAR = "clear",
+    DESTROY = "destroy",
+    ERROR = "error",
+    EXPIRED = "expired"
+}
+declare class FlatCache extends Hookified {
     private readonly _cache;
     private _cacheDir;
     private _cacheId;
     private _persistInterval;
     private _persistTimer;
+    private _changesSinceLastSave;
+    private readonly _parse;
+    private readonly _stringify;
     constructor(options?: FlatCacheOptions);
     /**
      * The cache object
@@ -50,6 +65,13 @@ declare class FlatCache {
      * @default 'cache1'
      */
     set cacheId(value: string);
+    /**
+     * The flag to indicate if there are changes since the last save
+     * @property changesSinceLastSave
+     * @type {Boolean}
+     * @default false
+     */
+    get changesSinceLastSave(): boolean;
     /**
      * The interval to persist the cache to disk. 0 means no timed persistence
      * @property persistInterval
@@ -70,10 +92,10 @@ declare class FlatCache {
      * then the cache module directory `.cacheDir` will be used instead
      *
      * @method load
-     * @param docId {String} the id of the cache, would also be used as the name of the file cache
-     * @param [cacheDir] {String} directory for the cache entry
+     * @param cacheId {String} the id of the cache, would also be used as the name of the file cache
+     * @param cacheDir {String} directory for the cache entry
      */
-    load(documentId: string, cacheDir?: string): void;
+    load(cacheId?: string, cacheDir?: string): void;
     /**
      * Load the cache from the provided file
      * @method loadFile
@@ -156,7 +178,7 @@ declare class FlatCache {
      */
     get<T>(key: string): T;
     /**
-     * Clear the cache
+     * Clear the cache and save the state to disk
      * @method clear
      */
     clear(): void;
@@ -165,7 +187,7 @@ declare class FlatCache {
      * as a JSON structure
      * @method save
      */
-    save(): void;
+    save(force?: boolean): void;
     /**
      * Remove the file where the cache is persisted
      * @method removeCacheFile
@@ -190,6 +212,12 @@ declare class FlatCache {
      */
     stopAutoPersist(): void;
 }
+declare class FlatCacheDefault {
+    static create: typeof create;
+    static createFromFile: typeof createFromFile;
+    static clearCacheById: typeof clearCacheById;
+    static clearAll: typeof clearAll;
+}
 /**
  * Load a cache identified by the given Id. If the element does not exists, then initialize an empty
  * cache storage.
@@ -200,7 +228,7 @@ declare class FlatCache {
  * @param options {FlatCacheOptions} options for the cache
  * @returns {cache} cache instance
  */
-declare function create(documentId: string, cacheDirectory?: string, options?: FlatCacheOptions): FlatCache;
+declare function create(options?: FlatCacheOptions): FlatCache;
 /**
  * Load a cache from the provided file
  * @method createFromFile
@@ -223,4 +251,4 @@ declare function clearCacheById(cacheId: string, cacheDirectory?: string): void;
  */
 declare function clearAll(cacheDirectory?: string): void;
 
-export { FlatCache, type FlatCacheOptions, clearAll, clearCacheById, create, createFromFile };
+export { FlatCache, FlatCacheEvents, type FlatCacheOptions, clearAll, clearCacheById, create, createFromFile, FlatCacheDefault as default };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { CacheableMemory } from 'cacheable';
+import { Hookified } from 'hookified';
 
 type FlatCacheOptions = {
     ttl?: number | string;
@@ -8,13 +9,27 @@ type FlatCacheOptions = {
     persistInterval?: number;
     cacheDir?: string;
     cacheId?: string;
+    deserialize?: (data: string) => any;
+    serialize?: (data: any) => string;
 };
-declare class FlatCache {
+declare enum FlatCacheEvents {
+    SAVE = "save",
+    LOAD = "load",
+    DELETE = "delete",
+    CLEAR = "clear",
+    DESTROY = "destroy",
+    ERROR = "error",
+    EXPIRED = "expired"
+}
+declare class FlatCache extends Hookified {
     private readonly _cache;
     private _cacheDir;
     private _cacheId;
     private _persistInterval;
     private _persistTimer;
+    private _changesSinceLastSave;
+    private readonly _parse;
+    private readonly _stringify;
     constructor(options?: FlatCacheOptions);
     /**
      * The cache object
@@ -50,6 +65,13 @@ declare class FlatCache {
      * @default 'cache1'
      */
     set cacheId(value: string);
+    /**
+     * The flag to indicate if there are changes since the last save
+     * @property changesSinceLastSave
+     * @type {Boolean}
+     * @default false
+     */
+    get changesSinceLastSave(): boolean;
     /**
      * The interval to persist the cache to disk. 0 means no timed persistence
      * @property persistInterval
@@ -70,10 +92,10 @@ declare class FlatCache {
      * then the cache module directory `.cacheDir` will be used instead
      *
      * @method load
-     * @param docId {String} the id of the cache, would also be used as the name of the file cache
-     * @param [cacheDir] {String} directory for the cache entry
+     * @param cacheId {String} the id of the cache, would also be used as the name of the file cache
+     * @param cacheDir {String} directory for the cache entry
      */
-    load(documentId: string, cacheDir?: string): void;
+    load(cacheId?: string, cacheDir?: string): void;
     /**
      * Load the cache from the provided file
      * @method loadFile
@@ -156,7 +178,7 @@ declare class FlatCache {
      */
     get<T>(key: string): T;
     /**
-     * Clear the cache
+     * Clear the cache and save the state to disk
      * @method clear
      */
     clear(): void;
@@ -165,7 +187,7 @@ declare class FlatCache {
      * as a JSON structure
      * @method save
      */
-    save(): void;
+    save(force?: boolean): void;
     /**
      * Remove the file where the cache is persisted
      * @method removeCacheFile
@@ -190,6 +212,12 @@ declare class FlatCache {
      */
     stopAutoPersist(): void;
 }
+declare class FlatCacheDefault {
+    static create: typeof create;
+    static createFromFile: typeof createFromFile;
+    static clearCacheById: typeof clearCacheById;
+    static clearAll: typeof clearAll;
+}
 /**
  * Load a cache identified by the given Id. If the element does not exists, then initialize an empty
  * cache storage.
@@ -200,7 +228,7 @@ declare class FlatCache {
  * @param options {FlatCacheOptions} options for the cache
  * @returns {cache} cache instance
  */
-declare function create(documentId: string, cacheDirectory?: string, options?: FlatCacheOptions): FlatCache;
+declare function create(options?: FlatCacheOptions): FlatCache;
 /**
  * Load a cache from the provided file
  * @method createFromFile
@@ -223,4 +251,4 @@ declare function clearCacheById(cacheId: string, cacheDirectory?: string): void;
  */
 declare function clearAll(cacheDirectory?: string): void;
 
-export { FlatCache, type FlatCacheOptions, clearAll, clearCacheById, create, createFromFile };
+export { FlatCache, FlatCacheEvents, type FlatCacheOptions, clearAll, clearCacheById, create, createFromFile, FlatCacheDefault as default };

package/dist/index.js

@@ -3,13 +3,28 @@ import path from "node:path";
 import fs from "node:fs";
 import { CacheableMemory } from "cacheable";
 import { parse, stringify } from "flatted";
-var FlatCache = class {
+import { Hookified } from "hookified";
+var FlatCacheEvents = /* @__PURE__ */ ((FlatCacheEvents2) => {
+  FlatCacheEvents2["SAVE"] = "save";
+  FlatCacheEvents2["LOAD"] = "load";
+  FlatCacheEvents2["DELETE"] = "delete";
+  FlatCacheEvents2["CLEAR"] = "clear";
+  FlatCacheEvents2["DESTROY"] = "destroy";
+  FlatCacheEvents2["ERROR"] = "error";
+  FlatCacheEvents2["EXPIRED"] = "expired";
+  return FlatCacheEvents2;
+})(FlatCacheEvents || {});
+var FlatCache = class extends Hookified {
   _cache = new CacheableMemory();
   _cacheDir = ".cache";
   _cacheId = "cache1";
   _persistInterval = 0;
   _persistTimer;
+  _changesSinceLastSave = false;
+  _parse = parse;
+  _stringify = stringify;
   constructor(options) {
+    super();
     if (options) {
       this._cache = new CacheableMemory({
         ttl: options.ttl,
@@ -28,6 +43,12 @@ var FlatCache = class {
       this._persistInterval = options.persistInterval;
       this.startAutoPersist();
     }
+    if (options?.deserialize) {
+      this._parse = options.deserialize;
+    }
+    if (options?.serialize) {
+      this._stringify = options.serialize;
+    }
   }
   /**
    * The cache object
@@ -73,6 +94,15 @@ var FlatCache = class {
   set cacheId(value) {
     this._cacheId = value;
   }
+  /**
+   * The flag to indicate if there are changes since the last save
+   * @property changesSinceLastSave
+   * @type {Boolean}
+   * @default false
+   */
+  get changesSinceLastSave() {
+    return this._changesSinceLastSave;
+  }
   /**
    * The interval to persist the cache to disk. 0 means no timed persistence
    * @property persistInterval
@@ -97,13 +127,18 @@ var FlatCache = class {
    * then the cache module directory `.cacheDir` will be used instead
    *
    * @method load
-   * @param docId {String} the id of the cache, would also be used as the name of the file cache
-   * @param [cacheDir] {String} directory for the cache entry
+   * @param cacheId {String} the id of the cache, would also be used as the name of the file cache
+   * @param cacheDir {String} directory for the cache entry
    */
   // eslint-disable-next-line unicorn/prevent-abbreviations
-  load(documentId, cacheDir) {
-    const filePath = path.resolve(`${cacheDir ?? this._cacheDir}/${documentId}`);
-    this.loadFile(filePath);
+  load(cacheId, cacheDir) {
+    try {
+      const filePath = path.resolve(`${cacheDir ?? this._cacheDir}/${cacheId ?? this._cacheId}`);
+      this.loadFile(filePath);
+      this.emit("load" /* LOAD */);
+    } catch (error) {
+      this.emit("error" /* ERROR */, error);
+    }
   }
   /**
    * Load the cache from the provided file
@@ -113,10 +148,11 @@ var FlatCache = class {
   loadFile(pathToFile) {
     if (fs.existsSync(pathToFile)) {
       const data = fs.readFileSync(pathToFile, "utf8");
-      const items = parse(data);
+      const items = this._parse(data);
       for (const key of Object.keys(items)) {
         this._cache.set(key, items[key]);
       }
+      this._changesSinceLastSave = true;
     }
   }
   /**
@@ -171,7 +207,7 @@ var FlatCache = class {
    * @param value {object} the value of the key. Could be any object that can be serialized with JSON.stringify
    */
   setKey(key, value, ttl) {
-    this._cache.set(key, value, ttl);
+    this.set(key, value, ttl);
   }
   /**
    * Sets a key to a given value
@@ -182,6 +218,7 @@ var FlatCache = class {
    */
   set(key, value, ttl) {
     this._cache.set(key, value, ttl);
+    this._changesSinceLastSave = true;
   }
   /**
    * (Legacy) Remove a given key from the cache. This method will be deprecated in the future
@@ -189,7 +226,7 @@ var FlatCache = class {
    * @param key {String} the key to remove from the object
    */
   removeKey(key) {
-    this._cache.delete(key);
+    this.delete(key);
   }
   /**
    * Remove a given key from the cache
@@ -198,6 +235,8 @@ var FlatCache = class {
    */
   delete(key) {
     this._cache.delete(key);
+    this._changesSinceLastSave = true;
+    this.emit("delete" /* DELETE */, key);
   }
   /**
   * (Legacy) Return the value of the provided key. This method will be deprecated in the future
@@ -218,25 +257,40 @@ var FlatCache = class {
     return this._cache.get(key);
   }
   /**
-   * Clear the cache
+   * Clear the cache and save the state to disk
    * @method clear
    */
   clear() {
-    this._cache.clear();
+    try {
+      this._cache.clear();
+      this._changesSinceLastSave = true;
+      this.save();
+      this.emit("clear" /* CLEAR */);
+    } catch (error) {
+      this.emit("error" /* ERROR */, error);
+    }
   }
   /**
    * Save the state of the cache identified by the docId to disk
    * as a JSON structure
    * @method save
    */
-  save() {
-    const filePath = this.cacheFilePath;
-    const items = this.all();
-    const data = stringify(items);
-    if (!fs.existsSync(this._cacheDir)) {
-      fs.mkdirSync(this._cacheDir, { recursive: true });
+  save(force = false) {
+    try {
+      if (this._changesSinceLastSave || force) {
+        const filePath = this.cacheFilePath;
+        const items = this.all();
+        const data = this._stringify(items);
+        if (!fs.existsSync(this._cacheDir)) {
+          fs.mkdirSync(this._cacheDir, { recursive: true });
+        }
+        fs.writeFileSync(filePath, data);
+        this._changesSinceLastSave = false;
+        this.emit("save" /* SAVE */);
+      }
+    } catch (error) {
+      this.emit("error" /* ERROR */, error);
     }
-    fs.writeFileSync(filePath, data);
   }
   /**
    * Remove the file where the cache is persisted
@@ -244,9 +298,13 @@ var FlatCache = class {
    * @return {Boolean} true or false if the file was successfully deleted
    */
   removeCacheFile() {
-    if (fs.existsSync(this.cacheFilePath)) {
-      fs.rmSync(this.cacheFilePath);
-      return true;
+    try {
+      if (fs.existsSync(this.cacheFilePath)) {
+        fs.rmSync(this.cacheFilePath);
+        return true;
+      }
+    } catch (error) {
+      this.emit("error" /* ERROR */, error);
     }
     return false;
   }
@@ -257,12 +315,18 @@ var FlatCache = class {
    * @return {undefined}
    */
   destroy(includeCacheDirectory = false) {
-    this._cache.clear();
-    this.stopAutoPersist();
-    if (includeCacheDirectory) {
-      fs.rmSync(this.cacheDirPath, { recursive: true, force: true });
-    } else {
-      fs.rmSync(this.cacheFilePath, { recursive: true, force: true });
+    try {
+      this._cache.clear();
+      this.stopAutoPersist();
+      if (includeCacheDirectory) {
+        fs.rmSync(this.cacheDirPath, { recursive: true, force: true });
+      } else {
+        fs.rmSync(this.cacheFilePath, { recursive: true, force: true });
+      }
+      this._changesSinceLastSave = false;
+      this.emit("destroy" /* DESTROY */);
+    } catch (error) {
+      this.emit("error" /* ERROR */, error);
     }
   }
   /**
@@ -291,13 +355,15 @@ var FlatCache = class {
     }
   }
 };
-function create(documentId, cacheDirectory, options) {
+var FlatCacheDefault = class {
+  static create = create;
+  static createFromFile = createFromFile;
+  static clearCacheById = clearCacheById;
+  static clearAll = clearAll;
+};
+function create(options) {
   const cache = new FlatCache(options);
-  cache.cacheId = documentId;
-  if (cacheDirectory) {
-    cache.cacheDir = cacheDirectory;
-  }
-  cache.load(documentId, cacheDirectory);
+  cache.load();
   return cache;
 }
 function createFromFile(filePath, options) {
@@ -314,8 +380,10 @@ function clearAll(cacheDirectory) {
 }
 export {
   FlatCache,
+  FlatCacheEvents,
   clearAll,
   clearCacheById,
   create,
-  createFromFile
+  createFromFile,
+  FlatCacheDefault as default
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flat-cache",
-  "version": "6.0.0",
+  "version": "6.1.1",
   "description": "A simple key/value storage using files to persist the data",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -12,32 +12,58 @@
       "import": "./dist/index.js"
     }
   },
-  "repository": "https://github.com/jaredwray/cacheable.git",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jaredwray/cacheable.git",
+    "directory": "packages/flat-cache"
+  },
   "author": "Jared Wray <me@jaredwray.com>",
   "license": "MIT",
   "private": false,
   "keywords": [
     "cache",
     "caching",
-    "node",
-    "nodejs",
     "cacheable",
-    "cacheable-node-cache",
-    "node-cache",
-    "cacheable-node"
+    "flat-cache",
+    "flat",
+    "file",
+    "file-cache",
+    "file-caching",
+    "file-based-cache",
+    "file-persist",
+    "file-persistence",
+    "file-storage",
+    "file-system",
+    "file-management",
+    "filesystem-cache",
+    "disk-cache",
+    "cache-persistence",
+    "cache-persist",
+    "persistent-cache",
+    "persistent-storage",
+    "cache-to-file",
+    "cache-on-disk",
+    "cache-file",
+    "cache-expiration",
+    "cache-lifetime",
+    "data-persistence",
+    "data-storage",
+    "local-storage",
+    "file-system-cache"
   ],
   "devDependencies": {
-    "@types/node": "^22.7.4",
-    "@vitest/coverage-v8": "^2.1.1",
+    "@types/node": "^22.7.8",
+    "@vitest/coverage-v8": "^2.1.3",
     "rimraf": "^6.0.1",
     "tsup": "^8.3.0",
-    "typescript": "^5.6.2",
-    "vitest": "^2.1.1",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.3",
     "xo": "^0.59.3"
   },
   "dependencies": {
-    "cacheable": "^1.7.1",
-    "flatted": "^3.3.1"
+    "cacheable": "^1.8.1",
+    "flatted": "^3.3.1",
+    "hookified": "^1.4.0"
   },
   "files": [
     "dist",