@stryke/helpers 0.8.0 → 0.9.0

package/dist/index.cjs

@@ -135,6 +135,17 @@ Object.keys(_isEqual).forEach(function (key) {
     }
   });
 });
+var _lruCache = require("./lru-cache.cjs");
+Object.keys(_lruCache).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _lruCache[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _lruCache[key];
+    }
+  });
+});
 var _matchSorter = require("./match-sorter.cjs");
 Object.keys(_matchSorter).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export * from "./get-ordered-by";
 export * from "./get-unique";
 export * from "./identity";
 export * from "./is-equal";
+export * from "./lru-cache";
 export * from "./match-sorter";
 export * from "./memoize";
 export * from "./mutex";

package/dist/index.mjs

@@ -1 +1 @@
-export*from"./arg-identity";export*from"./debounce";export*from"./deep-clone";export*from"./deep-merge";export*from"./delay";export*from"./filter-empty";export*from"./flatten-object";export*from"./get-field";export*from"./get-ordered-by";export*from"./get-unique";export*from"./identity";export*from"./is-equal";export*from"./match-sorter";export*from"./memoize";export*from"./mutex";export*from"./noop";export*from"./omit";export*from"./once";export*from"./pick";export*from"./remove-accents";export*from"./remove-empty-items";export*from"./semaphore";export*from"./set-field";export*from"./throttle";export*from"./timeout";export*from"./to-deep-key";export*from"./to-path";export*from"./unflatten-object";export*from"./union";export*from"./with-timeout";
+export*from"./arg-identity";export*from"./debounce";export*from"./deep-clone";export*from"./deep-merge";export*from"./delay";export*from"./filter-empty";export*from"./flatten-object";export*from"./get-field";export*from"./get-ordered-by";export*from"./get-unique";export*from"./identity";export*from"./is-equal";export*from"./lru-cache";export*from"./match-sorter";export*from"./memoize";export*from"./mutex";export*from"./noop";export*from"./omit";export*from"./once";export*from"./pick";export*from"./remove-accents";export*from"./remove-empty-items";export*from"./semaphore";export*from"./set-field";export*from"./throttle";export*from"./timeout";export*from"./to-deep-key";export*from"./to-path";export*from"./unflatten-object";export*from"./union";export*from"./with-timeout";

package/dist/lru-cache.cjs

@@ -0,0 +1,82 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.LRUCache = void 0;
+class r {
+  key;
+  data;
+  size;
+  prev = null;
+  next = null;
+  constructor(e, t, i) {
+    this.key = e, this.data = t, this.size = i;
+  }
+}
+class l {
+  prev = null;
+  next = null;
+}
+class LRUCache {
+  cache = new Map();
+  head;
+  tail;
+  totalSize = 0;
+  maxSize;
+  calculateSize;
+  constructor(e, t) {
+    this.maxSize = e, this.calculateSize = t, this.head = new l(), this.tail = new l(), this.head.next = this.tail, this.tail.prev = this.head;
+  }
+  addToHead(e) {
+    e.prev = this.head, e.next = this.head.next, this.head.next.prev = e, this.head.next = e;
+  }
+  removeNode(e) {
+    e.prev.next = e.next, e.next.prev = e.prev;
+  }
+  moveToHead(e) {
+    this.removeNode(e), this.addToHead(e);
+  }
+  removeTail() {
+    const e = this.tail.prev;
+    return this.removeNode(e), e;
+  }
+  set(e, t) {
+    const i = this.calculateSize?.(t) ?? 1;
+    if (i > this.maxSize) return;
+    const a = this.cache.get(e);
+    if (a) a.data = t, this.totalSize = this.totalSize - a.size + i, a.size = i, this.moveToHead(a);else {
+      const s = new r(e, t, i);
+      this.cache.set(e, s), this.addToHead(s), this.totalSize += i;
+    }
+    for (; this.totalSize > this.maxSize && this.cache.size > 0;) {
+      const s = this.removeTail();
+      this.cache.delete(s.key), this.totalSize -= s.size;
+    }
+  }
+  has(e) {
+    return this.cache.has(e);
+  }
+  get(e) {
+    const t = this.cache.get(e);
+    if (t) return this.moveToHead(t), t.data;
+  }
+  *[Symbol.iterator]() {
+    let e = this.head.next;
+    for (; e && e !== this.tail;) {
+      const t = e;
+      yield [t.key, t.data], e = e.next;
+    }
+  }
+  remove(e) {
+    const t = this.cache.get(e);
+    t && (this.removeNode(t), this.cache.delete(e), this.totalSize -= t.size);
+  }
+  get size() {
+    return this.cache.size;
+  }
+  get currentSize() {
+    return this.totalSize;
+  }
+}
+exports.LRUCache = LRUCache;

