@cacheable/node-cache 0.5.0 → 1.0.0

package/LICENSE

@@ -1,4 +1,4 @@
-MIT License
+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

package/README.md

@@ -4,7 +4,7 @@
 
 > Simple and Maintained fast Node.js caching
 
-[![codecov](https://codecov.io/gh/jaredwray/cacheable/branch/master/graph/badge.svg?token=LDLaqe4PsI)](https://codecov.io/gh/jaredwray/cacheable)
+[![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/cacheable.svg)](https://www.npmjs.com/package/cacheable)
 [![npm](https://img.shields.io/npm/v/cacheable)](https://www.npmjs.com/package/cacheable)
@@ -22,6 +22,7 @@ Note: `NodeCache` is ready and available for use. `NodeCacheStore` is in progres
 * [Getting Started](#getting-started)
 * [Basic Usage](#basic-usage)
 * [Advanced Usage](#advanced-usage)
+* [NodeCacheStore](#nodecachestore)
 * [API](#api)
 * [How to Contribute](#how-to-contribute)
 * [License and Copyright](#license-and-copyright)
@@ -60,6 +61,46 @@ await cache.get('foo'); // 'bar'
 cache.getStats(); // {hits: 1, misses: 1, keys: 1, ksize: 2, vsize: 3}
 ```
 
+## NodeCacheStore
+
+The `NodeCacheStore` is a class that extends the `NodeCache` and adds the ability to use storage adapters. This is based on the `cacheable` engine and allows you to do layer 1 and layer 2 caching. The storage adapters are based on the [Keyv](https://keyv.org) package. This allows you to use any of the storage adapters that are available.
+
+```javascript
+import {NodeCacheStore} from '@cacheable/node-cache';
+
+const cache = new NodeCacheStore();
+cache.set('foo', 'bar');
+cache.get('foo'); // 'bar'
+```
+
+### NodeCacheStoreOptions
+
+When initializing the cache you can pass in the options below:
+
+```javascript
+export type NodeCacheStoreOptions = {
+	ttl?: number; // The standard ttl as number in seconds for every generated cache element. 0 = unlimited
+	primary?: Keyv; // The primary storage adapter
+	secondary?: Keyv; // The secondary storage adapter
+	maxKeys?: number; // Default is 0 (unlimited). If this is set it will throw and error if you try to set more keys than the max.
+};
+```
+
+### Node Cache Store API
+
+* `set(key: string | number, value: any, ttl?: number): Promise<boolean>` - Set a key value pair with an optional ttl (in milliseconds). Will return true on success. If the ttl is not set it will default to 0 (no ttl)
+* `mset(data: Array<NodeCacheItem>): Promise<boolean>` - Set multiple key value pairs at once
+* `get(key: string | number): Promise<any>` - Get a value from the cache by key
+* `mget(keys: Array<string | number>): Promise<Record<string, unknown>>` - Get multiple values from the cache by keys
+* `del(key: string | number): Promise<boolean>` - Delete a key
+* `mdel(keys: Array<string | number>): Promise<boolean>` - Delete multiple keys
+* `clear(): Promise<void>` - Clear the cache
+* `stats`: `NodeCacheStats` - Get the stats of the cache
+* `ttl`: `number` - The standard ttl as number in seconds for every generated cache element. 0 = unlimited
+* `primary`: `Keyv` - The primary storage adapter
+* `secondary`: `Keyv` - The secondary storage adapter
+* `maxKeys`: `number` - If this is set it will throw and error if you try to set more keys than the max
+
 ## API
 
 ### `constructor(options?: NodeCacheOptions)`
@@ -259,4 +300,4 @@ cache.on('set', (key, value) => {
 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](https://github.com/jaredwray/cacheable/blob/main/LICENSE)
+[MIT © Jared Wray](./LICENSE)

package/dist/index.cjs

@@ -0,0 +1,398 @@
+"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, {
+  NodeCacheErrors: () => NodeCacheErrors,
+  NodeCacheStore: () => NodeCacheStore,
+  default: () => NodeCache
+});
+module.exports = __toCommonJS(src_exports);
+var import_eventemitter3 = __toESM(require("eventemitter3"), 1);
+var import_cacheable2 = require("cacheable");
+
+// src/store.ts
+var import_cacheable = require("cacheable");
+var import_keyv = require("keyv");
+var NodeCacheStore = class {
+  _maxKeys = 0;
+  _cache = new import_cacheable.Cacheable({ primary: new import_keyv.Keyv({ store: new import_cacheable.CacheableMemory() }) });
+  constructor(options) {
+    if (options) {
+      const cacheOptions = {
+        ttl: options.ttl,
+        primary: options.primary,
+        secondary: options.secondary
+      };
+      this._cache = new import_cacheable.Cacheable(cacheOptions);
+      if (options.maxKeys) {
+        this._maxKeys = options.maxKeys;
+        if (this._maxKeys > 0) {
+          this._cache.stats.enabled = true;
+        }
+      }
+    }
+  }
+  get cache() {
+    return this._cache;
+  }
+  get ttl() {
+    return this._cache.ttl;
+  }
+  set ttl(ttl) {
+    this._cache.ttl = ttl;
+  }
+  get primary() {
+    return this._cache.primary;
+  }
+  set primary(primary) {
+    this._cache.primary = primary;
+  }
+  get secondary() {
+    return this._cache.secondary;
+  }
+  set secondary(secondary) {
+    this._cache.secondary = secondary;
+  }
+  get maxKeys() {
+    return this._maxKeys;
+  }
+  set maxKeys(maxKeys) {
+    this._maxKeys = maxKeys;
+    if (this._maxKeys > 0) {
+      this._cache.stats.enabled = true;
+    }
+  }
+  async set(key, value, ttl) {
+    if (this._maxKeys > 0) {
+      console.log(this._cache.stats.count, this._maxKeys);
+      if (this._cache.stats.count >= this._maxKeys) {
+        return false;
+      }
+    }
+    const finalTtl = ttl ?? this._cache.ttl;
+    await this._cache.set(key.toString(), value, finalTtl);
+    return true;
+  }
+  async mset(list) {
+    const items = new Array();
+    for (const item of list) {
+      items.push({ key: item.key.toString(), value: item.value, ttl: item.ttl });
+    }
+    await this._cache.setMany(items);
+  }
+  async get(key) {
+    return this._cache.get(key.toString());
+  }
+  async mget(keys) {
+    const result = {};
+    for (const key of keys) {
+      result[key.toString()] = await this._cache.get(key.toString());
+    }
+    return result;
+  }
+  async del(key) {
+    return this._cache.delete(key.toString());
+  }
+  async mdel(keys) {
+    return this._cache.deleteMany(keys.map((key) => key.toString()));
+  }
+  async clear() {
+    return this._cache.clear();
+  }
+};
+
+// src/index.ts
+var NodeCacheErrors = /* @__PURE__ */ ((NodeCacheErrors2) => {
+  NodeCacheErrors2["ECACHEFULL"] = "Cache max keys amount exceeded";
+  NodeCacheErrors2["EKEYTYPE"] = "The key argument has to be of type `string` or `number`. Found: `__key`";
+  NodeCacheErrors2["EKEYSTYPE"] = "The keys argument has to be an array.";
+  NodeCacheErrors2["ETTLTYPE"] = "The ttl argument has to be a number.";
+  return NodeCacheErrors2;
+})(NodeCacheErrors || {});
+var NodeCache = class extends import_eventemitter3.default {
+  options = {
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    stdTTL: 0,
+    checkperiod: 600,
+    useClones: true,
+    deleteOnExpire: true,
+    maxKeys: -1
+  };
+  store = /* @__PURE__ */ new Map();
+  _stats = new import_cacheable2.CacheableStats({ enabled: true });
+  _cacheable = new import_cacheable2.CacheableMemory();
+  intervalId = 0;
+  constructor(options) {
+    super();
+    if (options) {
+      this.options = { ...this.options, ...options };
+    }
+    this.startInterval();
+  }
+  // Sets a key value pair. It is possible to define a ttl (in seconds). Returns true on success.
+  set(key, value, ttl) {
+    if (typeof key !== "string" && typeof key !== "number") {
+      throw this.createError("The key argument has to be of type `string` or `number`. Found: `__key`" /* EKEYTYPE */, key);
+    }
+    if (ttl && typeof ttl !== "number") {
+      throw this.createError("The ttl argument has to be a number." /* ETTLTYPE */, this.formatKey(key));
+    }
+    const keyValue = this.formatKey(key);
+    const ttlValue = ttl ?? this.options.stdTTL;
+    let expirationTimestamp = 0;
+    if (ttlValue && ttlValue > 0) {
+      expirationTimestamp = this.getExpirationTimestamp(ttlValue);
+    }
+    if (this.options.maxKeys) {
+      const maxKeys = this.options.maxKeys;
+      if (maxKeys > -1 && this.store.size >= maxKeys) {
+        throw this.createError("Cache max keys amount exceeded" /* ECACHEFULL */, this.formatKey(key));
+      }
+    }
+    this.store.set(keyValue, { key: keyValue, value, ttl: expirationTimestamp });
+    this.emit("set", keyValue, value, ttlValue);
+    this._stats.incrementKSize(keyValue);
+    this._stats.incrementVSize(value);
+    this._stats.setCount(this.store.size);
+    return true;
+  }
+  // Sets multiple key val pairs. It is possible to define a ttl (seconds). Returns true on success.
+  mset(data) {
+    if (!Array.isArray(data)) {
+      throw this.createError("The keys argument has to be an array." /* EKEYSTYPE */);
+    }
+    for (const item of data) {
+      this.set(item.key, item.value, item.ttl);
+    }
+    return true;
+  }
+  // Gets a saved value from the cache. Returns a undefined if not found or expired. If the value was found it returns the value.
+  get(key) {
+    const result = this.store.get(this.formatKey(key));
+    if (result) {
+      if (result.ttl > 0) {
+        if (result.ttl < Date.now()) {
+          if (this.options.deleteOnExpire) {
+            this.del(key);
+          }
+          this._stats.incrementMisses();
+          this.emit("expired", this.formatKey(key), result.value);
+          return void 0;
+        }
+        this._stats.incrementHits();
+        if (this.options.useClones) {
+          return this._cacheable.clone(result.value);
+        }
+        return result.value;
+      }
+      this._stats.incrementHits();
+      if (this.options.useClones) {
+        return this._cacheable.clone(result.value);
+      }
+      return result.value;
+    }
+    this._stats.incrementMisses();
+    return void 0;
+  }
+  /*
+  	Gets multiple saved values from the cache. Returns an empty object {} if not found or expired.
+  	If the value was found it returns an object with the key value pair.
+  */
+  mget(keys) {
+    const result = {};
+    for (const key of keys) {
+      const value = this.get(key);
+      if (value) {
+        result[this.formatKey(key)] = value;
+      }
+    }
+    return result;
+  }
+  /*
+  	Get the cached value and remove the key from the cache.
+  	Equivalent to calling get(key) + del(key).
+  	Useful for implementing single use mechanism such as OTP, where once a value is read it will become obsolete.
+  */
+  take(key) {
+    const result = this.get(key);
+    if (result) {
+      this.del(key);
+      if (this.options.useClones) {
+        return this._cacheable.clone(result);
+      }
+      return result;
+    }
+    return void 0;
+  }
+  // Delete a key. Returns the number of deleted entries. A delete will never fail.
+  del(key) {
+    if (Array.isArray(key)) {
+      return this.mdel(key);
+    }
+    const result = this.store.get(this.formatKey(key));
+    if (result) {
+      const keyValue = this.formatKey(key);
+      this.store.delete(keyValue);
+      this.emit("del", keyValue, result.value);
+      this._stats.decreaseKSize(keyValue);
+      this._stats.decreaseVSize(result.value);
+      this._stats.setCount(this.store.size);
+      return 1;
+    }
+    return 0;
+  }
+  // Delete all keys in Array that exist. Returns the number of deleted entries.
+  mdel(keys) {
+    let result = 0;
+    for (const key of keys) {
+      result += this.del(key);
+    }
+    return result;
+  }
+  // Redefine the ttl of a key. Returns true if the key has been found and changed.
+  // Otherwise returns false. If the ttl-argument isn't passed the default-TTL will be used.
+  ttl(key, ttl) {
+    const result = this.store.get(this.formatKey(key));
+    if (result) {
+      const ttlValue = ttl ?? this.options.stdTTL;
+      result.ttl = this.getExpirationTimestamp(ttlValue);
+      this.store.set(this.formatKey(key), result);
+      return true;
+    }
+    return false;
+  }
+  /*
+  		Receive the ttl of a key. You will get:
+  
+  		undefined if the key does not exist
+  		0 if this key has no ttl
+  		a timestamp in ms representing the time at which the key will expire
+  	*/
+  getTtl(key) {
+    const result = this.store.get(this.formatKey(key));
+    if (result) {
+      if (result.ttl === 0) {
+        return 0;
+      }
+      return result.ttl;
+    }
+    return void 0;
+  }
+  /*
+  	Returns an array of all existing keys.
+  	[ "all", "my", "keys", "foo", "bar" ]
+  */
+  keys() {
+    const result = [];
+    for (const key of this.store.keys()) {
+      result.push(key);
+    }
+    return result;
+  }
+  // Returns boolean indicating if the key is cached.
+  has(key) {
+    return this.store.has(this.formatKey(key));
+  }
+  // Gets the stats of the cache.
+  getStats() {
+    const stats = {
+      keys: this._stats.count,
+      hits: this._stats.hits,
+      misses: this._stats.misses,
+      ksize: this._stats.ksize,
+      vsize: this._stats.vsize
+    };
+    return stats;
+  }
+  // Flush the whole data.
+  flushAll() {
+    this.store.clear();
+    this.flushStats();
+    this.emit("flush");
+  }
+  // Flush the stats
+  flushStats() {
+    this._stats = new import_cacheable2.CacheableStats({ enabled: true });
+    this.emit("flush_stats");
+  }
+  // Close the cache. This will clear the interval timeout which is set on check period option.
+  close() {
+    this.stopInterval();
+  }
+  // Get the interval id
+  getIntervalId() {
+    return this.intervalId;
+  }
+  formatKey(key) {
+    return key.toString();
+  }
+  getExpirationTimestamp(ttlInSeconds) {
+    const currentTimestamp = Date.now();
+    const ttlInMilliseconds = ttlInSeconds * 1e3;
+    const expirationTimestamp = currentTimestamp + ttlInMilliseconds;
+    return expirationTimestamp;
+  }
+  startInterval() {
+    if (this.options.checkperiod && this.options.checkperiod > 0) {
+      const checkPeriodinSeconds = this.options.checkperiod * 1e3;
+      this.intervalId = setInterval(() => {
+        this.checkData();
+      }, checkPeriodinSeconds);
+      return;
+    }
+    this.intervalId = 0;
+  }
+  checkData() {
+    for (const [key, value] of this.store.entries()) {
+      if (value.ttl > 0 && value.ttl < Date.now()) {
+        this.del(key);
+      }
+    }
+  }
+  stopInterval() {
+    if (this.intervalId !== 0) {
+      clearInterval(this.intervalId);
+      this.intervalId = 0;
+    }
+  }
+  createError(errorCode, key) {
+    let error = errorCode;
+    if (key) {
+      error = error.replace("__key", key);
+    }
+    return new Error(error);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  NodeCacheErrors,
+  NodeCacheStore
+});

package/dist/index.d.cts

@@ -0,0 +1,89 @@
+import eventemitter from 'eventemitter3';
+import { Cacheable } from 'cacheable';
+import { Keyv } from 'keyv';
+
+type NodeCacheStoreOptions = {
+    ttl?: number;
+    maxKeys?: number;
+    primary?: Keyv;
+    secondary?: Keyv;
+};
+declare class NodeCacheStore {
+    private _maxKeys;
+    private readonly _cache;
+    constructor(options?: NodeCacheStoreOptions);
+    get cache(): Cacheable;
+    get ttl(): number | undefined;
+    set ttl(ttl: number | undefined);
+    get primary(): Keyv;
+    set primary(primary: Keyv);
+    get secondary(): Keyv | undefined;
+    set secondary(secondary: Keyv | undefined);
+    get maxKeys(): number;
+    set maxKeys(maxKeys: number);
+    set(key: string | number, value: any, ttl?: number): Promise<boolean>;
+    mset(list: NodeCacheItem[]): Promise<void>;
+    get<T>(key: string | number): Promise<T | undefined>;
+    mget<T>(keys: Array<string | number>): Promise<Record<string, T | undefined>>;
+    del(key: string | number): Promise<boolean>;
+    mdel(keys: Array<string | number>): Promise<boolean>;
+    clear(): Promise<void>;
+}
+
+type NodeCacheOptions = {
+    stdTTL?: number;
+    checkperiod?: number;
+    useClones?: boolean;
+    deleteOnExpire?: boolean;
+    maxKeys?: number;
+};
+type NodeCacheItem = {
+    key: string | number;
+    value: any;
+    ttl?: number;
+};
+declare enum NodeCacheErrors {
+    ECACHEFULL = "Cache max keys amount exceeded",
+    EKEYTYPE = "The key argument has to be of type `string` or `number`. Found: `__key`",
+    EKEYSTYPE = "The keys argument has to be an array.",
+    ETTLTYPE = "The ttl argument has to be a number."
+}
+type NodeCacheStats = {
+    keys: number;
+    hits: number;
+    misses: number;
+    ksize: number;
+    vsize: number;
+};
+declare class NodeCache extends eventemitter {
+    readonly options: NodeCacheOptions;
+    readonly store: Map<string, any>;
+    private _stats;
+    private readonly _cacheable;
+    private intervalId;
+    constructor(options?: NodeCacheOptions);
+    set(key: string | number, value: any, ttl?: number): boolean;
+    mset(data: NodeCacheItem[]): boolean;
+    get(key: string | number): any;
+    mget(keys: Array<string | number>): Record<string, unknown>;
+    take(key: string | number): any;
+    del(key: string | number | Array<string | number>): number;
+    mdel(keys: Array<string | number>): number;
+    ttl(key: string | number, ttl?: number): boolean;
+    getTtl(key: string | number): number | undefined;
+    keys(): string[];
+    has(key: string | number): boolean;
+    getStats(): NodeCacheStats;
+    flushAll(): void;
+    flushStats(): void;
+    close(): void;
+    getIntervalId(): number | NodeJS.Timeout;
+    private formatKey;
+    private getExpirationTimestamp;
+    private startInterval;
+    private checkData;
+    private stopInterval;
+    private createError;
+}
+
+export { NodeCacheErrors, type NodeCacheItem, type NodeCacheOptions, type NodeCacheStats, NodeCacheStore, type NodeCacheStoreOptions, NodeCache as default };

package/dist/index.d.ts

@@ -1,33 +1,65 @@
 import eventemitter from 'eventemitter3';
-export type NodeCacheOptions = {
+import { Cacheable } from 'cacheable';
+import { Keyv } from 'keyv';
+
+type NodeCacheStoreOptions = {
+    ttl?: number;
+    maxKeys?: number;
+    primary?: Keyv;
+    secondary?: Keyv;
+};
+declare class NodeCacheStore {
+    private _maxKeys;
+    private readonly _cache;
+    constructor(options?: NodeCacheStoreOptions);
+    get cache(): Cacheable;
+    get ttl(): number | undefined;
+    set ttl(ttl: number | undefined);
+    get primary(): Keyv;
+    set primary(primary: Keyv);
+    get secondary(): Keyv | undefined;
+    set secondary(secondary: Keyv | undefined);
+    get maxKeys(): number;
+    set maxKeys(maxKeys: number);
+    set(key: string | number, value: any, ttl?: number): Promise<boolean>;
+    mset(list: NodeCacheItem[]): Promise<void>;
+    get<T>(key: string | number): Promise<T | undefined>;
+    mget<T>(keys: Array<string | number>): Promise<Record<string, T | undefined>>;
+    del(key: string | number): Promise<boolean>;
+    mdel(keys: Array<string | number>): Promise<boolean>;
+    clear(): Promise<void>;
+}
+
+type NodeCacheOptions = {
     stdTTL?: number;
     checkperiod?: number;
     useClones?: boolean;
     deleteOnExpire?: boolean;
     maxKeys?: number;
 };
-export type NodeCacheItem = {
+type NodeCacheItem = {
     key: string | number;
     value: any;
     ttl?: number;
 };
-export declare enum NodeCacheErrors {
+declare enum NodeCacheErrors {
     ECACHEFULL = "Cache max keys amount exceeded",
     EKEYTYPE = "The key argument has to be of type `string` or `number`. Found: `__key`",
     EKEYSTYPE = "The keys argument has to be an array.",
     ETTLTYPE = "The ttl argument has to be a number."
 }
-export type NodeCacheStats = {
+type NodeCacheStats = {
     keys: number;
     hits: number;
     misses: number;
     ksize: number;
     vsize: number;
 };
-export default class NodeCache extends eventemitter {
+declare class NodeCache extends eventemitter {
     readonly options: NodeCacheOptions;
     readonly store: Map<string, any>;
     private _stats;
+    private readonly _cacheable;
     private intervalId;
     constructor(options?: NodeCacheOptions);
     set(key: string | number, value: any, ttl?: number): boolean;
@@ -48,15 +80,10 @@ export default class NodeCache extends eventemitter {
     getIntervalId(): number | NodeJS.Timeout;
     private formatKey;
     private getExpirationTimestamp;
-    private addHit;
-    private addMiss;
-    private roughSizeOfKey;
-    private roughSizeOfObject;
     private startInterval;
     private checkData;
     private stopInterval;
     private createError;
-    private isPrimitive;
-    private clone;
 }
-//# sourceMappingURL=index.d.ts.map
+
+export { NodeCacheErrors, type NodeCacheItem, type NodeCacheOptions, type NodeCacheStats, NodeCacheStore, type NodeCacheStoreOptions, NodeCache as default };