flat-cache 6.1.10 → 6.1.12

package/README.md

@@ -29,6 +29,7 @@
 - [API](#api)
 - [Events (FlatCacheEvents)](#events-flatcacheevents)
 - [Parse and Stringify for File Caching](#parse-and-stringify-for-file-caching)
+- [Loading Data via Streams](#loading-data-via-streams)
 - [How to Contribute](#how-to-contribute)
 - [License and Copyright](#license-and-copyright)
 
@@ -122,7 +123,7 @@ In version 6 we attempted to keep as much as the functionality as possible which
 
 - `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
-- `clearCacheById(cacheId: string, cacheDir?: string)` - Clears the cache by the cacheId
+- `clearCacheById(cacheId: string, cacheDir?: string)` - Clears the cache by the cacheId on the file system not in memory.
 - `clearAll(cacheDirectory?: string)` - Clears all the caches
 
 
@@ -148,6 +149,7 @@ In version 6 we attempted to keep as much as the functionality as possible which
 - `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
+- `loadFileStream(pathToFile: string, onProgress: function, onEnd: function, onError?: function)` - Loads the data from disk as a stream
 - `all()` - Gets all the data in the cache
 - `items()` - Gets all the items in the cache
 - `keys()` - Gets all the keys in the cache
@@ -200,6 +202,31 @@ This will use `JSON.parse` and `JSON.stringify` to parse and stringify the data.
 
 **NOTE: This could cause issues if you are trying to load data that was saved with a different parser or stringifier.** 
 
+# Loading Data via Streams
+
+Because of some large files we have added a helper function to load data from a file using streams. This is useful if you have a large file and want to load it in chunks. Here is an example:
+
+```javascript
+import { FlatCache } from 'flat-cache';
+const cache = new FlatCache();
+let progressCount = 0;
+const onProgress = (progress: number, total: number) => {
+  progressCount++;
+};
+
+let errorCount = 0;
+const onError = (error: Error) => {
+  errorCount++;
+};
+
+let endCount = 0;
+const onEnd = () => {
+  console.log(`Loaded ${progressCount} chunks with ${errorCount} errors.`);
+};
+cache.loadFileStream('/path/to/cache/file', onProgress, onEnd, onError);
+```
+This will load the data from the file in chunks and emit the `onProgress`, `onEnd`, and `onError` events. You can use these events to track the progress of the loading and handle any errors that may occur.
+
 # 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

@@ -194,6 +194,40 @@ var FlatCache = class extends import_hookified.Hookified {
       this._changesSinceLastSave = true;
     }
   }
+  loadFileStream(pathToFile, onProgress, onEnd, onError) {
+    if (import_node_fs.default.existsSync(pathToFile)) {
+      const stats = import_node_fs.default.statSync(pathToFile);
+      const total = stats.size;
+      let loaded = 0;
+      let streamData = "";
+      const readStream = import_node_fs.default.createReadStream(pathToFile, { encoding: "utf8" });
+      readStream.on("data", (chunk) => {
+        loaded += chunk.length;
+        streamData += chunk;
+        onProgress(loaded, total);
+      });
+      readStream.on("end", () => {
+        const items = this._parse(streamData);
+        for (const key of Object.keys(items)) {
+          this._cache.set(items[key].key, items[key].value, { expire: items[key].expires });
+        }
+        this._changesSinceLastSave = true;
+        onEnd();
+      });
+      readStream.on("error", (error) => {
+        this.emit("error" /* ERROR */, error);
+        if (onError) {
+          onError(error);
+        }
+      });
+    } else {
+      const error = new Error(`Cache file ${pathToFile} does not exist`);
+      this.emit("error" /* ERROR */, error);
+      if (onError) {
+        onError(error);
+      }
+    }
+  }
   /**
    * Returns the entire persisted object
    * @method all

package/dist/index.d.cts

@@ -102,6 +102,7 @@ declare class FlatCache extends Hookified {
      * @param  {String} pathToFile the path to the file containing the info for the cache
      */
     loadFile(pathToFile: string): void;
+    loadFileStream(pathToFile: string, onProgress: (progress: number, total: number) => void, onEnd: () => void, onError?: (error: Error) => void): void;
     /**
      * Returns the entire persisted object
      * @method all
@@ -238,7 +239,7 @@ declare function create(options?: FlatCacheOptions): FlatCache;
  */
 declare function createFromFile(filePath: string, options?: FlatCacheOptions): FlatCache;
 /**
- * Clear the cache identified by the given Id
+ * Clear the cache identified by the given Id. This will only remove the cache from disk.
  * @method clearCacheById
  * @param cacheId {String} the id of the cache
  * @param cacheDirectory {String} directory for the cache entry

package/dist/index.d.ts

@@ -102,6 +102,7 @@ declare class FlatCache extends Hookified {
      * @param  {String} pathToFile the path to the file containing the info for the cache
      */
     loadFile(pathToFile: string): void;
+    loadFileStream(pathToFile: string, onProgress: (progress: number, total: number) => void, onEnd: () => void, onError?: (error: Error) => void): void;
     /**
      * Returns the entire persisted object
      * @method all
@@ -238,7 +239,7 @@ declare function create(options?: FlatCacheOptions): FlatCache;
  */
 declare function createFromFile(filePath: string, options?: FlatCacheOptions): FlatCache;
 /**
- * Clear the cache identified by the given Id
+ * Clear the cache identified by the given Id. This will only remove the cache from disk.
  * @method clearCacheById
  * @param cacheId {String} the id of the cache
  * @param cacheDirectory {String} directory for the cache entry

package/dist/index.js

@@ -154,6 +154,40 @@ var FlatCache = class extends Hookified {
       this._changesSinceLastSave = true;
     }
   }
+  loadFileStream(pathToFile, onProgress, onEnd, onError) {
+    if (fs.existsSync(pathToFile)) {
+      const stats = fs.statSync(pathToFile);
+      const total = stats.size;
+      let loaded = 0;
+      let streamData = "";
+      const readStream = fs.createReadStream(pathToFile, { encoding: "utf8" });
+      readStream.on("data", (chunk) => {
+        loaded += chunk.length;
+        streamData += chunk;
+        onProgress(loaded, total);
+      });
+      readStream.on("end", () => {
+        const items = this._parse(streamData);
+        for (const key of Object.keys(items)) {
+          this._cache.set(items[key].key, items[key].value, { expire: items[key].expires });
+        }
+        this._changesSinceLastSave = true;
+        onEnd();
+      });
+      readStream.on("error", (error) => {
+        this.emit("error" /* ERROR */, error);
+        if (onError) {
+          onError(error);
+        }
+      });
+    } else {
+      const error = new Error(`Cache file ${pathToFile} does not exist`);
+      this.emit("error" /* ERROR */, error);
+      if (onError) {
+        onError(error);
+      }
+    }
+  }
   /**
    * Returns the entire persisted object
    * @method all

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flat-cache",
-  "version": "6.1.10",
+  "version": "6.1.12",
   "description": "A simple key/value storage using files to persist the data",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -52,18 +52,19 @@
     "file-system-cache"
   ],
   "devDependencies": {
-    "@types/node": "^22.15.30",
-    "@vitest/coverage-v8": "^3.2.2",
+    "@faker-js/faker": "^9.9.0",
+    "@types/node": "^24.1.0",
+    "@vitest/coverage-v8": "^3.2.4",
     "rimraf": "^6.0.1",
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",
-    "vitest": "^3.2.2",
-    "xo": "^1.1.0"
+    "vitest": "^3.2.4",
+    "xo": "^1.2.1"
   },
   "dependencies": {
     "flatted": "^3.3.3",
-    "hookified": "^1.9.1",
-    "cacheable": "^1.10.0"
+    "hookified": "^1.10.0",
+    "cacheable": "^1.10.3"
   },
   "files": [
     "dist",
@@ -73,7 +74,7 @@
     "build": "rimraf ./dist && tsup src/index.ts --format cjs,esm --dts --clean",
     "prepublish": "pnpm build",
     "test": "xo --fix && vitest run --coverage",
-    "test:ci": "xo && vitest run",
+    "test:ci": "xo && vitest run --coverage",
     "clean": "rimraf ./dist ./coverage ./node_modules"
   }
 }