flat-cache 4.0.1 → 6.0.0

package/LICENSE

@@ -1,22 +1,19 @@
-The MIT License (MIT)
-
-Copyright (c) Roy Riojas and Jared Wray
+MIT License & © Jared Wray 
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,77 +1,85 @@
-# flat-cache
-
-> A stupidly simple key/value storage using files to persist the data
-
-[![NPM Version](https://img.shields.io/npm/v/flat-cache.svg?style=flat)](https://npmjs.org/package/flat-cache)
-[![tests](https://github.com/jaredwray/flat-cache/actions/workflows/tests.yaml/badge.svg?branch=master)](https://github.com/jaredwray/flat-cache/actions/workflows/tests.yaml)
-[![codecov](https://codecov.io/github/jaredwray/flat-cache/branch/master/graph/badge.svg?token=KxR95XT3NF)](https://codecov.io/github/jaredwray/flat-cache)
-[![npm](https://img.shields.io/npm/dm/flat-cache)](https://npmjs.com/package/flat-cache)
-
-## install
+[<img align="center" src="https://cacheable.org/logo.svg" alt="Cacheable" />](https://github.com/jaredwray/cacheable)
 
+# flat-cache
+> A simple key/value storage using files to persist the data
+
+[![codecov](https://codecov.io/gh/jaredwray/cacheable/graph/badge.svg?token=lWZ9OBQ7GM)](https://codecov.io/gh/jaredwray/cacheable)
+[![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)
+
+# 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 `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
+
+# Installation
 ```bash
-npm i --save flat-cache
+npm install flat-cache
 ```
 
-## Usage
-
-```js
-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');
-
-// sets a key on the cache
-cache.setKey('key', { foo: 'var' });
-
-// get a key from the cache
-cache.getKey('key'); // { foo: 'var' }
-
-// fetch the entire persisted object
-cache.all(); // { 'key': { foo: 'var' } }
-
-// remove a key
-cache.removeKey('key'); // removes a key from the cache
-
-// save it to disk
-cache.save(); // very important, if you don't save no changes will be persisted.
-// cache.save( true /* noPrune */) // can be used to prevent the removal of non visited keys
-
-// loads the cache from a given directory, if one does
-// not exists for the given Id a new one will be prepared to be created
-const cache = flatCache.load('cacheId', path.resolve('./path/to/folder'));
-
-// The following methods are useful to clear the cache
-// delete a given cache
-flatCache.clearCacheById('cacheId'); // removes the cacheId document if one exists.
-
-// delete all cache
-flatCache.clearAll(); // remove the cache directory
+# Getting Started
+```javascript
+import { FlatCache } from 'flat-cache';
+const cache = new FlatCache();
+cache.setKey('key', 'value');
+cache.save(); // Saves the data to disk
 ```
 
-## Motivation for this module
-
-I needed a super simple and dumb **in-memory cache** with optional disk persistance in order to make
-a script that will beutify files with `esformatter` only execute on the files that were changed since the last run.
-To make that possible we need to store the `fileSize` and `modificationTime` of the files. So a simple `key/value`
-storage was needed and Bam! this module was born.
-
-## Important notes
-
-- If no directory is especified when the `load` method is called, a folder named `.cache` will be created
-  inside the module directory when `cache.save` is called. If you're committing your `node_modules` to any vcs, you
-  might want to ignore the default `.cache` folder, or specify a custom directory.
-- The values set on the keys of the cache should be `stringify-able` ones, meaning no circular references
-- All the changes to the cache state are done to memory
-- I could have used a timer or `Object.observe` to deliver the changes to disk, but I wanted to keep this module
-  intentionally dumb and simple
-- Non visited keys are removed when `cache.save()` is called. If this is not desired, you can pass `true` to the save call
-  like: `cache.save( true /* noPrune */ )`.
-
-## License
-
-MIT
-
-## Changelog
+lets add it with `ttl`, `lruSize`, and `persistInterval`
+```javascript
+import { FlatCache } from 'flat-cache';
+const cache = new FlatCache({
+  ttl: 60 * 60 * 1000 , // 1 hour
+  lruSize: 10000, // 10,000 items
+  expirationInterval: 5 * 1000 * 60, // 5 minutes
+  persistInterval: 5 * 1000 * 60, // 5 minutes
+});
+cache.setKey('key', 'value');
+```
 
-[changelog](./changelog.md)
+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.
+
+# 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`
+
+# API
+
+- `cache` - The in-memory cache as a `CacheableMemory` instance
+- `cacheDir` - The directory to save the cache files
+- `cacheId` - The id of the cache
+- `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
+- `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
+- `items()` - Gets all the items in the cache
+- `keys()` - Gets all the keys in the cache
+- `setKey(key: string, value: any, ttl?: string | number)` - (legacy) Sets the key/value pair in the cache
+- `set(key: string, value: any, ttl?: string | number)` - Sets the key/value pair in the cache
+- `getKey<T>(key: string)` - Gets the value for the key or the default value
+- `get<T>(key: string)` - Gets the value for the key or the default value
+- `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
+- `destroy()` - Destroys the cache and remove files
+
+# 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`.
+
+# License and Copyright
+[MIT © Jared Wray](./LICENSE)

package/dist/index.cjs

@@ -0,0 +1,360 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  FlatCache: () => FlatCache,
+  clearAll: () => clearAll,
+  clearCacheById: () => clearCacheById,
+  create: () => create,
+  createFromFile: () => createFromFile
+});
+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 {
+  _cache = new import_cacheable.CacheableMemory();
+  _cacheDir = ".cache";
+  _cacheId = "cache1";
+  _persistInterval = 0;
+  _persistTimer;
+  constructor(options) {
+    if (options) {
+      this._cache = new import_cacheable.CacheableMemory({
+        ttl: options.ttl,
+        useClone: options.useClone,
+        lruSize: options.lruSize,
+        checkInterval: options.expirationInterval
+      });
+    }
+    if (options?.cacheDir) {
+      this._cacheDir = options.cacheDir;
+    }
+    if (options?.cacheId) {
+      this._cacheId = options.cacheId;
+    }
+    if (options?.persistInterval) {
+      this._persistInterval = options.persistInterval;
+      this.startAutoPersist();
+    }
+  }
+  /**
+   * The cache object
+   * @property cache
+   * @type {CacheableMemory}
+   */
+  get cache() {
+    return this._cache;
+  }
+  /**
+   * The cache directory
+   * @property cacheDir
+   * @type {String}
+   * @default '.cache'
+   */
+  get cacheDir() {
+    return this._cacheDir;
+  }
+  /**
+   * Set the cache directory
+   * @property cacheDir
+   * @type {String}
+   * @default '.cache'
+   */
+  set cacheDir(value) {
+    this._cacheDir = value;
+  }
+  /**
+   * The cache id
+   * @property cacheId
+   * @type {String}
+   * @default 'cache1'
+   */
+  get cacheId() {
+    return this._cacheId;
+  }
+  /**
+   * Set the cache id
+   * @property cacheId
+   * @type {String}
+   * @default 'cache1'
+   */
+  set cacheId(value) {
+    this._cacheId = value;
+  }
+  /**
+   * The interval to persist the cache to disk. 0 means no timed persistence
+   * @property persistInterval
+   * @type {Number}
+   * @default 0
+   */
+  get persistInterval() {
+    return this._persistInterval;
+  }
+  /**
+   * Set the interval to persist the cache to disk. 0 means no timed persistence
+   * @property persistInterval
+   * @type {Number}
+   * @default 0
+   */
+  set persistInterval(value) {
+    this._persistInterval = value;
+  }
+  /**
+   * Load a cache identified by the given Id. If the element does not exists, then initialize an empty
+   * cache storage. If specified `cacheDir` will be used as the directory to persist the data to. If omitted
+   * 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
+   */
+  // 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 the cache from the provided file
+   * @method loadFile
+   * @param  {String} pathToFile the path to the file containing the info for the cache
+   */
+  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);
+      for (const key of Object.keys(items)) {
+        this._cache.set(key, items[key]);
+      }
+    }
+  }
+  /**
+   * Returns the entire persisted object
+   * @method all
+   * @returns {*}
+   */
+  all() {
+    const result = {};
+    const items = Array.from(this._cache.items);
+    for (const item of items) {
+      result[item.key] = item.value;
+    }
+    return result;
+  }
+  /**
+   * Returns an array with all the items in the cache { key, value, ttl }
+   * @method items
+   * @returns {Array}
+   */
+  get items() {
+    return Array.from(this._cache.items);
+  }
+  /**
+   * Returns the path to the file where the cache is persisted
+   * @method cacheFilePath
+   * @returns {String}
+   */
+  get cacheFilePath() {
+    return import_node_path.default.resolve(`${this._cacheDir}/${this._cacheId}`);
+  }
+  /**
+   * Returns the path to the cache directory
+   * @method cacheDirPath
+   * @returns {String}
+   */
+  get cacheDirPath() {
+    return import_node_path.default.resolve(this._cacheDir);
+  }
+  /**
+   * Returns an array with all the keys in the cache
+   * @method keys
+   * @returns {Array}
+   */
+  keys() {
+    return Array.from(this._cache.keys);
+  }
+  /**
+   * (Legacy) set key method. This method will be deprecated in the future
+   * @method setKey
+   * @param key {string} the key to set
+   * @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);
+  }
+  /**
+   * Sets a key to a given value
+   * @method set
+   * @param key {string} the key to set
+   * @param value {object} the value of the key. Could be any object that can be serialized with JSON.stringify
+   * @param [ttl] {number} the time to live in milliseconds
+   */
+  set(key, value, ttl) {
+    this._cache.set(key, value, ttl);
+  }
+  /**
+   * (Legacy) Remove a given key from the cache. This method will be deprecated in the future
+   * @method removeKey
+   * @param key {String} the key to remove from the object
+   */
+  removeKey(key) {
+    this._cache.delete(key);
+  }
+  /**
+   * Remove a given key from the cache
+   * @method delete
+   * @param key {String} the key to remove from the object
+   */
+  delete(key) {
+    this._cache.delete(key);
+  }
+  /**
+  * (Legacy) Return the value of the provided key. This method will be deprecated in the future
+  * @method getKey<T>
+  * @param key {String} the name of the key to retrieve
+  * @returns {*} at T the value from the key
+  */
+  getKey(key) {
+    return this.get(key);
+  }
+  /**
+   * Return the value of the provided key
+   * @method get<T>
+   * @param key {String} the name of the key to retrieve
+   * @returns {*} at T the value from the key
+   */
+  get(key) {
+    return this._cache.get(key);
+  }
+  /**
+   * Clear the cache
+   * @method clear
+   */
+  clear() {
+    this._cache.clear();
+  }
+  /**
+   * 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 });
+    }
+    import_node_fs.default.writeFileSync(filePath, data);
+  }
+  /**
+   * Remove the file where the cache is persisted
+   * @method removeCacheFile
+   * @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;
+    }
+    return false;
+  }
+  /**
+   * Destroy the cache. This will remove the directory, file, and memory cache
+   * @method destroy
+   * @param [includeCacheDir=false] {Boolean} if true, the cache directory will be removed
+   * @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 });
+    }
+  }
+  /**
+   * Start the auto persist interval
+   * @method startAutoPersist
+   */
+  startAutoPersist() {
+    if (this._persistInterval > 0) {
+      if (this._persistTimer) {
+        clearInterval(this._persistTimer);
+        this._persistTimer = void 0;
+      }
+      this._persistTimer = setInterval(() => {
+        this.save();
+      }, this._persistInterval);
+    }
+  }
+  /**
+   * Stop the auto persist interval
+   * @method stopAutoPersist
+   */
+  stopAutoPersist() {
+    if (this._persistTimer) {
+      clearInterval(this._persistTimer);
+      this._persistTimer = void 0;
+    }
+  }
+};
+function create(documentId, cacheDirectory, options) {
+  const cache = new FlatCache(options);
+  cache.cacheId = documentId;
+  if (cacheDirectory) {
+    cache.cacheDir = cacheDirectory;
+  }
+  cache.load(documentId, cacheDirectory);
+  return cache;
+}
+function createFromFile(filePath, options) {
+  const cache = new FlatCache(options);
+  cache.loadFile(filePath);
+  return cache;
+}
+function clearCacheById(cacheId, cacheDirectory) {
+  const cache = new FlatCache({ cacheId, cacheDir: cacheDirectory });
+  cache.destroy();
+}
+function clearAll(cacheDirectory) {
+  import_node_fs.default.rmSync(cacheDirectory ?? ".cache", { recursive: true, force: true });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FlatCache,
+  clearAll,
+  clearCacheById,
+  create,
+  createFromFile
+});