@common.js/quick-lru 7.0.0 → 7.3.0

package/README.md

@@ -2,4 +2,4 @@
 
 The [quick-lru](https://www.npmjs.com/package/quick-lru) package exported as CommonJS modules.
 
-Exported from [quick-lru@7.0.0](https://www.npmjs.com/package/quick-lru/v/7.0.0) using https://github.com/etienne-martin/common.js.
+Exported from [quick-lru@7.3.0](https://www.npmjs.com/package/quick-lru/v/7.3.0) using https://github.com/etienne-martin/common.js.

package/index.d.ts

@@ -5,21 +5,25 @@ export type Options<KeyType, ValueType> = {
 	@default Infinity
 
 	By default, `maxAge` will be `Infinity`, which means that items will never expire.
-	Lazy expiration upon the next write or read call.
+	Lazy expiration occurs upon the next write or read call.
 
-	Individual expiration of an item can be specified by the `set(key, value, maxAge)` method.
+	Individual expiration of an item can be specified with the `set(key, value, {maxAge})` method.
 	*/
 	readonly maxAge?: number;
 
 	/**
-	The maximum number of items before evicting the least recently used items.
+	The target maximum number of items before evicting the least recently used items.
+
+	__Note:__ This package uses an [algorithm](https://github.com/sindresorhus/quick-lru#algorithm) which maintains between `maxSize` and `2 × maxSize` items for performance reasons. The cache may temporarily contain up to twice the specified size due to the dual-cache design that avoids expensive delete operations.
 	*/
 	readonly maxSize: number;
 
 	/**
-	Called right before an item is evicted from the cache.
+	Called right before an item is evicted from the cache due to LRU pressure, TTL expiration, or manual eviction via `evict()`.
 
 	Useful for side effects or for items like object URLs that need explicit cleanup (`revokeObjectURL`).
+
+	__Note:__ This callback is not called for manual removals via `delete()` or `clear()`. It fires for automatic evictions and manual evictions via `evict()`.
 	*/
 	onEviction?: (key: KeyType, value: ValueType) => void;
 };
@@ -53,9 +57,9 @@ export default class QuickLRU<KeyType, ValueType> extends Map<KeyType, ValueType
 	/**
 	Set an item. Returns the instance.
 
-	Individual expiration of an item can be specified with the `maxAge` option. If not specified, the global `maxAge` value will be used in case it is specified in the constructor, otherwise the item will never expire.
+	Individual expiration of an item can be specified with the `maxAge` option. If not specified, the global `maxAge` value will be used in case it is specified in the constructor; otherwise the item will never expire.
 
-	@returns The list instance.
+	@returns The cache instance.
 	*/
 	set(key: KeyType, value: ValueType, options?: {maxAge?: number}): this;
 
@@ -90,6 +94,18 @@ export default class QuickLRU<KeyType, ValueType> extends Map<KeyType, ValueType
 	*/
 	clear(): void;
 
+	/**
+	Get the remaining time to live (in milliseconds) for the given item, or `undefined` when the item is not in the cache.
+
+	- Does not mark the item as recently used.
+	- Does not trigger lazy expiration or remove the entry when it is expired.
+	- Returns `Infinity` if the item has no expiration.
+	- May return a negative number if the item is already expired but not yet lazily removed.
+
+	@returns Remaining time to live in milliseconds when set, `Infinity` when there is no expiration, or `undefined` when the item does not exist.
+	*/
+	expiresIn(key: KeyType): number | undefined;
+
 	/**
 	Update the `maxSize` in-place, discarding items as necessary. Insertion order is mostly preserved, though this is not a strong guarantee.
 
@@ -107,6 +123,11 @@ export default class QuickLRU<KeyType, ValueType> extends Map<KeyType, ValueType
 	*/
 	get maxSize(): number;
 
+	/**
+	The set max age.
+	*/
+	get maxAge(): number;
+
 	/**
 	Iterable for all the keys.
 	*/
@@ -126,4 +147,32 @@ export default class QuickLRU<KeyType, ValueType> extends Map<KeyType, ValueType
 	Iterable for all entries, starting with the newest (descending in recency).
 	*/
 	entriesDescending(): IterableIterator<[KeyType, ValueType]>;
+
+	/**
+	Evict the least recently used items from the cache.
+
+	@param count - The number of items to evict. Defaults to 1.
+
+	It will always keep at least one item in the cache.
+
+	@example
+	```
+	import QuickLRU from 'quick-lru';
+
+	const lru = new QuickLRU({maxSize: 10});
+
+	lru.set('a', 1);
+	lru.set('b', 2);
+	lru.set('c', 3);
+
+	lru.evict(2); // Evicts 'a' and 'b'
+
+	console.log(lru.has('a'));
+	//=> false
+
+	console.log(lru.has('c'));
+	//=> true
+	```
+	*/
+	evict(count?: number): void;
 }

package/index.js

@@ -378,7 +378,7 @@ var __generator = (void 0) && (void 0).__generator || function(thisArg, body) {
     }
 };
 var _size = /*#__PURE__*/ new WeakMap(), _cache = /*#__PURE__*/ new WeakMap(), _oldCache = /*#__PURE__*/ new WeakMap(), _maxSize = /*#__PURE__*/ new WeakMap(), _maxAge = /*#__PURE__*/ new WeakMap(), _onEviction = /*#__PURE__*/ new WeakMap(), _emitEvictions = /*#__PURE__*/ new WeakSet(), _deleteIfExpired = /*#__PURE__*/ new WeakSet(), _getOrDeleteIfExpired = /*#__PURE__*/ new WeakSet(), _getItemValue = /*#__PURE__*/ new WeakSet(), _peek = /*#__PURE__*/ new WeakSet(), _set = /*#__PURE__*/ new WeakSet(), _moveToRecent = /*#__PURE__*/ new WeakSet(), _entriesAscending = /*#__PURE__*/ new WeakSet();
-var _iterator = Symbol.iterator, _toStringTag = Symbol.toStringTag;
+var _iterator = Symbol.iterator, _toStringTag = Symbol.toStringTag, tmp = Symbol.for("nodejs.util.inspect.custom");
 var QuickLRU = /*#__PURE__*/ function(Map1) {
     "use strict";
     _inherits(QuickLRU, Map1);
@@ -497,6 +497,16 @@ var QuickLRU = /*#__PURE__*/ function(Map1) {
                 }
             }
         },
