docs: complete documentation overhaul, UMD removal, and 10 new utility methods (#405)

* Add peek() method to retrieve value without LRU update

- peek() retrieves value without moving item in LRU order
- peek() does not perform TTL checks or delete expired items
- All core operations remain O(1)
- Updated tests, documentation, and AGENTS.md

* Add comprehensive tests for 9 LRU utility methods

- Added 68 new tests covering forEach, getMany, hasAll, hasAny, cleanup, toJSON, stats, onEvict, sizeByTTL, keysByTTL, and valuesByTTL methods
- Refactored values() to directly iterate linked list instead of using keys()
- Refactored forEach() for direct linked list traversal
- Updated API documentation in docs/API.md
- Updated README.md method table
- Updated AGENTS.md API reference
- All tests passing (145/145)

* Add tests for noTTL items in sizeByTTL/keysByTTL

- Added test for items with expiry=0 when ttl>0 (manual expiry set)
- Covers uncovered lines 534-535 and 563-564 in sizeByTTL and keysByTTL
- 100% line coverage achieved

* Docs: sort Methods table alphabetically

* README: fix badge order and remove duplicate tag line

* README: complete rewrite based on source documentation

- Compress badges to first 8 lines after title
- Add new badges: GitHub stars, Codecov
- Organize content with clear sections
- Add modern usage patterns (LLM caching, session auth)
- Improve 'Why Tiny LRU?' comparison table
- Add detailed API reference with all methods
- Include TypeScript examples
- Add security best practices
- Remove duplicate TypeScript section
- Standardize method descriptions
- Add comprehensive code examples

Fixes: branch name references (master vs main)

* README: fix build status badge URL

* ci.yml: add push event for master branch

* README: use full GitHub paths for markdown doc links

* README: correct comparison table values

- Update bundle sizes to actual measured values (gzipped)
- Fix quick-lru TTL support (it does support maxAge)
- Replace inaccurate 'Comprehensive API' column with 'Pure LRU'

* build: remove UMD output format

* docs: remove UMD mentions from README.md, AGENTS.md and TECHNICAL_DOCUMENTATION.md

* docs: update test coverage metrics

* docs: order methods alphabetically, expand ToC

- Methods now sorted A-Z: cleanup() to valuesByTTL()
- Expanded table of contents with 1-3 level headers
- All method anchors now directly link to section headers

* Add documentation links to README.md

- Removed redundant TECHNICAL_DOCUMENTATION link in Security section
- Added Documentation section with links to all three docs files

* Fix incorrect resetTtl documentation and readonly properties

- Corrected resetTtl doc to say 'via set()' instead of 'via get()'
- Removed 'readonly' from class properties (implementation doesn't use readonly)

* evict(): clear item.prev to allow garbage collection

- When evicting items, ensure both prev and next pointers are cleared
- This prevents keeping the rest of the list reachable when consumers
  hold references to evicted nodes

* cleanup(): fix inconsistency with expiry === 0 handling

- Items with expiry === 0 represent noTTL items, not expired items
- Changed cleanup() to only remove items where expiry !== 0 && expiry <= now
- This matches the semantics in sizeByTTL()/keysByTTL()

* docs: correct forEach() documentation to match actual implementation

* docs: fix cache-aside example to show shared cache instance

* docs: correct comment to say 'TTL reset on update' instead of 'on access'

* Fix cleanup() memory leak - clear prev/next pointers on expired nodes

- Properly unlink expired nodes during cleanup() deletion
- Clear prev/next pointers to allow garbage collection
- Fix iteration to save next pointer before unlinking

* Fix onEvict() documentation - callback also triggers on direct evict() calls

* Fix test name - should test peek() during forEach, not get()

* Fix documentation inaccuracies

- README.md: Add missing methods (expiresAt, sizeByTTL, keysByTTL, valuesByTTL)
- README.md: Fix entries() description - with keys parameter, order matches input
- README.md: Clarify onEvict() triggers on evict() and set()/setWithEvicted() eviction
- API.md: Fix entries() - input array order, not LRU order, when keys provided
- API.md: Clarify onEvict() triggering conditions explicitly
- API.md: Add note about cleanup() silently removing items
- API.md: Clarify setWithEvicted() can return null when no eviction needed

* Fix clear() memory leak - clear prev/next pointers on all nodes

When clear() was called, linked list nodes retained their prev/next
pointers. If external references to nodes existed, the entire list
remained reachable and couldn't be garbage collected.

This fix iterates through all nodes before clearing references,
ensuring proper cleanup and allowing GC even with external node refs.

* Fix TTL semantics inconsistency - expiry === 0 should be noTTL, not expired

get() was treating expiry === 0 as expired when ttl > 0, but cleanup(),
sizeByTTL(), keysByTTL(), and valuesByTTL() all treat expiry === 0 as
noTTL/valid items.

The fix adds 'item.expiry !== 0' check to get() so noTTL items are never
incorrectly treated as expired.

* Add #isExpired() private function for DRY TTL expiration check

Extracts TTL expiration logic into a single private function that:
- Returns false if ttl === 0 or item.expiry === 0 (noTTL items)
- Returns true if item.expiry <= Date.now() for items with TTL set

Updates get() and cleanup() to use #isExpired() instead of duplicating logic.
Size reductions from DRY: get() reduced by 4 lines, cleanup() by 5 lines.

* Fix has() TTL semantics - use #isExpired() consistently

has() was incorrectly treating expiry === 0 as expired when ttl > 0,
while #isExpired() and cleanup() correctly treat expiry === 0 as noTTL.

Aligns has() with the rest of the TTL semantics by using #isExpired().

* docs: consolidate duplicate entries() method descriptions

Removed duplicate entries() method entries (rows 172-173 and 183)
and combined into single clear description: 'Get [key, value] pairs.
Without keys: LRU order. With keys: input array order.'

* docs: fix backticks and add full description to Properties table

Changed 'object | null' to 'object' | 'null' in Type column for 'first' and 'last'.
Also added the missing node details to 'last' property description to match 'first'.

* test: fix forEach delete test title to reflect actual behavior

The test collects keys during forEach but deletes them afterward,
so it doesn't actually test mutation during iteration. Updated
title to clarify: 'should allow deleting items after collecting keys during iteration'.

* docs: fix noTTL description in keysByTTL() and sizeByTTL()

The noTTL property correctly identifies items where item.expiry === 0,
not where cache ttl === 0. Updated documentation to reflect this.

* fix(types): make items property return Record<any, LRUItem<T> | undefined>

This correctly reflects that items[key] returns undefined for missing keys,

* fix: validate onEvict callback is a function before storing

Prevents runtime error if onEvict() is called with undefined or non-function value.
The evict() method already checked #onEvict !== null, but that allows non-functions.

* fix: throw TypeError if onEvict callback is not a function

* test: add onEvict validation tests for non-function callbacks

* docs: update coverage metrics to 99.28% branches

* docs: add testing and coverage requirements to CODE_STYLE_GUIDE

* chore: build and update coverage metrics to 99.28% branches

* docs: fix clear() time complexity from O(1) to O(n)

clear() now iterates through linked list to nullify prev/next pointers,
allowing proper garbage collection of nodes.

* docs: fix stats() sets description to include setWithEvicted()

The sets counter increments in both set() and setWithEvicted() methods.
Updated documentation to reflect actual behavior.

* docs: Fix stats().deletes description

The delete count includes both explicit delete() calls AND internal
removal of expired items by get(). Update the documentation to reflect
this behavior accurately.

* docs: Remove nodei.co npm badge

Remove the redundant nodei.co npm badge which duplicated npm version
and downloads information already shown in the badges above.

* docs: Sort Properties and Methods alphabetically

- Properties: first, last, max, resetTtl, size, ttl
- Methods: clear, cleanup, delete, entries, evict, forEach, get, getMany,
  has, hasAll, hasAny, keys, keysByTTL, onEvict, peek, set, setWithEvicted,
  sizeByTTL, stats, toJSON, values, valuesByTTL, expiresAt

* docs: Sort Methods section alphabetically

Updated Methods table to be alphabetically sorted:
- cleanup, clear, delete, entries, evict, expiresAt, forEach, get,
  getMany, has, hasAll, hasAny, keys, keysByTTL, onEvict, peek,
  set, setWithEvicted, sizeByTTL, stats, toJSON, values, valuesByTTL

* docs: Update test counts to 149 tests across 26 suites

- Added test count to README.md Tests section

- Added test count to AGENTS.md Testing section

* docs: Remove GitHub stars badge from README

* docs: Fix lru-cache bundle size from 15 KB to 12 KB

* docs: Fix API.md inaccuracies

- cleanup() returns number, not  (documented in Method Chaining section)
- setWithEvicted() TTL reset behavior on updates with resetTtl=true
- values() example comment: 'respects LRU order' -> 'order matches input array'
- onEvict() parameter validation throws TypeError
- forEach() thisArg type: Object -> *
- entries() return type: Array<[string, *]> -> Array<(string|*)[]>

* docs: Clarify which build files are shipped via npm

- dist/tiny-lru.min.js is available in repo but not packaged for npm
- Only dist/tiny-lru.js, dist/tiny-lru.cjs, and types/lru.d.ts are shipped

* docs: Document getMany() side effects

- getMany() calls get() for each key
- Updates LRU order (items move to MRU position)
- Removes expired items (affects stats: hits, misses, deletes)
- Clarify this is not a read-only operation

* Rename resetTtl to resetTTL for consistent TTL naming

* docs: Fix entries() return type to specify 2-element tuple

* docs: fix valuesByTTL() noTTL description

Correctly state that noTTL contains items where expiry === 0, regardless of cache ttl setting

Author: avoidwork

.github/workflows/ci.yml

@@ -2,6 +2,9 @@
 name: ci
 
 on:
+  push:
+    branches:
+      - master
   pull_request:
     branches:
       - master

AGENTS.md

@@ -32,6 +32,9 @@ Source code is in `src/`.
 ├── tests/              # Test files
 ├── benchmarks/          # Performance benchmarks
 ├── dist/               # Built distribution files
+│   ├── tiny-lru.js     # ES Modules
+│   ├── tiny-lru.cjs    # CommonJS
+│   └── tiny-lru.min.js # Minified ESM
 ├── types/              # TypeScript definitions
 ├── docs/               # Documentation
 ├── rollup.config.js    # Build configuration
@@ -56,16 +59,19 @@ Source code is in `src/`.
 
 - `lru(max, ttl, resetTtl)` - Factory function to create cache
 - `LRU` class - Direct instantiation with `new LRU(max, ttl, resetTtl)`
-- Key methods: `get()`, `set()`, `delete()`, `has()`, `clear()`, `evict()`
+- Core methods: `get()`, `set()`, `peek()`, `delete()`, `has()`, `clear()`, `evict()`
 - Array methods: `keys()`, `values()`, `entries()`
+- Utility methods: `forEach()`, `getMany()`, `hasAll()`, `hasAny()`, `cleanup()`, `toJSON()`, `stats()`, `onEvict()`, `sizeByTTL()`, `keysByTTL()`, `valuesByTTL()`
 - Properties: `first`, `last`, `max`, `size`, `ttl`, `resetTtl`
+- `peek(key)` - Retrieve value without moving it (no LRU update, no TTL check)
 
 ## Testing
 
 - Framework: Node.js built-in test runner (`node --test`)
-- Coverage: 100%
+- Tests: 149 tests across 26 suites
+- Coverage: 100% lines, 99.28% branches, 100% functions
 - Test pattern: `tests/**/*.js`
-- All tests must pass with 100% coverage before merging
+- All tests must pass with 100% line coverage before merging
 - Run: `npm test` (lint + tests) or `npm run coverage` for coverage report
 
 ## Common Issues to Avoid