package/dist/lru-cache.d.ts

@@ -0,0 +1,99 @@
+/**
+ * LRU (Least Recently Used) Cache implementation using a doubly-linked list
+ * and hash map for O(1) operations.
+ *
+ * Algorithm:
+ * - Uses a doubly-linked list to maintain access order (most recent at head)
+ * - Hash map provides O(1) key-to-node lookup
+ * - Sentinel head/tail nodes simplify edge case handling
+ * - Size-based eviction supports custom size calculation functions
+ *
+ * Data Structure Layout:
+ * HEAD \<-\> [most recent] \<-\> ... \<-\> [least recent] \<-\> TAIL
+ *
+ * Operations:
+ * - get(): Move accessed node to head (mark as most recent)
+ * - set(): Add new node at head, evict from tail if over capacity
+ * - Eviction: Remove least recent node (tail.prev) when size exceeds limit
+ */
+export declare class LRUCache<T> {
+    private readonly cache;
+    private readonly head;
+    private readonly tail;
+    private totalSize;
+    private readonly maxSize;
+    private readonly calculateSize;
+    constructor(maxSize: number, calculateSize?: (value: T) => number);
+    /**
+     * Adds a node immediately after the head (marks as most recently used). Used when inserting new items or when an item is accessed. **PRECONDITION:** node must be disconnected (prev/next should be null)
+     *
+     * @param node - The node to add after the head.
+     */
+    private addToHead;
+    /**
+     * Removes a node from its current position in the doubly-linked list. Updates the prev/next pointers of adjacent nodes to maintain list integrity. **PRECONDITION:** node must be connected (prev/next are non-null)
+     *
+     * @param node - The node to remove from the list.
+     */
+    private removeNode;
+    /**
+     * Moves an existing node to the head position (marks as most recently used). This is the core LRU operation - accessed items become most recent.
+     *
+     * @param node - The node to move to the head.
+     */
+    private moveToHead;
+    /**
+     * Removes and returns the least recently used node (the one before tail). This is called during eviction when the cache exceeds capacity. **PRECONDITION:** cache is not empty (ensured by caller)
+     *
+     * @returns The removed least recently used node.
+     */
+    private removeTail;
+    /**
+     * Sets a key-value pair in the cache.
+     * If the key exists, updates the value and moves to head.
+     * If new, adds at head and evicts from tail if necessary.
+     *
+     * Time Complexity:
+     * - O(1) for uniform item sizes
+     * - O(k) where k is the number of items evicted (can be O(N) for variable sizes)
+     *
+     * @param key - The key to set.
+     * @param value - The value to set.
+     */
+    set(key: string, value: T): void;
+    /**
+     * Checks if a key exists in the cache.
+     * This is a pure query operation - does NOT update LRU order.
+     *
+     * Time Complexity: O(1)
+     */
+    has(key: string): boolean;
+    /**
+     * Retrieves a value by key and marks it as most recently used.
+     * Moving to head maintains the LRU property for future evictions.
+     *
+     * Time Complexity: O(1)
+     */
+    get(key: string): T | undefined;
+    /**
+     * Returns an iterator over the cache entries. The order is outputted in the
+     * order of most recently used to least recently used.
+     */
+    [Symbol.iterator](): IterableIterator<[string, T]>;
+    /**
+     * Removes a specific key from the cache.
+     * Updates both the hash map and doubly-linked list.
+     *
+     * Time Complexity: O(1)
+     */
+    remove(key: string): void;
+    /**
+     * Returns the number of items in the cache.
+     */
+    get size(): number;
+    /**
+     * Returns the current total size of all cached items.
+     * This uses the custom size calculation if provided.
+     */
+    get currentSize(): number;
+}