+        {
+            key: "expiresIn",
+            value: function expiresIn(key) {
+                var ref;
+                var item = (ref = _classPrivateFieldGet(this, _cache).get(key)) !== null && ref !== void 0 ? ref : _classPrivateFieldGet(this, _oldCache).get(key);
+                if (item) {
+                    return item.expiry ? item.expiry - Date.now() : Number.POSITIVE_INFINITY;
+                }
+            }
+        },
         {
             key: "delete",
             value: function _delete(key) {
@@ -538,6 +548,25 @@ var QuickLRU = /*#__PURE__*/ function(Map1) {
                 _classPrivateFieldSet(this, _maxSize, newSize);
             }
         },
+        {
+            key: "evict",
+            value: function evict() {
+                var count = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : 1;
+                var requested = Number(count);
+                if (!requested || requested <= 0) {
+                    return;
+                }
+                var items = _toConsumableArray(_classPrivateMethodGet(this, _entriesAscending, entriesAscending).call(this));
+                var evictCount = Math.trunc(Math.min(requested, Math.max(items.length - 1, 0)));
+                if (evictCount <= 0) {
+                    return;
+                }
+                _classPrivateMethodGet(this, _emitEvictions, emitEvictions).call(this, items.slice(0, evictCount));
+                _classPrivateFieldSet(this, _oldCache, new Map(items.slice(evictCount)));
+                _classPrivateFieldSet(this, _cache, new Map());
+                _classPrivateFieldSet(this, _size, 0);
+            }
+        },
         {
             key: "keys",
             value: function keys() {
@@ -1024,6 +1053,12 @@ var QuickLRU = /*#__PURE__*/ function(Map1) {
                 return _classPrivateFieldGet(this, _maxSize);
             }
         },
+        {
+            key: "maxAge",
+            get: function get() {
+                return _classPrivateFieldGet(this, _maxAge);
+            }
+        },
         {
             key: "entries",
             value: function entries() {
@@ -1059,7 +1094,19 @@ var QuickLRU = /*#__PURE__*/ function(Map1) {
         {
             key: _toStringTag,
             get: function get() {
-                return JSON.stringify(_toConsumableArray(this.entriesAscending()));
+                return "QuickLRU";
+            }
+        },
+        {
+            key: "toString",
+            value: function toString() {
+                return "QuickLRU(".concat(this.size, "/").concat(this.maxSize, ")");
+            }
+        },
+        {
+            key: tmp,
+            value: function value() {
+                return this.toString();
             }
         }
     ]);

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@common.js/quick-lru",
-  "version": "7.0.0",
+  "version": "7.3.0",
   "description": "quick-lru package exported as CommonJS modules",
   "license": "MIT",
   "repository": "etienne-martin/common.js",
   "funding": "https://github.com/sponsors/sindresorhus",
   "type": "commonjs",
+  "sideEffects": false,
   "engines": {
     "node": ">=18"
   },
@@ -30,6 +31,6 @@
   },
   "homepage": "https://github.com/etienne-martin/common.js#readme",
   "dependencies": {},
-  "types": "./index.d.ts",
-  "main": "./index.js"
+  "main": "./index.js",
+  "types": "./index.d.ts"
 }