cacheable 1.6.1 → 1.7.1

package/README.md

@@ -19,10 +19,26 @@
 * Resilient to failures with try/catch and offline
 * Hooks and Events to extend functionality
 * Comprehensive testing and code coverage
+* Shorthand for ttl in milliseconds `(1m = 60000) (1h = 3600000) (1d = 86400000)`
 * Distributed Caching Sync via Pub/Sub (coming soon)
 * ESM and CommonJS support with TypeScript
 * Maintained and supported regularly
 
+## Table of Contents
+* [Getting Started](#getting-started)
+* [Basic Usage](#basic-usage)
+* [Hooks and Events](#hooks-and-events)
+* [Storage Tiering and Caching](#storage-tiering-and-caching)
+* [Shorthand for Time to Live (ttl)](#shorthand-for-time-to-live-ttl)
+* [Non-Blocking Operations](#non-blocking-operations)
+* [CacheSync - Distributed Updates](#cachesync---distributed-updates)
+* [Cacheable Options](#cacheable-options)
+* [Cacheable Statistics (Instance Only)](#cacheable-statistics-instance-only)
+* [API](#api)
+* [CacheableMemory - In-Memory Cache](#cacheablememory---in-memory-cache)
+* [How to Contribute](#how-to-contribute)
+* [License and Copyright](#license-and-copyright)
+
 ## Getting Started
 
 `cacheable` is primarily used as an extension to you caching engine with a robust storage backend [Keyv](https://keyv.org), Memonization (Wrap), Hooks, Events, and Statistics.
@@ -99,6 +115,44 @@ cacheable.onHook(CacheableHooks.BEFORE_SET, (data) => {
 * `Deleting Data`: Deletes the value from the primary store and secondary store at the same time waiting for both to respond.
 * `Clearing Data`: Clears the primary store and secondary store at the same time waiting for both to respond.
 
+# Shorthand for Time to Live (ttl)
+
+By default `Cacheable` and `CacheableMemory` the `ttl` is in milliseconds but you can use shorthand for the time to live. Here are the following shorthand values:
+
+* `ms`: Milliseconds such as (1ms = 1)
+* `s`: Seconds such as (1s = 1000)
+* `m`: Minutes such as (1m = 60000)
+* `h` or `hr`: Hours such as (1h = 3600000)
+* `d`: Days such as (1d = 86400000)
+
+Here is an example of how to use the shorthand for the `ttl`:
+
+```javascript
+import { Cacheable } from 'cacheable';
+const cache = new Cacheable({ ttl: '15m' }); //sets the default ttl to 15 minutes (900000 ms)
+cache.set('key', 'value', '1h'); //sets the ttl to 1 hour (3600000 ms) and overrides the default
+```
+
+if you want to disable the `ttl` you can set it to `0` or `undefined`:
+
+```javascript
+import { Cacheable } from 'cacheable';
+const cache = new Cacheable({ ttl: 0 }); //sets the default ttl to 0 which is disabled
+cache.set('key', 'value', 0); //sets the ttl to 0 which is disabled
+```
+
+If you set the ttl to anything below `0` or `undefined` it will disable the ttl for the cache and the value that returns will be `undefined`. With no ttl set the value will be stored `indefinitely`.
+
+```javascript
+import { Cacheable } from 'cacheable';
+const cache = new Cacheable({ ttl: 0 }); //sets the default ttl to 0 which is disabled
+console.log(cache.ttl); // undefined
+cache.ttl = '1h'; // sets the default ttl to 1 hour (3600000 ms)
+console.log(cache.ttl); // '1h'
+cache.ttl = -1; // sets the default ttl to 0 which is disabled
+console.log(cache.ttl); // undefined
+```
+
 ## Non-Blocking Operations
 
 If you want your layer 2 (secondary) store to be non-blocking you can set the `nonBlocking` property to `true` in the options. This will make the secondary store non-blocking and will not wait for the secondary store to respond on `setting data`, `deleting data`, or `clearing data`. This is useful if you want to have a faster response time and not wait for the secondary store to respond.
@@ -131,6 +185,7 @@ The following options are available for you to configure `cacheable`:
 * `secondary`: The secondary store for the cache (layer 2) usually a persistent cache by Keyv.
 * `nonBlocking`: If the secondary store is non-blocking. Default is `false`.
 * `stats`: To enable statistics for this instance. Default is `false`.
+* `ttl`: The default time to live for the cache in milliseconds. Default is `undefined` which is disabled.
 
 ## Cacheable Statistics (Instance Only)
 
@@ -181,7 +236,7 @@ _This does not enable statistics for your layer 2 cache as that is a distributed
 ```javascript
 import { CacheableMemory } from 'cacheable';
 const options = {
-  ttl: 60 * 60 * 1000, // 1 hour
+  ttl: '1h', // 1 hour
   useClones: true, // use clones for the values (default is true)
   lruSize: 1000, // the size of the LRU cache (default is 0 which is unlimited)
 }
@@ -198,7 +253,7 @@ By default we use lazy expiration deletion which means on `get` and `getMany` ty
 
 ### CacheableMemory Options
 
-* `ttl`: The time to live for the cache in milliseconds.
+* `ttl`: The time to live for the cache in milliseconds. Default is `undefined` which is means indefinitely.
 * `useClones`: If the cache should use clones for the values. Default is `true`.
 * `lruSize`: The size of the LRU cache. Default is `0` which is unlimited.
 * `checkInterval`: The interval to check for expired keys in milliseconds. Default is `0` which is disabled.
@@ -206,13 +261,20 @@ By default we use lazy expiration deletion which means on `get` and `getMany` ty
 ### CacheableMemory API
 
 * `set(key, value, ttl?)`: Sets a value in the cache.
+* `setMany([{key, value, ttl?}])`: Sets multiple values in the cache from `CachableItem`.
 * `get(key)`: Gets a value from the cache.
+* `getMany([keys])`: Gets multiple values from the cache.
+* `getRaw(key)`: Gets a value from the cache as `CacheableStoreItem`.
+* `getManyRaw([keys])`: Gets multiple values from the cache as `CacheableStoreItem`.
 * `has(key)`: Checks if a value exists in the cache.
 * `delete(key)`: Deletes a value from the cache.
+* `deleteMany([keys])`: Deletes multiple values from the cache.
+* `take(key)`: Takes a value from the cache and deletes it.
+* `takeMany([keys])`: Takes multiple values from the cache and deletes them.
 * `clear()`: Clears the cache.
 * `size()`: The number of keys in the cache.
 * `keys()`: The keys in the cache.
-* `items()`: The items in the cache as `{ key, value, expiration }`.
+* `items()`: The items in the cache as `CacheableStoreItem` example `{ key, value, expires? }`.
 * `checkExpired()`: Checks for expired keys in the cache. This is used by the `checkInterval` property.
 * `startIntervalCheck()`: Starts the interval check for expired keys if `checkInterval` is above 0 ms.
 * `stopIntervalCheck()`: Stops the interval check for expired keys.

package/dist/index.cjs

@@ -25,12 +25,81 @@ __export(src_exports, {
   CacheableHooks: () => CacheableHooks,
   CacheableMemory: () => CacheableMemory,
   CacheableStats: () => CacheableStats,
-  KeyvCacheableMemory: () => KeyvCacheableMemory
+  KeyvCacheableMemory: () => KeyvCacheableMemory,
+  shorthandToMilliseconds: () => shorthandToMilliseconds,
+  shorthandToTime: () => shorthandToTime
 });
 module.exports = __toCommonJS(src_exports);
 var import_keyv = require("keyv");
 var import_hookified = require("hookified");
 
+// src/shorthand-time.ts
+var shorthandToMilliseconds = (shorthand) => {
+  let milliseconds;
+  if (shorthand === void 0) {
+    return void 0;
+  }
+  if (typeof shorthand === "number") {
+    milliseconds = shorthand;
+  } else if (typeof shorthand === "string") {
+    shorthand = shorthand.trim();
+    if (Number.isNaN(Number(shorthand))) {
+      const match = /^([\d.]+)\s*(ms|s|m|h|hr|d)$/i.exec(shorthand);
+      if (!match) {
+        throw new Error(
+          `Unsupported time format: "${shorthand}". Use 'ms', 's', 'm', 'h', 'hr', or 'd'.`
+        );
+      }
+      const [, value, unit] = match;
+      const numericValue = Number.parseFloat(value);
+      const unitLower = unit.toLowerCase();
+      switch (unitLower) {
+        case "ms": {
+          milliseconds = numericValue;
+          break;
+        }
+        case "s": {
+          milliseconds = numericValue * 1e3;
+          break;
+        }
+        case "m": {
+          milliseconds = numericValue * 1e3 * 60;
+          break;
+        }
+        case "h": {
+          milliseconds = numericValue * 1e3 * 60 * 60;
+          break;
+        }
+        case "hr": {
+          milliseconds = numericValue * 1e3 * 60 * 60;
+          break;
+        }
+        case "d": {
+          milliseconds = numericValue * 1e3 * 60 * 60 * 24;
+          break;
+        }
+        /* c8 ignore next 3 */
+        default: {
+          milliseconds = Number(shorthand);
+        }
+      }
+    } else {
+      milliseconds = Number(shorthand);
+    }
+  } else {
+    throw new TypeError("Time must be a string or a number.");
+  }
+  return milliseconds;
+};
+var shorthandToTime = (shorthand, fromDate) => {
+  fromDate ||= /* @__PURE__ */ new Date();
+  const milliseconds = shorthandToMilliseconds(shorthand);
+  if (milliseconds === void 0) {
+    return fromDate.getTime();
+  }
+  return fromDate.getTime() + milliseconds;
+};
+
 // src/memory-lru.ts
 var ListNode = class {
   // eslint-disable-next-line @typescript-eslint/parameter-properties
@@ -118,7 +187,7 @@ var CacheableMemory = class {
   _hash8 = /* @__PURE__ */ new Map();
   _hash9 = /* @__PURE__ */ new Map();
   _lru = new DoublyLinkedList();
-  _ttl = 0;
+  _ttl;
   // Turned off by default
   _useClone = true;
   // Turned on by default
@@ -130,7 +199,7 @@ var CacheableMemory = class {
   // Turned off by default
   constructor(options) {
     if (options?.ttl) {
-      this._ttl = options.ttl;
+      this.setTtl(options.ttl);
     }
     if (options?.useClone !== void 0) {
       this._useClone = options.useClone;
@@ -147,7 +216,7 @@ var CacheableMemory = class {
     return this._ttl;
   }
   set ttl(value) {
-    this._ttl = value;
+    this.setTtl(value);
   }
   get useClone() {
     return this._useClone;
@@ -193,11 +262,41 @@ var CacheableMemory = class {
     }
     return this.clone(item.value);
   }
+  getMany(keys) {
+    const result = new Array();
+    for (const key of keys) {
+      result.push(this.get(key));
+    }
+    return result;
+  }
+  getRaw(key) {
+    const store = this.getStore(key);
+    const item = store.get(key);
+    if (!item) {
+      return void 0;
+    }
+    if (item.expires && item.expires && Date.now() > item.expires) {
+      store.delete(key);
+      return void 0;
+    }
+    this.lruMoveToFront(key);
+    return item;
+  }
+  getManyRaw(keys) {
+    const result = new Array();
+    for (const key of keys) {
+      result.push(this.getRaw(key));
+    }
+    return result;
+  }
   set(key, value, ttl) {
     const store = this.getStore(key);
     let expires;
-    if (ttl !== void 0 || this._ttl !== 0) {
-      expires = Date.now() + (ttl ?? this._ttl);
+    if (ttl !== void 0 || this._ttl !== void 0) {
+      const finalTtl = shorthandToTime(ttl ?? this._ttl);
+      if (finalTtl !== void 0) {
+        expires = finalTtl;
+      }
     }
     if (this._lruSize > 0) {
       if (store.has(key)) {
@@ -220,6 +319,11 @@ var CacheableMemory = class {
       expires
     });
   }
+  setMany(items) {
+    for (const item of items) {
+      this.set(item.key, item.value, item.ttl);
+    }
+  }
   has(key) {
     const item = this.get(key);
     return Boolean(item);
@@ -232,10 +336,22 @@ var CacheableMemory = class {
     this.delete(key);
     return item;
   }
+  takeMany(keys) {
+    const result = new Array();
+    for (const key of keys) {
+      result.push(this.take(key));
+    }
+    return result;
+  }
   delete(key) {
     const store = this.getStore(key);
     store.delete(key);
   }
+  deleteMany(keys) {
+    for (const key of keys) {
+      this.delete(key);
+    }
+  }
   clear() {
     this._hash0.clear();
     this._hash1.clear();
@@ -364,6 +480,15 @@ var CacheableMemory = class {
     const result = new Map([...this._hash0, ...this._hash1, ...this._hash2, ...this._hash3, ...this._hash4, ...this._hash5, ...this._hash6, ...this._hash7, ...this._hash8, ...this._hash9]);
     return result;
   }
+  setTtl(ttl) {
+    if (typeof ttl === "string" || ttl === void 0) {
+      this._ttl = ttl;
+    } else if (ttl > 0) {
+      this._ttl = ttl;
+    } else {
+      this._ttl = void 0;
+    }
+  }
 };
 
 // src/keyv-memory.ts
@@ -384,38 +509,35 @@ var KeyvCacheableMemory = class {
   }
   async get(key) {
     const result = this._cache.get(key);
-    console.log("result", result);
     if (result) {
       return result;
     }
     return void 0;
   }
-  set(key, value, ttl) {
+  async getMany(keys) {
+    const result = this._cache.getMany(keys);
+    return result;
+  }
+  async set(key, value, ttl) {
     this._cache.set(key, value, ttl);
   }
+  async setMany(values) {
+    this._cache.setMany(values);
+  }
   async delete(key) {
     this._cache.delete(key);
     return true;
   }
+  async deleteMany(key) {
+    this._cache.deleteMany(key);
+    return true;
+  }
   async clear() {
     this._cache.clear();
   }
   async has(key) {
     return this._cache.has(key);
   }
-  async getMany(keys) {
-    const result = [];
-    for (const key of keys) {
-      result.push(this._cache.get(key));
-    }
-    return result;
-  }
-  async deleteMany(key) {
-    for (const k of key) {
-      this._cache.delete(k);
-    }
-    return true;
-  }
   on(event, listener) {
     return this;
   }
@@ -633,7 +755,7 @@ var Cacheable = class extends import_hookified.Hookified {
       this._stats.enabled = options.stats;
     }
     if (options?.ttl) {
-      this._ttl = options.ttl;
+      this.setTtl(options.ttl);
     }
   }
   get stats() {
@@ -661,7 +783,7 @@ var Cacheable = class extends import_hookified.Hookified {
     return this._ttl;
   }
   set ttl(ttl) {
-    this._ttl = ttl;
+    this.setTtl(ttl);
   }
   setPrimary(primary) {
     this._primary = primary instanceof import_keyv.Keyv ? primary : new import_keyv.Keyv(primary);
@@ -677,7 +799,8 @@ var Cacheable = class extends import_hookified.Hookified {
       if (!result && this._secondary) {
         result = await this._secondary.get(key);
         if (result) {
-          await this._primary.set(key, result, this._ttl);
+          const finalTtl = shorthandToMilliseconds(this._ttl);
+          await this._primary.set(key, result, finalTtl);
         }
       }
       await this.hook("AFTER_GET" /* AFTER_GET */, { key, result });
@@ -710,7 +833,8 @@ var Cacheable = class extends import_hookified.Hookified {
         for (const [i, key] of keys.entries()) {
           if (!result[i] && secondaryResult[i]) {
             result[i] = secondaryResult[i];
-            await this._primary.set(key, secondaryResult[i], this._ttl);
+            const finalTtl = shorthandToMilliseconds(this._ttl);
+            await this._primary.set(key, secondaryResult[i], finalTtl);
           }
         }
       }
@@ -732,7 +856,7 @@ var Cacheable = class extends import_hookified.Hookified {
   }
   async set(key, value, ttl) {
     let result = false;
-    const finalTtl = ttl ?? this._ttl;
+    const finalTtl = shorthandToMilliseconds(ttl ?? this._ttl);
     try {
       const item = { key, value, ttl: finalTtl };
       await this.hook("BEFORE_SET" /* BEFORE_SET */, item);
@@ -901,7 +1025,7 @@ var Cacheable = class extends import_hookified.Hookified {
   async setManyKeyv(keyv, items) {
     const promises = [];
     for (const item of items) {
-      const finalTtl = item.ttl ?? this._ttl;
+      const finalTtl = shorthandToMilliseconds(item.ttl ?? this._ttl);
       promises.push(keyv.set(item.key, item.value, finalTtl));
     }
     await Promise.all(promises);
@@ -914,6 +1038,15 @@ var Cacheable = class extends import_hookified.Hookified {
     }
     return Promise.all(promises);
   }
+  setTtl(ttl) {
+    if (typeof ttl === "string" || ttl === void 0) {
+      this._ttl = ttl;
+    } else if (ttl > 0) {
+      this._ttl = ttl;
+    } else {
+      this._ttl = void 0;
+    }
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -922,5 +1055,7 @@ var Cacheable = class extends import_hookified.Hookified {
   CacheableHooks,
   CacheableMemory,
   CacheableStats,
-  KeyvCacheableMemory
+  KeyvCacheableMemory,
+  shorthandToMilliseconds,
+  shorthandToTime
 });

package/dist/index.d.cts

@@ -46,17 +46,23 @@ declare class CacheableStats {
     resetStoreValues(): void;
 }
 
-type CacheableMemoryOptions = {
-    ttl?: number;
-    useClone?: boolean;
-    lruSize?: number;
-    checkInterval?: number;
+type CacheableItem = {
+    key: string;
+    value: any;
+    ttl?: number | string;
 };
-type CacheableItem$1 = {
+type CacheableStoreItem = {
     key: string;
     value: any;
     expires?: number;
 };
+
+type CacheableMemoryOptions = {
+    ttl?: number | string;
+    useClone?: boolean;
+    lruSize?: number;
+    checkInterval?: number;
+};
 declare class CacheableMemory {
     private readonly _hashCache;
     private readonly _hash0;
@@ -76,8 +82,8 @@ declare class CacheableMemory {
     private _checkInterval;
     private _interval;
     constructor(options?: CacheableMemoryOptions);
-    get ttl(): number;
-    set ttl(value: number);
+    get ttl(): number | string | undefined;
+    set ttl(value: number | string | undefined);
     get useClone(): boolean;
     set useClone(value: boolean);
     get lruSize(): number;
@@ -86,12 +92,18 @@ declare class CacheableMemory {
     set checkInterval(value: number);
     get size(): number;
     get keys(): IterableIterator<string>;
-    get items(): IterableIterator<CacheableItem$1>;
+    get items(): IterableIterator<CacheableStoreItem>;
     get<T>(key: string): any;
-    set(key: string, value: any, ttl?: number): void;
+    getMany<T>(keys: string[]): any[];
+    getRaw(key: string): CacheableStoreItem | undefined;
+    getManyRaw(keys: string[]): Array<CacheableStoreItem | undefined>;
+    set(key: string, value: any, ttl?: number | string): void;
+    setMany(items: CacheableItem[]): void;
     has(key: string): boolean;
     take<T>(key: string): any;
+    takeMany<T>(keys: string[]): any[];
     delete(key: string): void;
+    deleteMany(keys: string[]): void;
     clear(): void;
     hashKey(key: string): number;
     getStore(key: string): Map<string, any>;
@@ -104,6 +116,7 @@ declare class CacheableMemory {
     stopIntervalCheck(): void;
     private isPrimitive;
     private concatStores;
+    private setTtl;
 }
 
 declare class KeyvCacheableMemory implements KeyvStoreAdapter {
@@ -112,15 +125,23 @@ declare class KeyvCacheableMemory implements KeyvStoreAdapter {
     private readonly _cache;
     constructor(options?: CacheableMemoryOptions);
     get<Value>(key: string): Promise<StoredData<Value> | undefined>;
-    set(key: string, value: any, ttl?: number): void;
+    getMany<Value>(keys: string[]): Promise<Array<StoredData<Value | undefined>>>;
+    set(key: string, value: any, ttl?: number): Promise<void>;
+    setMany(values: Array<{
+        key: string;
+        value: any;
+        ttl?: number;
+    }>): Promise<void>;
     delete(key: string): Promise<boolean>;
+    deleteMany?(key: string[]): Promise<boolean>;
     clear(): Promise<void>;
     has?(key: string): Promise<boolean>;
-    getMany?<Value>(keys: string[]): Promise<Array<StoredData<Value | undefined>>>;
-    deleteMany?(key: string[]): Promise<boolean>;
     on(event: string, listener: (...arguments_: any[]) => void): this;
 }
 
+declare const shorthandToMilliseconds: (shorthand?: string | number) => number | undefined;
+declare const shorthandToTime: (shorthand?: string | number, fromDate?: Date) => number;
+
 declare enum CacheableHooks {
     BEFORE_SET = "BEFORE_SET",
     AFTER_SET = "AFTER_SET",
@@ -134,17 +155,12 @@ declare enum CacheableHooks {
 declare enum CacheableEvents {
     ERROR = "error"
 }
-type CacheableItem = {
-    key: string;
-    value: unknown;
-    ttl?: number;
-};
 type CacheableOptions = {
     primary?: Keyv | KeyvStoreAdapter;
     secondary?: Keyv | KeyvStoreAdapter;
     stats?: boolean;
     nonBlocking?: boolean;
-    ttl?: number;
+    ttl?: number | string;
 };
 declare class Cacheable extends Hookified {
     private _primary;
@@ -160,8 +176,8 @@ declare class Cacheable extends Hookified {
     set secondary(secondary: Keyv | undefined);
     get nonBlocking(): boolean;
     set nonBlocking(nonBlocking: boolean);
-    get ttl(): number | undefined;
-    set ttl(ttl: number | undefined);
+    get ttl(): number | string | undefined;
+    set ttl(ttl: number | string | undefined);
     setPrimary(primary: Keyv | KeyvStoreAdapter): void;
     setSecondary(secondary: Keyv | KeyvStoreAdapter): void;
     get<T>(key: string): Promise<T | undefined>;
@@ -179,6 +195,7 @@ declare class Cacheable extends Hookified {
     private deleteManyKeyv;
     private setManyKeyv;
     private hasManyKeyv;
+    private setTtl;
 }
 
-export { Cacheable, CacheableEvents, CacheableHooks, type CacheableItem, CacheableMemory, type CacheableOptions, CacheableStats, KeyvCacheableMemory };
+export { Cacheable, CacheableEvents, CacheableHooks, type CacheableItem, CacheableMemory, type CacheableOptions, CacheableStats, KeyvCacheableMemory, shorthandToMilliseconds, shorthandToTime };

package/dist/index.d.ts

@@ -46,17 +46,23 @@ declare class CacheableStats {
     resetStoreValues(): void;
 }
 
-type CacheableMemoryOptions = {
-    ttl?: number;
-    useClone?: boolean;
-    lruSize?: number;
-    checkInterval?: number;
+type CacheableItem = {
+    key: string;
+    value: any;
+    ttl?: number | string;
 };
-type CacheableItem$1 = {
+type CacheableStoreItem = {
     key: string;
     value: any;
     expires?: number;
 };
+
+type CacheableMemoryOptions = {
+    ttl?: number | string;
+    useClone?: boolean;
+    lruSize?: number;
+    checkInterval?: number;
+};
 declare class CacheableMemory {
     private readonly _hashCache;
     private readonly _hash0;
@@ -76,8 +82,8 @@ declare class CacheableMemory {
     private _checkInterval;
     private _interval;
     constructor(options?: CacheableMemoryOptions);
-    get ttl(): number;
-    set ttl(value: number);
+    get ttl(): number | string | undefined;
+    set ttl(value: number | string | undefined);
     get useClone(): boolean;
     set useClone(value: boolean);
     get lruSize(): number;
@@ -86,12 +92,18 @@ declare class CacheableMemory {
     set checkInterval(value: number);
     get size(): number;
     get keys(): IterableIterator<string>;
-    get items(): IterableIterator<CacheableItem$1>;
+    get items(): IterableIterator<CacheableStoreItem>;
     get<T>(key: string): any;
-    set(key: string, value: any, ttl?: number): void;
+    getMany<T>(keys: string[]): any[];
+    getRaw(key: string): CacheableStoreItem | undefined;
+    getManyRaw(keys: string[]): Array<CacheableStoreItem | undefined>;
+    set(key: string, value: any, ttl?: number | string): void;
+    setMany(items: CacheableItem[]): void;
     has(key: string): boolean;
     take<T>(key: string): any;
+    takeMany<T>(keys: string[]): any[];
     delete(key: string): void;
+    deleteMany(keys: string[]): void;
     clear(): void;
     hashKey(key: string): number;
     getStore(key: string): Map<string, any>;
@@ -104,6 +116,7 @@ declare class CacheableMemory {
     stopIntervalCheck(): void;
     private isPrimitive;
     private concatStores;
+    private setTtl;
 }
 
 declare class KeyvCacheableMemory implements KeyvStoreAdapter {
@@ -112,15 +125,23 @@ declare class KeyvCacheableMemory implements KeyvStoreAdapter {
     private readonly _cache;
     constructor(options?: CacheableMemoryOptions);
     get<Value>(key: string): Promise<StoredData<Value> | undefined>;
-    set(key: string, value: any, ttl?: number): void;
+    getMany<Value>(keys: string[]): Promise<Array<StoredData<Value | undefined>>>;
+    set(key: string, value: any, ttl?: number): Promise<void>;
+    setMany(values: Array<{
+        key: string;
+        value: any;
+        ttl?: number;
+    }>): Promise<void>;
     delete(key: string): Promise<boolean>;
+    deleteMany?(key: string[]): Promise<boolean>;
     clear(): Promise<void>;
     has?(key: string): Promise<boolean>;
-    getMany?<Value>(keys: string[]): Promise<Array<StoredData<Value | undefined>>>;
-    deleteMany?(key: string[]): Promise<boolean>;
     on(event: string, listener: (...arguments_: any[]) => void): this;
 }
 
+declare const shorthandToMilliseconds: (shorthand?: string | number) => number | undefined;
+declare const shorthandToTime: (shorthand?: string | number, fromDate?: Date) => number;
+
 declare enum CacheableHooks {
     BEFORE_SET = "BEFORE_SET",
     AFTER_SET = "AFTER_SET",
@@ -134,17 +155,12 @@ declare enum CacheableHooks {
 declare enum CacheableEvents {
     ERROR = "error"
 }
-type CacheableItem = {
-    key: string;
-    value: unknown;
-    ttl?: number;
-};
 type CacheableOptions = {
     primary?: Keyv | KeyvStoreAdapter;
     secondary?: Keyv | KeyvStoreAdapter;
     stats?: boolean;
     nonBlocking?: boolean;
-    ttl?: number;
+    ttl?: number | string;
 };
 declare class Cacheable extends Hookified {
     private _primary;
@@ -160,8 +176,8 @@ declare class Cacheable extends Hookified {
     set secondary(secondary: Keyv | undefined);
     get nonBlocking(): boolean;
     set nonBlocking(nonBlocking: boolean);
-    get ttl(): number | undefined;
-    set ttl(ttl: number | undefined);
+    get ttl(): number | string | undefined;
+    set ttl(ttl: number | string | undefined);
     setPrimary(primary: Keyv | KeyvStoreAdapter): void;
     setSecondary(secondary: Keyv | KeyvStoreAdapter): void;
     get<T>(key: string): Promise<T | undefined>;
@@ -179,6 +195,7 @@ declare class Cacheable extends Hookified {
     private deleteManyKeyv;
     private setManyKeyv;
     private hasManyKeyv;
+    private setTtl;
 }
 
-export { Cacheable, CacheableEvents, CacheableHooks, type CacheableItem, CacheableMemory, type CacheableOptions, CacheableStats, KeyvCacheableMemory };
+export { Cacheable, CacheableEvents, CacheableHooks, type CacheableItem, CacheableMemory, type CacheableOptions, CacheableStats, KeyvCacheableMemory, shorthandToMilliseconds, shorthandToTime };

package/dist/index.js

@@ -2,6 +2,73 @@
 import { Keyv } from "keyv";
 import { Hookified } from "hookified";
 
+// src/shorthand-time.ts
+var shorthandToMilliseconds = (shorthand) => {
+  let milliseconds;
+  if (shorthand === void 0) {
+    return void 0;
+  }
+  if (typeof shorthand === "number") {
+    milliseconds = shorthand;
+  } else if (typeof shorthand === "string") {
+    shorthand = shorthand.trim();
+    if (Number.isNaN(Number(shorthand))) {
+      const match = /^([\d.]+)\s*(ms|s|m|h|hr|d)$/i.exec(shorthand);
+      if (!match) {
+        throw new Error(
+          `Unsupported time format: "${shorthand}". Use 'ms', 's', 'm', 'h', 'hr', or 'd'.`
+        );
+      }
+      const [, value, unit] = match;
+      const numericValue = Number.parseFloat(value);
+      const unitLower = unit.toLowerCase();
+      switch (unitLower) {
+        case "ms": {
+          milliseconds = numericValue;
+          break;
+        }
+        case "s": {
+          milliseconds = numericValue * 1e3;
+          break;
+        }
+        case "m": {
+          milliseconds = numericValue * 1e3 * 60;
+          break;
+        }
+        case "h": {
+          milliseconds = numericValue * 1e3 * 60 * 60;
+          break;
+        }
+        case "hr": {
+          milliseconds = numericValue * 1e3 * 60 * 60;
+          break;
+        }
+        case "d": {
+          milliseconds = numericValue * 1e3 * 60 * 60 * 24;
+          break;
+        }
+        /* c8 ignore next 3 */
+        default: {
+          milliseconds = Number(shorthand);
+        }
+      }
+    } else {
+      milliseconds = Number(shorthand);
+    }
+  } else {
+    throw new TypeError("Time must be a string or a number.");
+  }
+  return milliseconds;
+};
+var shorthandToTime = (shorthand, fromDate) => {
+  fromDate ||= /* @__PURE__ */ new Date();
+  const milliseconds = shorthandToMilliseconds(shorthand);
+  if (milliseconds === void 0) {
+    return fromDate.getTime();
+  }
+  return fromDate.getTime() + milliseconds;
+};
+
 // src/memory-lru.ts
 var ListNode = class {
   // eslint-disable-next-line @typescript-eslint/parameter-properties
@@ -89,7 +156,7 @@ var CacheableMemory = class {
   _hash8 = /* @__PURE__ */ new Map();
   _hash9 = /* @__PURE__ */ new Map();
   _lru = new DoublyLinkedList();
-  _ttl = 0;
+  _ttl;
   // Turned off by default
   _useClone = true;
   // Turned on by default
@@ -101,7 +168,7 @@ var CacheableMemory = class {
   // Turned off by default
   constructor(options) {
     if (options?.ttl) {
-      this._ttl = options.ttl;
+      this.setTtl(options.ttl);
     }
     if (options?.useClone !== void 0) {
       this._useClone = options.useClone;
@@ -118,7 +185,7 @@ var CacheableMemory = class {
     return this._ttl;
   }
   set ttl(value) {
-    this._ttl = value;
+    this.setTtl(value);
   }
   get useClone() {
     return this._useClone;
@@ -164,11 +231,41 @@ var CacheableMemory = class {
     }
     return this.clone(item.value);
   }
+  getMany(keys) {
+    const result = new Array();
+    for (const key of keys) {
+      result.push(this.get(key));
+    }
+    return result;
+  }
+  getRaw(key) {
+    const store = this.getStore(key);
+    const item = store.get(key);
+    if (!item) {
+      return void 0;
+    }
+    if (item.expires && item.expires && Date.now() > item.expires) {
+      store.delete(key);
+      return void 0;
+    }
+    this.lruMoveToFront(key);
+    return item;
+  }
+  getManyRaw(keys) {
+    const result = new Array();
+    for (const key of keys) {
+      result.push(this.getRaw(key));
+    }
+    return result;
+  }
   set(key, value, ttl) {
     const store = this.getStore(key);
     let expires;
-    if (ttl !== void 0 || this._ttl !== 0) {
-      expires = Date.now() + (ttl ?? this._ttl);
+    if (ttl !== void 0 || this._ttl !== void 0) {
+      const finalTtl = shorthandToTime(ttl ?? this._ttl);
+      if (finalTtl !== void 0) {
+        expires = finalTtl;
+      }
     }
     if (this._lruSize > 0) {
       if (store.has(key)) {
@@ -191,6 +288,11 @@ var CacheableMemory = class {
       expires
     });
   }
+  setMany(items) {
+    for (const item of items) {
+      this.set(item.key, item.value, item.ttl);
+    }
+  }
   has(key) {
     const item = this.get(key);
     return Boolean(item);
@@ -203,10 +305,22 @@ var CacheableMemory = class {
     this.delete(key);
     return item;
   }
+  takeMany(keys) {
+    const result = new Array();
+    for (const key of keys) {
+      result.push(this.take(key));
+    }
+    return result;
+  }
   delete(key) {
     const store = this.getStore(key);
     store.delete(key);
   }
+  deleteMany(keys) {
+    for (const key of keys) {
+      this.delete(key);
+    }
+  }
   clear() {
     this._hash0.clear();
     this._hash1.clear();
@@ -335,6 +449,15 @@ var CacheableMemory = class {
     const result = new Map([...this._hash0, ...this._hash1, ...this._hash2, ...this._hash3, ...this._hash4, ...this._hash5, ...this._hash6, ...this._hash7, ...this._hash8, ...this._hash9]);
     return result;
   }
+  setTtl(ttl) {
+    if (typeof ttl === "string" || ttl === void 0) {
+      this._ttl = ttl;
+    } else if (ttl > 0) {
+      this._ttl = ttl;
+    } else {
+      this._ttl = void 0;
+    }
+  }
 };
 
 // src/keyv-memory.ts
@@ -355,38 +478,35 @@ var KeyvCacheableMemory = class {
   }
   async get(key) {
     const result = this._cache.get(key);
-    console.log("result", result);
     if (result) {
       return result;
     }
     return void 0;
   }
-  set(key, value, ttl) {
+  async getMany(keys) {
+    const result = this._cache.getMany(keys);
+    return result;
+  }
+  async set(key, value, ttl) {
     this._cache.set(key, value, ttl);
   }
+  async setMany(values) {
+    this._cache.setMany(values);
+  }
   async delete(key) {
     this._cache.delete(key);
     return true;
   }
+  async deleteMany(key) {
+    this._cache.deleteMany(key);
+    return true;
+  }
   async clear() {
     this._cache.clear();
   }
   async has(key) {
     return this._cache.has(key);
   }
-  async getMany(keys) {
-    const result = [];
-    for (const key of keys) {
-      result.push(this._cache.get(key));
-    }
-    return result;
-  }
-  async deleteMany(key) {
-    for (const k of key) {
-      this._cache.delete(k);
-    }
-    return true;
-  }
   on(event, listener) {
     return this;
   }
@@ -604,7 +724,7 @@ var Cacheable = class extends Hookified {
       this._stats.enabled = options.stats;
     }
     if (options?.ttl) {
-      this._ttl = options.ttl;
+      this.setTtl(options.ttl);
     }
   }
   get stats() {
@@ -632,7 +752,7 @@ var Cacheable = class extends Hookified {
     return this._ttl;
   }
   set ttl(ttl) {
-    this._ttl = ttl;
+    this.setTtl(ttl);
   }
   setPrimary(primary) {
     this._primary = primary instanceof Keyv ? primary : new Keyv(primary);
@@ -648,7 +768,8 @@ var Cacheable = class extends Hookified {
       if (!result && this._secondary) {
         result = await this._secondary.get(key);
         if (result) {
-          await this._primary.set(key, result, this._ttl);
+          const finalTtl = shorthandToMilliseconds(this._ttl);
+          await this._primary.set(key, result, finalTtl);
         }
       }
       await this.hook("AFTER_GET" /* AFTER_GET */, { key, result });
@@ -681,7 +802,8 @@ var Cacheable = class extends Hookified {
         for (const [i, key] of keys.entries()) {
           if (!result[i] && secondaryResult[i]) {
             result[i] = secondaryResult[i];
-            await this._primary.set(key, secondaryResult[i], this._ttl);
+            const finalTtl = shorthandToMilliseconds(this._ttl);
+            await this._primary.set(key, secondaryResult[i], finalTtl);
           }
         }
       }
@@ -703,7 +825,7 @@ var Cacheable = class extends Hookified {
   }
   async set(key, value, ttl) {
     let result = false;
-    const finalTtl = ttl ?? this._ttl;
+    const finalTtl = shorthandToMilliseconds(ttl ?? this._ttl);
     try {
       const item = { key, value, ttl: finalTtl };
       await this.hook("BEFORE_SET" /* BEFORE_SET */, item);
@@ -872,7 +994,7 @@ var Cacheable = class extends Hookified {
   async setManyKeyv(keyv, items) {
     const promises = [];
     for (const item of items) {
-      const finalTtl = item.ttl ?? this._ttl;
+      const finalTtl = shorthandToMilliseconds(item.ttl ?? this._ttl);
       promises.push(keyv.set(item.key, item.value, finalTtl));
     }
     await Promise.all(promises);
@@ -885,6 +1007,15 @@ var Cacheable = class extends Hookified {
     }
     return Promise.all(promises);
   }
+  setTtl(ttl) {
+    if (typeof ttl === "string" || ttl === void 0) {
+      this._ttl = ttl;
+    } else if (ttl > 0) {
+      this._ttl = ttl;
+    } else {
+      this._ttl = void 0;
+    }
+  }
 };
 export {
   Cacheable,
@@ -892,5 +1023,7 @@ export {
   CacheableHooks,
   CacheableMemory,
   CacheableStats,
-  KeyvCacheableMemory
+  KeyvCacheableMemory,
+  shorthandToMilliseconds,
+  shorthandToTime
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cacheable",
-  "version": "1.6.1",
+  "version": "1.7.1",
   "description": "Simple Caching Engine using Keyv",
   "type": "module",
   "main": "./dist/index.cjs",