quick-lru-ts

library1.0.0jsnpmunverified

A simple Least Recently Used (LRU) cache implementation in TypeScript. Version 1.0.0 wraps sindresorhus/quick-lru with TypeScript declarations. It uses a Map internally for O(1) operations and supports keys of any type, including objects and symbols. Key features include configurable maxSize and maxAge (with per-item TTL), an onEviction callback for cleanup, and multiple iteration methods (keys, values, entriesAscending, entriesDescending). Compared to lru-cache or tiny-lru, quick-lru-ts focuses on simplicity and minimal API surface. The package is ESM-only, requires Node.js >=12, and is stable with no breaking changes expected. It is actively maintained as a TypeScript conversion of the original quick-lru.

storage

npm install quick-lru-ts

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · QUICK-LRU-TS

quick-lru-ts

storagejavascriptv1.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

QuickLRU

✓ import { QuickLRU } from 'quick-lru-ts'

✗ const QuickLRU = require('quick-lru-ts')

Package is ESM-only; require() will not work. The default export was available in v0.x but removed in v1.0.0.

QuickLRU (default import)

✓ import QuickLRU from 'quick-lru-ts'

✗ const { QuickLRU } = require('quick-lru-ts')

From v1.0.0, named export is preferred; default import also works. Use named import for clarity.

QuickLRUOptions

✓ import type { QuickLRUOptions } from 'quick-lru-ts'

✗ import { QuickLRUOptions } from 'quick-lru-ts'

Options is a type only, not a runtime value. Use type import to avoid emitting unused code.

Creates an LRU cache with max size 100 and default TTL 60 seconds. Sets two items, the second with a custom 30-second TTL. Demonstrates has, get, delete, and size.

import { QuickLRU } from 'quick-lru-ts'; const lru = new QuickLRU({ maxSize: 100, maxAge: 60_000 }); lru.set('key1', 'value1'); lru.set('key2', 'value2', { maxAge: 30_000 }); console.log(lru.has('key1')); // true console.log(lru.get('key1')); // 'value1' lru.delete('key2'); console.log(lru.size); // 1

Debug

Known issues

breakingPackage is ESM-only since v1.0.0. CommonJS require() throws an error.

fix

Switch to import { QuickLRU } from 'quick-lru-ts' or use dynamic import().

affects: >=1.0.0

deprecatedDefault export (QuickLRU named as default) was available in v0.x but is deprecated in v1.0.0; use named export instead.

fix

Use import { QuickLRU } from 'quick-lru-ts' instead of import QuickLRU from 'quick-lru-ts'.

affects: >=1.0.0

gotchamaxAge expiration is lazy: expired items are only removed upon the next read or write. The cache may hold expired items longer, counting toward maxSize.

fix

Either rely on onEviction callback or call get()/has() periodically to purge expired entries. No automatic eviction.

affects: >=0.1.0

gotchaonEviction callback is called synchronously during set/delete/resize/clear, not asynchronously. Do not schedule microtasks or I/O inside it.

fix

If you need async cleanup, queue the work (e.g., queueMicrotask) inside onEviction.

affects: >=0.1.0

gotchaSetting maxSize to 0 or negative will cause runtime errors (e.g., infinite loop or unexpected evictions).

fix

Always provide a positive integer for maxSize. Validation is not performed internally.

affects: >=0.1.0

deprecatedThe original npm package quick-lru (non-TS) is available. quick-lru-ts is a community fork; check for future divergence.

fix

If you need TypeScript declarations, you can also use @types/quick-lru with the original package. Compare features before choosing.

affects: >=1.0.0

Errors

Common errors & fixes

SyntaxError: Named export 'QuickLRU' not found. The requested module 'quick-lru-ts' is a CommonJS module, which may not support all module.exports as named exports.

Using a dynamic import or bundler that expects CommonJS; package is ESM-only.

fix

Use import { QuickLRU } from 'quick-lru-ts' and ensure your project is configured for ESM (type: module in package.json or .mjs extension).

TypeError: QuickLRU is not a constructor

Trying to call new QuickLRU() after a default import that actually resolves to a different export (or using require).

fix

If using import QuickLRU from 'quick-lru-ts', ensure the package version supports default export (v0.x). For v1.0.0, use named import: import { QuickLRU } from 'quick-lru-ts'.

RangeError: Invalid maxSize: must be a positive integer

Passing undefined or a non-number to maxSize option. The library does not validate; Map size throwing if set to non-integer.

fix

Ensure maxSize is a positive integer: new QuickLRU({ maxSize: Number(someValue) || 100 }).

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

Resources

githubhttps://github.com/greguintow/quick-lru-ts ↗

packagequick-lru-ts ↗

homepagehttps://github.com/greguintow/quick-lru-ts#readme ↗