flat-cache 6.1.9 → 6.1.11

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)
 
@@ -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

@@ -170,7 +170,6 @@ var FlatCache = class extends import_hookified.Hookified {
    * @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(cacheId, cacheDir) {
     try {
       const filePath = import_node_path.default.resolve(`${cacheDir ?? this._cacheDir}/${cacheId ?? this._cacheId}`);
@@ -195,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
@@ -202,7 +235,7 @@ var FlatCache = class extends import_hookified.Hookified {
    */
   all() {
     const result = {};
-    const items = Array.from(this._cache.items);
+    const items = [...this._cache.items];
     for (const item of items) {
       result[item.key] = item.value;
     }
@@ -214,7 +247,7 @@ var FlatCache = class extends import_hookified.Hookified {
    * @returns {Array}
    */
   get items() {
-    return Array.from(this._cache.items);
+    return [...this._cache.items];
   }
   /**
    * Returns the path to the file where the cache is persisted
@@ -238,7 +271,7 @@ var FlatCache = class extends import_hookified.Hookified {
    * @returns {Array}
    */
   keys() {
-    return Array.from(this._cache.keys);
+    return [...this._cache.keys];
   }
   /**
    * (Legacy) set key method. This method will be deprecated in the future
@@ -319,7 +352,7 @@ var FlatCache = class extends import_hookified.Hookified {
     try {
       if (this._changesSinceLastSave || force) {
         const filePath = this.cacheFilePath;
-        const items = Array.from(this._cache.items);
+        const items = [...this._cache.items];
         const data = this._stringify(items);
         if (!import_node_fs.default.existsSync(this._cacheDir)) {
           import_node_fs.default.mkdirSync(this._cacheDir, { recursive: true });

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

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

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/index.ts
-import path from "node:path";
-import fs from "node:fs";
+import path from "path";
+import fs from "fs";
 import { CacheableMemory } from "cacheable";
 import { parse, stringify } from "flatted";
 import { Hookified } from "hookified";
@@ -130,7 +130,6 @@ var FlatCache = class extends Hookified {
    * @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(cacheId, cacheDir) {
     try {
       const filePath = path.resolve(`${cacheDir ?? this._cacheDir}/${cacheId ?? this._cacheId}`);
@@ -155,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
@@ -162,7 +195,7 @@ var FlatCache = class extends Hookified {
    */
   all() {
     const result = {};
-    const items = Array.from(this._cache.items);
+    const items = [...this._cache.items];
     for (const item of items) {
       result[item.key] = item.value;
     }
@@ -174,7 +207,7 @@ var FlatCache = class extends Hookified {
    * @returns {Array}
    */
   get items() {
-    return Array.from(this._cache.items);
+    return [...this._cache.items];
   }
   /**
    * Returns the path to the file where the cache is persisted
@@ -198,7 +231,7 @@ var FlatCache = class extends Hookified {
    * @returns {Array}
    */
   keys() {
-    return Array.from(this._cache.keys);
+    return [...this._cache.keys];
   }
   /**
    * (Legacy) set key method. This method will be deprecated in the future
@@ -279,7 +312,7 @@ var FlatCache = class extends Hookified {
     try {
       if (this._changesSinceLastSave || force) {
         const filePath = this.cacheFilePath;
-        const items = Array.from(this._cache.items);
+        const items = [...this._cache.items];
         const data = this._stringify(items);
         if (!fs.existsSync(this._cacheDir)) {
           fs.mkdirSync(this._cacheDir, { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flat-cache",
-  "version": "6.1.9",
+  "version": "6.1.11",
   "description": "A simple key/value storage using files to persist the data",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -52,18 +52,18 @@
     "file-system-cache"
   ],
   "devDependencies": {
-    "@types/node": "^22.15.8",
-    "@vitest/coverage-v8": "^3.1.3",
+    "@types/node": "^24.0.7",
+    "@vitest/coverage-v8": "^3.2.4",
     "rimraf": "^6.0.1",
-    "tsup": "^8.4.0",
+    "tsup": "^8.5.0",
     "typescript": "^5.8.3",
-    "vitest": "^3.1.3",
-    "xo": "^0.60.0"
+    "vitest": "^3.2.4",
+    "xo": "^1.1.1"
   },
   "dependencies": {
     "flatted": "^3.3.3",
-    "hookified": "^1.8.2",
-    "cacheable": "^1.9.0"
+    "hookified": "^1.10.0",
+    "cacheable": "^1.10.1"
   },
   "files": [
     "dist",
@@ -73,7 +73,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"
   }
 }