package/dist/lru-cache.mjs

@@ -0,0 +1 @@
+class r{key;data;size;prev=null;next=null;constructor(e,t,i){this.key=e,this.data=t,this.size=i}}class l{prev=null;next=null}export class LRUCache{cache=new Map;head;tail;totalSize=0;maxSize;calculateSize;constructor(e,t){this.maxSize=e,this.calculateSize=t,this.head=new l,this.tail=new l,this.head.next=this.tail,this.tail.prev=this.head}addToHead(e){e.prev=this.head,e.next=this.head.next,this.head.next.prev=e,this.head.next=e}removeNode(e){e.prev.next=e.next,e.next.prev=e.prev}moveToHead(e){this.removeNode(e),this.addToHead(e)}removeTail(){const e=this.tail.prev;return this.removeNode(e),e}set(e,t){const i=this.calculateSize?.(t)??1;if(i>this.maxSize)return;const a=this.cache.get(e);if(a)a.data=t,this.totalSize=this.totalSize-a.size+i,a.size=i,this.moveToHead(a);else{const s=new r(e,t,i);this.cache.set(e,s),this.addToHead(s),this.totalSize+=i}for(;this.totalSize>this.maxSize&&this.cache.size>0;){const s=this.removeTail();this.cache.delete(s.key),this.totalSize-=s.size}}has(e){return this.cache.has(e)}get(e){const t=this.cache.get(e);if(t)return this.moveToHead(t),t.data}*[Symbol.iterator](){let e=this.head.next;for(;e&&e!==this.tail;){const t=e;yield[t.key,t.data],e=e.next}}remove(e){const t=this.cache.get(e);t&&(this.removeNode(t),this.cache.delete(e),this.totalSize-=t.size)}get size(){return this.cache.size}get currentSize(){return this.totalSize}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stryke/helpers",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "A package containing miscellaneous helper functions that are used across many different Storm Software projects.",
   "repository": {
@@ -11,9 +11,9 @@
   "private": false,
   "publishConfig": { "access": "public" },
   "dependencies": {
-    "@stryke/convert": "^0.3.1",
-    "@stryke/type-checks": "^0.3.9",
-    "@stryke/types": "^0.8.9"
+    "@stryke/convert": "^0.6.0",
+    "@stryke/type-checks": "^0.3.10",
+    "@stryke/types": "^0.9.0"
   },
   "devDependencies": {},
   "sideEffects": false,
@@ -263,6 +263,20 @@
         "default": "./dist/match-sorter.mjs"
       }
     },
+    "./lru-cache": {
+      "import": {
+        "types": "./dist/lru-cache.d.ts",
+        "default": "./dist/lru-cache.mjs"
+      },
+      "require": {
+        "types": "./dist/lru-cache.d.ts",
+        "default": "./dist/lru-cache.cjs"
+      },
+      "default": {
+        "types": "./dist/lru-cache.d.ts",
+        "default": "./dist/lru-cache.mjs"
+      }
+    },
     "./is-equal": {
       "import": {
         "types": "./dist/is-equal.d.ts",
@@ -460,5 +474,5 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
-  "gitHead": "a27f10e735a05cca18b29026136249ed3bb76c1c"
+  "gitHead": "4074c4a56f6e2c42ca4c39c30df5309c19024c7b"
 }