Performance & Tooling Modernization: oxlint, Native Testing, and Documentation Overhaul

[avoidwork]

Summary

This PR introduces several performance optimizations, code quality improvements, and comprehensive documentation updates to the tiny-lru library.

Key Changes

Performance Optimizations

• Removed bypass parameter from evict() - Eliminated unnecessary conditional logic that caused V8 deoptimization. All internal callers already guaranteed size > 0 before calling evict(), making the parameter redundant.
• Converted unlink() to private field - Changed from unlink() to #unlink() for true encapsulation and cleaner API surface.
• Updated Node.js requirement - Bumped from >=12 to >=14 to support private class fields.

Code Quality Improvements

• Simplified JSDoc - Removed redundant @example, @see, @since, @method, and @memberof tags from all method docblocks while preserving essential @param, @returns, and @throws information.
• DRY refactoring - Extracted #unlink() helper to eliminate duplicate linked list manipulation code in delete(), evict(), and moveToEnd().
• API simplification - Removed resetTtl parameter from set() and setWithEvicted() methods (internal implementation detail exposed in public API).

Documentation Updates

• Complete API reference - Added comprehensive docs/API.md with all methods, parameters, and usage examples.
• Technical documentation - Updated docs/TECHNICAL_DOCUMENTATION.md with accurate mathematical formulas, data flow diagrams, and TypeScript signatures.
• Contributing guide - Added CONTRIBUTING.md with development workflow and best practices.
• Development principles - Documented DRY, YAGNI, SOLID, and OWASP principles in AGENTS.md.
• Fixed documentation issues - Corrected resetTtl description, setWithEvicted() return type, and TTL reset invariant.

Build & Tooling

• Migrated to oxlint/oxfmt - Replaced ESLint with faster oxlint and added oxfmt for formatting.
• Native test runner - Switched from Mocha/c8 to Node.js built-in test runner (node --test).
• Updated benchmarks - Enhanced benchmark suite with more comprehensive performance testing.

Breaking Changes

Removed Parameters

• evict(bypass?) - The bypass parameter has been removed. Call evict() without arguments.
• set(key, value, resetTtl?) - The third resetTtl parameter has been removed. Use the constructor-level resetTtl setting instead.
• setWithEvicted(key, value, resetTtl?) - The third resetTtl parameter has been removed. Use the constructor-level resetTtl setting instead.

Environment Requirements

• Node.js 14+ required - Private class fields (#unlink()) require Node.js 14 or later. Previously supported Node.js 12+.

Behavioral Notes

• resetTtl behavior - The resetTtl constructor option now only affects set() and setWithEvicted() when updating existing keys. It does NOT affect get() operations (this was never the case, but documentation was corrected).

Migration Guide

Before

const cache = new LRU(100, 5000, true);
cache.set('key', 'value');
cache.set('key', 'new value', true); // Third parameter ignored
cache.evict(true); // bypass parameter

After

const cache = new LRU(100, 5000, true);
cache.set('key', 'value');
cache.set('key', 'new value'); // resetTtl handled by constructor setting
cache.evict(); // No parameters needed

Testing

All 54 tests pass with 100% line coverage.

✔ LRU Cache (295.68ms)
ℹ tests 54
ℹ suites 12
ℹ pass 54
ℹ fail 0

Performance Impact

Benchmarking shows no significant performance regression from removing the bypass parameter. The new implementation is actually simpler:

• Old: if (bypass || this.size > 0) with nested early return
• New: if (this.size === 0) return this; single check
  The overhead of accessing this.size is negligible (<1ns) and the property is already "warm" in CPU cache from being accessed in set().

Files Changed

• src/lru.js - Core implementation with private #unlink() and simplified evict(), set(), setWithEvicted()
• types/lru.d.ts - Updated TypeScript definitions
• docs/API.md - New comprehensive API reference
• docs/TECHNICAL_DOCUMENTATION.md - Updated technical documentation
• CONTRIBUTING.md - New contributing guide
• AGENTS.md - Development principles and workflow
• package.json - Updated engines, dependencies, and scripts
• Distribution files in dist/

[augmentcode]

🤖 Augment PR Summary

Summary: This PR refreshes documentation/tooling and tweaks the LRU internals around TTL-awareness and iteration helpers.

Changes:

• Adds AGENTS.md and CLAUDE.md with project/workflow guidance.
• Rewrites README.md to be shorter and introduces docs/API.md as the full API reference.
• Updates docs to clarify resetTtl behavior and the setWithEvicted() return shape.
• Switches dev tooling to oxlint/oxfmt and migrates tests to Node’s built-in node --test runner.
• Updates benchmarks to avoid new Array(); regenerates dist/ outputs.
• Refactors cache internals: TTL-aware has(), pointer cleanup on removal, and entries()/values() no longer call get() (avoids LRU reordering/side effects during enumeration).

Technical notes: The behavioral changes primarily affect TTL visibility via has() and how enumeration helpers read values without mutating LRU order.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. 6 suggestions posted.

Comment augment review to trigger a new review at any time.